@williamthorsen/nmr 0.17.0 → 0.17.2

package/README.md

@@ -3,13 +3,18 @@
 Context-aware script runner for PNPM monorepos. Ships 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.17.0 (2026-07-01)
+## Release notes — v0.17.2 (2026-07-06)
 
-### 🎉 Features
+### 🐛 Bug fixes
 
-- 🚨 **Breaking:** Rebuild nmr-compile on a unified tsc emit (#455)
+- Replace the raw attw script with an nmr-attw wrapper (#461)
 
-  `nmr` now compiles a package's JavaScript and type declarations in one step, rewriting every import form — static, re-export, dynamic `import()`, bare side-effect, and tsconfig `paths` aliases — to runnable `.js` in both outputs. It now requires TypeScript 5.7 or newer as a peer dependency.
+  Fixes the issues that made the default `nmr attw` check fail across monorepos:
+
+  - packages with no published API failed with a false `NoResolution` error;
+  - the check left stray `.tgz` files in the working tree ;
+  - output was a verbose per-package table; now output is terse on success, full diagnostics only on failure (`--verbose` to force full output);
+  - a missing `@arethetypeswrong/cli` gave a raw command-not-found; now a hint is given.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -141,7 +146,7 @@ These scripts are available out of the box. Repo-wide config (tier 2) and per-pa
 
 | Command         | Runs                                                             |
 | --------------- | ---------------------------------------------------------------- |
-| `attw`          | `attw --pack --profile esm-only`                                 |
+| `attw`          | `nmr-attw`                                                       |
 | `build`         | `compile`                                                        |
 | `check`         | `typecheck`, `fmt:check`, `lint:check`, `test`                   |
 | `check:strict`  | `typecheck`, `fmt:check`, `lint:strict`, `test:coverage`, `attw` |
@@ -345,7 +350,7 @@ nmr sync-pnpm-version
 
 ### `nmr-compile`
 
-Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` and `.d.ts` in one pass. Because the compiler parses each source file, every relative import form — static, re-export, dynamic `import()`, and bare side-effect — is rewritten from `.ts` to `.js` in both outputs, and `.ts` occurrences inside strings and comments are left intact. tsconfig `paths` aliases are resolved to runnable relative `.js` specifiers in both outputs, sourced from the package's tsconfig. The build is skipped when no input has changed (a content-and-path hash is cached in `dist/esm/.cache`). This is the default `compile` script — run it from a package directory.
+Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler API, emitting `.js` and `.d.ts` in one pass. Because the compiler parses each source file, every relative import form — static, re-export, dynamic `import()`, and bare side-effect — is rewritten from `.ts` to `.js` in both outputs, and `.ts` occurrences inside strings and comments are left intact. tsconfig `paths` aliases are resolved to runnable relative `.js` specifiers in both outputs, sourced from the package's tsconfig. The build is skipped when no input has changed (a content-and-path hash is cached under `node_modules/.cache/nmr-compile/`, outside the published output). This is the default `compile` script — run it from a package directory.
 
 `typescript` is a peer dependency (`>=5.7.0`, required for `rewriteRelativeImportExtensions`); the consuming repo provides it. Relative imports in source must carry explicit `.ts` extensions for them to be rewritten.
 
@@ -353,6 +358,20 @@ Compile a single package's `src` tree to `dist/esm` with the TypeScript compiler
 nmr-compile
 ```
 
+### `nmr-attw`
+
+Validate a package's published type-resolution surface with [`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io). This is the default `attw` script — run it from a package directory. It wraps attw so that it behaves well across a monorepo:
+
+- **Skips packages with no publishable entry point** (neither `main` nor `exports`) — a message and exit 0, before attw runs. A package with no importable surface has nothing for attw to resolve, so running it would false-positive with `NoResolution`. A private package that _does_ declare `exports` is still checked.
+- **Leaves no `.tgz` in the working tree.** attw analyzes a packed tarball; nmr-attw packs into a temp directory instead of the package directory, so nothing litters the tree.
+- **Condenses output** to a terse per-package result on success and full attw diagnostics only on failure. Pass `--verbose` to print the full attw output on success too.
+
+`@arethetypeswrong/cli` is not bundled — a package that declares an entry point must have it installed; nmr-attw reports an actionable message if it is missing. Any other flags are forwarded to attw (the profile defaults to `esm-only`).
+
+```bash
+nmr-attw
+```
+
 ### `ensure-prepublish-hooks`
 
 Verify that all publishable workspace packages have a `prepublishOnly` script. Exits non-zero if any are missing.

package/bin/nmr-attw.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+try {
+  await import('../dist/esm/cli-attw.js');
+} catch (error) {
+  if (error.code === 'ERR_MODULE_NOT_FOUND') {
+    process.stderr.write('nmr-attw: build output not found — run `pnpm run build` first\n');
+  } else {
+    process.stderr.write(`nmr-attw: failed to load: ${error.message}\n`);
+  }
+  process.exit(1);
+}

package/dist/esm/cli-attw.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/cli-attw.js

@@ -0,0 +1,15 @@
+import { reportError } from '@williamthorsen/nmr-core';
+import { runAttw } from "./commands/attw.js";
+try {
+    process.exitCode = runAttw({
+        packageDir: process.cwd(),
+        argv: process.argv.slice(2),
+        stdout: process.stdout,
+        stderr: process.stderr,
+        env: process.env,
+    });
+}
+catch (error) {
+    reportError(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

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

@@ -0,0 +1,34 @@
+import { type SpawnSyncReturns } from 'node:child_process';
+import type { Writable } from 'node:stream';
+export type SpawnSyncFn = (command: string, args: string[], options: {
+    cwd: string;
+    encoding: 'utf8';
+    env: NodeJS.ProcessEnv;
+}) => Pick<SpawnSyncReturns<string>, 'error' | 'status' | 'stdout' | 'stderr'>;
+export interface RunAttwOptions {
+    packageDir: string;
+    argv: string[];
+    stdout: Writable;
+    stderr: Writable;
+    env: NodeJS.ProcessEnv;
+    spawn?: SpawnSyncFn;
+}
+export declare function runAttw(options: RunAttwOptions): number;
+export declare function buildAttwArgs(argv: string[]): {
+    verbose: boolean;
+    attwArgs: string[];
+};
+interface AttwOutcome {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function formatAttwResult(params: {
+    label: string;
+    verbose: boolean;
+    attwStatus: number | null;
+    attwStdout: string;
+    attwStderr: string;
+}): AttwOutcome;
+export declare function attwSpawnErrorMessage(label: string, error: Error): string;
+export {};

package/dist/esm/commands/attw.js

@@ -0,0 +1,87 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { hasPublishableEntryPoint, readPackageJson } from "../helpers/package-json.js";
+const DEFAULT_PROFILE = 'esm-only';
+export function runAttw(options) {
+    const { packageDir, argv, stdout, stderr, env } = options;
+    const spawn = options.spawn ?? ((command, args, spawnOptions) => spawnSync(command, args, spawnOptions));
+    const pkg = readPackageJson(packageDir);
+    const label = pkg.name ?? path.basename(packageDir);
+    if (!hasPublishableEntryPoint(pkg)) {
+        stdout.write(`⛔ ${label}: No publishable entry point (no "main"/"exports"). Skipping attw.\n`);
+        return 0;
+    }
+    const { verbose, attwArgs } = buildAttwArgs(argv);
+    const tempDir = mkdtempSync(path.join(tmpdir(), 'nmr-attw-'));
+    try {
+        const pack = spawn('npm', ['pack', '--pack-destination', tempDir], { cwd: packageDir, encoding: 'utf8', env });
+        if (pack.error !== undefined) {
+            stderr.write(`nmr-attw: npm pack failed for ${label}: ${pack.error.message}\n`);
+            return 1;
+        }
+        if (pack.status !== 0) {
+            stderr.write(pack.stderr || `nmr-attw: npm pack failed for ${label}\n`);
+            return pack.status ?? 1;
+        }
+        const tarball = readdirSync(tempDir).find((file) => file.endsWith('.tgz'));
+        if (tarball === undefined) {
+            stderr.write(`nmr-attw: npm pack produced no tarball for ${label}\n`);
+            return 1;
+        }
+        const attw = spawn('attw', [path.join(tempDir, tarball), ...attwArgs], {
+            cwd: packageDir,
+            encoding: 'utf8',
+            env,
+        });
+        if (attw.error !== undefined) {
+            stderr.write(attwSpawnErrorMessage(label, attw.error));
+            return 1;
+        }
+        const outcome = formatAttwResult({
+            label,
+            verbose,
+            attwStatus: attw.status,
+            attwStdout: attw.stdout,
+            attwStderr: attw.stderr,
+        });
+        if (outcome.stdout)
+            stdout.write(outcome.stdout);
+        if (outcome.stderr)
+            stderr.write(outcome.stderr);
+        return outcome.status;
+    }
+    finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+export function buildAttwArgs(argv) {
+    let verbose = false;
+    const attwArgs = [];
+    for (const arg of argv) {
+        if (arg === '--verbose' || arg === '-v') {
+            verbose = true;
+            continue;
+        }
+        attwArgs.push(arg);
+    }
+    if (!attwArgs.some((arg) => arg === '--profile' || arg.startsWith('--profile='))) {
+        attwArgs.push('--profile', DEFAULT_PROFILE);
+    }
+    return { verbose, attwArgs };
+}
+export function formatAttwResult(params) {
+    const { label, verbose, attwStatus, attwStdout, attwStderr } = params;
+    const status = attwStatus ?? 1;
+    if (status === 0 && !verbose) {
+        return { status: 0, stdout: `✓ ${label}: types OK\n`, stderr: '' };
+    }
+    return { status, stdout: attwStdout, stderr: attwStderr };
+}
+export function attwSpawnErrorMessage(label, error) {
+    if ('code' in error && error.code === 'ENOENT') {
+        return `⚠ ${label}: attw not found — install @arethetypeswrong/cli to validate published types.\n`;
+    }
+    return `nmr-attw: failed to run attw for ${label}: ${error.message}\n`;
+}

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

@@ -2,8 +2,8 @@ export interface BuildOptions {
     entryGlobs?: string[];
     ignore?: string[];
     outdir?: string;
-    cacheFile?: string;
 }
 export declare function buildPackage(packageDir: string, options?: BuildOptions): Promise<void>;
 export declare function computeBuildHash(packageDir: string, files: string[], emitConfig: object): Promise<string>;
 export declare function resolveTsconfigChain(packageDir: string, configFileName?: string): string[];
+export declare function resolveBuildCachePath(packageDir: string): string;

package/dist/esm/commands/build.js

@@ -9,7 +9,6 @@ const SKIPPED_ICON = '⏭️';
 const DEFAULT_ENTRY_GLOBS = ['src/**/*.ts'];
 const DEFAULT_IGNORE = ['**/__tests__/**'];
 const DEFAULT_OUTDIR = 'dist/esm/';
-const DEFAULT_CACHE_FILE = 'dist/esm/.cache';
 const SOURCE_ROOT = 'src';
 const MINIMUM_TYPESCRIPT_MAJOR = 5;
 const MINIMUM_TYPESCRIPT_MINOR = 7;
@@ -17,7 +16,7 @@ const TS_EXTENSION = '.ts';
 const JS_EXTENSION = '.js';
 export async function buildPackage(packageDir, options = {}) {
     assertSupportedTypeScript();
-    const cacheFile = options.cacheFile ?? DEFAULT_CACHE_FILE;
+    const cachePath = resolveBuildCachePath(packageDir);
     const outdir = options.outdir ?? DEFAULT_OUTDIR;
     const emitConfig = { outdir, declaration: true, rewriteRelativeImportExtensions: true };
     const entryPoints = await glob(options.entryGlobs ?? DEFAULT_ENTRY_GLOBS, {
@@ -25,12 +24,12 @@ export async function buildPackage(packageDir, options = {}) {
         ignore: options.ignore ?? DEFAULT_IGNORE,
     });
     const dependencies = ['package.json', ...resolveTsconfigChain(packageDir)];
-    const { changed, currentHash } = await detectBuildChanges(packageDir, [...entryPoints, ...dependencies], emitConfig, cacheFile);
+    const { changed, currentHash } = await detectBuildChanges(packageDir, [...entryPoints, ...dependencies], emitConfig, cachePath);
     if (!changed) {
         return;
     }
     emitPackage(packageDir, entryPoints, outdir);
-    await writeBuildCache(packageDir, cacheFile, currentHash);
+    await writeBuildCache(cachePath, currentHash);
 }
 export async function computeBuildHash(packageDir, files, emitConfig) {
     const hash = createHash('sha256');
@@ -181,9 +180,27 @@ function getModuleSpecifier(node) {
     }
     return undefined;
 }
-async function detectBuildChanges(packageDir, files, emitConfig, cacheFile) {
+export function resolveBuildCachePath(packageDir) {
+    const absolutePackageDir = path.resolve(packageDir);
+    const home = findNearestNodeModulesHost(absolutePackageDir) ?? absolutePackageDir;
+    const digest = createHash('sha256').update(absolutePackageDir).digest('hex').slice(0, 8);
+    const key = `${path.basename(absolutePackageDir)}-${digest}.hash`;
+    return path.join(home, 'node_modules', '.cache', 'nmr-compile', key);
+}
+function findNearestNodeModulesHost(startDir) {
+    let current = startDir;
+    let parent = path.dirname(current);
+    while (!existsSync(path.join(current, 'node_modules'))) {
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+        parent = path.dirname(current);
+    }
+    return current;
+}
+async function detectBuildChanges(packageDir, files, emitConfig, cachePath) {
     const packageName = path.basename(packageDir);
-    const cachePath = path.join(packageDir, cacheFile);
     const previousHash = existsSync(cachePath) ? readFileSync(cachePath, 'utf8') : undefined;
     const currentHash = await computeBuildHash(packageDir, files, emitConfig);
     if (previousHash === currentHash) {
@@ -193,8 +210,7 @@ async function detectBuildChanges(packageDir, files, emitConfig, cacheFile) {
     console.info(`${PACKAGE_ICON} ${packageName}: Changes detected.`);
     return { changed: true, currentHash };
 }
-async function writeBuildCache(packageDir, cacheFile, hash) {
-    const cachePath = path.join(packageDir, cacheFile);
+async function writeBuildCache(cachePath, hash) {
     await mkdir(path.dirname(cachePath), { recursive: true });
     await writeFile(cachePath, hash);
 }

package/dist/esm/default-scripts.js

@@ -1,5 +1,5 @@
 export const commonWorkspaceScripts = {
-    attw: 'attw --pack --profile esm-only',
+    attw: 'nmr-attw',
     build: ['compile'],
     check: ['typecheck', 'fmt:check', 'lint:check', 'test'],
     'check:strict': ['typecheck', 'fmt:check', 'lint:strict', 'test:coverage', 'attw'],

package/dist/esm/helpers/package-json.d.ts

@@ -3,10 +3,13 @@ export interface PackageJson {
     private?: boolean;
     version?: string;
     packageManager?: string;
+    main?: string;
+    exports?: unknown;
     scripts?: Record<string, string>;
     pnpm?: {
         overrides?: Record<string, string>;
     };
 }
 export declare function readPackageJson(dir: string): PackageJson;
+export declare function hasPublishableEntryPoint(pkg: PackageJson): boolean;
 export declare function getPnpmOverrides(pkg: PackageJson): Record<string, string> | undefined;

package/dist/esm/helpers/package-json.js

@@ -16,6 +16,10 @@ export function readPackageJson(dir) {
         pkg.version = parsed.version;
     if (typeof parsed.packageManager === 'string')
         pkg.packageManager = parsed.packageManager;
+    if (typeof parsed.main === 'string')
+        pkg.main = parsed.main;
+    if (parsed.exports !== undefined)
+        pkg.exports = parsed.exports;
     if (isObject(parsed.scripts)) {
         const scripts = {};
         for (const [key, val] of Object.entries(parsed.scripts)) {
@@ -37,6 +41,9 @@ export function readPackageJson(dir) {
     }
     return pkg;
 }
+export function hasPublishableEntryPoint(pkg) {
+    return pkg.main !== undefined || pkg.exports !== undefined;
+}
 export function getPnpmOverrides(pkg) {
     if (!isObject(pkg.pnpm))
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/nmr",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "private": false,
   "description": "Context-aware script runner for PNPM monorepos",
   "keywords": [
@@ -29,6 +29,7 @@
   "bin": {
     "ensure-prepublish-hooks": "bin/ensure-prepublish-hooks.js",
     "nmr": "bin/nmr.js",
+    "nmr-attw": "bin/nmr-attw.js",
     "nmr-compile": "bin/nmr-compile.js",
     "nmr-report-overrides": "bin/nmr-report-overrides.js",
     "nmr-sync-agent-files": "bin/nmr-sync-agent-files.js",

package/dist/esm/.cache

@@ -1 +0,0 @@
-49f79592247d14646b1445473aa445a8bcbeafb478c6dc9949eb31cee8e2a627