dt-clean 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v1.1.1](https://github.com/ljharb/dt-clean/compare/v1.1.0...v1.1.1) - 2026-06-21
+
+### Commits
+
+- [Fix] `--setup`: never duplicate `dt-clean`, and converge on the preferred hook [`bc32122`](https://github.com/ljharb/dt-clean/commit/bc321229b54decfd6000e8d58d202604c36af206)
+- [Dev Deps] add `dt-clean` (self-reference) [`d1a6cdf`](https://github.com/ljharb/dt-clean/commit/d1a6cdf7de2c29d1a17858bf8febf4bd586253f6)
+
+## [v1.1.0](https://github.com/ljharb/dt-clean/compare/v1.0.1...v1.1.0) - 2026-06-21
+
+### Commits
+
+- [New] add `--auto`, meant for the `dependencies` lifecycle script [`bc60a91`](https://github.com/ljharb/dt-clean/commit/bc60a91bf4f3e4d0964f8dcb71d1b0d1182612f9)
+- [Tests] treat taken-down registry packages as skipped, not failures [`d020cc6`](https://github.com/ljharb/dt-clean/commit/d020cc62dd06de08189eebfe45e79a372ec8e5a1)
+- [meta] run `dt-clean --setup` [`459cc0c`](https://github.com/ljharb/dt-clean/commit/459cc0cc3a5a2b64e498946c8930ae49899eb8b3)
+
 ## [v1.0.1](https://github.com/ljharb/dt-clean/compare/v1.0.0...v1.0.1) - 2026-06-19
 
 ### Commits

package/README.md

@@ -47,8 +47,46 @@ With `--update` (`-u`), `dt-clean` edits `package.json` in place - adding, movin
 ### Options
 
 - `-u`, `--update`: apply the changes to `package.json` (default: report only).
+- `--setup`: idempotently wire `dt-clean --auto` into a `dependencies` lifecycle script, without overwriting any existing script (see [Automatic cleanup](#automatic-cleanup)).
+- `--auto`: for use in a `dependencies` lifecycle script - apply the changes like `--update` during `npm install`, but during `npm ci` only print what would change and exit `0` (see [Automatic cleanup](#automatic-cleanup)).
 - `--help`: show usage.
 
+### Automatic cleanup
+
+To keep your `@types/*` set tidy on every install, run `dt-clean --auto` from a [`dependencies` lifecycle script](https://docs.npmjs.com/cli/using-npm/scripts#npm-install) - the one npm's installer (arborist) runs after any operation that changes `node_modules`.
+
+The one-step way to set this up, in any project, is:
+
+```sh
+npx dt-clean --setup
+```
+
+`--setup` edits `package.json` for you and is safe to run anywhere:
+
+- if you have no `dependencies` script, it adds `"dependencies": "dt-clean --auto"`;
+- if you already have one, it adds `dt-clean --auto` to a free `postdependencies` (or `predependencies`) hook instead, so your existing script is never touched - and if every hook is taken, it appends `&& dt-clean --auto` to your `dependencies` script rather than clobbering it;
+- if it already added `dt-clean --auto` to a `post`/`pre` hook and the preferred `dependencies` slot later frees up, re-running moves it back to the most-preferred available hook;
+- if `dt-clean --auto` is already in the best available hook, it does nothing; and if some other `dt-clean` invocation (or a customized one you wrote) is already present, it leaves that alone rather than adding a duplicate.
+
+It only ever manages this one invocation and leaves the rest of your `package.json` (and its formatting) alone, so it's safe to re-run - repeated runs converge on the same result. That result is simply the equivalent of:
+
+```json
+{
+  "scripts": {
+    "dependencies": "dt-clean --auto"
+  }
+}
+```
+
+Once it's wired in, `dt-clean --auto` inspects `npm_command` to decide what to do:
+
+- under `npm install`, it applies the changes for you, so a fresh install keeps your `@types/*` set tidy automatically;
+- under `npm ci` (typically used in CI pipelines, where `package.json` must not be mutated), it only prints what would change and exits `0`, so it never edits a checked-in file and never fails the install.
+
+When `npm_command` is anything else (or absent), `--auto` applies the changes, exactly as under `npm install`.
+
+To avoid surprising edits, `--auto` runs *only* inside the `dependencies` lifecycle (or its `predependencies`/`postdependencies` hooks): it checks `npm_lifecycle_event`, and if it is invoked any other way (for example directly from the shell) it refuses to do anything and exits nonzero. Use `--update` to apply changes manually.
+
 ### Exit codes
 
 In the default report-only mode, the exit code is a bitmask of the kinds of pending changes, so a clean project exits `0` and you can fail CI (or a `git` pre-commit hook) on drift:

package/applyChanges.mjs

@@ -1,11 +1,7 @@
 import { join } from 'path';
 import { readFile, writeFile } from 'fs/promises';
 
-/** @param {string} raw */
-function detectIndent(raw) {
-	const match = (/^[ \t]+/m).exec(raw);
-	return match?.[0] ?? '\t';
-}
+import detectIndent from '#/detectIndent';
 
 /** @type {<K extends string, V>(obj: Record<K, V>) => Record<K, V>} */
 function sortKeys(obj) {

package/bin.mjs

@@ -8,20 +8,36 @@ import getDelTa from '#/getDelTa';
 import applyChanges from '#/applyChanges';
 import formatReport from '#/report';
 import exitCode from '#/exitCode';
+import setupScripts from '#/setup';
 
 const {
-	values: { json, update },
+	values: {
+		auto,
+		json,
+		setup,
+		update,
+	},
 	positionals,
 	help,
 } = await pargs(import.meta.filename, {
 	allowPositionals: 1,
 	description: 'Reports which DefinitelyTyped (`@types/*`) packages a project should add, move, or remove. By default it only reports; with `--update` it edits `package.json`.',
 	options: {
+		auto: {
+			default: false,
+			description: 'for a `dependencies` lifecycle script (or its `pre`/`post` hooks): apply the changes like `--update` during `npm install`, but during `npm ci` only print what would change and exit zero',
+			type: 'boolean',
+		},
 		json: {
 			default: false,
 			description: 'print the result as JSON on stdout (the human-readable report moves to stderr)',
 			type: 'boolean',
 		},
+		setup: {
+			default: false,
+			description: 'idempotently add `dt-clean --auto` to a `dependencies` lifecycle script in `package.json`, without overwriting any existing script',
+			type: 'boolean',
+		},
 		update: {
 			default: false,
 			description: 'apply the changes to `package.json`, then run `npm install` (or your package manager\'s equivalent)',
@@ -36,54 +52,87 @@ await help();
 
 const cwd = positionals.length > 0 ? resolve(positionals[0]) : process.cwd();
 
-const {
-	present,
-	toAdd,
-	toMove,
-	toRemain,
-	toRemove,
-} = await getDelTa(cwd);
+const { npm_command: npmCommand, npm_lifecycle_event: lifecycleEvent } = process.env;
 
-const report = formatReport({
-	present,
-	toAdd,
-	toMove,
-	toRemove,
-});
+// the `dependencies` lifecycle and its `pre`/`post` hooks are the only safe slots for `--auto`,
+// since npm runs them after a reify; `postdependencies`/`predependencies` let you add it without
+// clobbering an existing `dependencies` script.
+const DEPENDENCY_HOOKS = [
+	'predependencies',
+	'dependencies',
+	'postdependencies',
+];
 
-if (json) {
-	console.log(JSON.stringify({
-		present: Object.fromEntries(present),
-		toAdd: Object.fromEntries(toAdd),
-		toMove: Object.fromEntries(toMove),
-		toRemain: Array.from(toRemain),
-		toRemove,
-	}, null, '\t'));
-	console.error(report);
+if (setup) {
+	const { action, script } = await setupScripts(cwd);
+	console.log({
+		chained: `Appended \`dt-clean --auto\` to the existing \`${script}\` script in \`package.json\`.`,
+		exists: `\`${script}\` already invokes \`dt-clean\` (without \`--auto\`); leaving it unchanged - add \`--auto\` there yourself for install-time cleanup.`,
+		moved: `Moved \`dt-clean --auto\` to the preferred \`${script}\` script in \`package.json\`.`,
+		present: `\`${script}\` already runs \`dt-clean --auto\`; nothing to do.`,
+		set: `Added \`dt-clean --auto\` to the \`${script}\` script in \`package.json\`.`,
+	}[action]);
+} else if (auto && (!lifecycleEvent || !DEPENDENCY_HOOKS.includes(lifecycleEvent))) {
+	console.error('`--auto` only runs inside a `dependencies` (or `pre`/`postdependencies`) lifecycle script (see the README); use `--update` to apply changes manually.');
+	process.exitCode = 1;
 } else {
-	console.log(report);
-}
-
-if (update) {
-	// `--update` applies the changes, leaving the project clean, so a successful run exits zero;
-	// only an error (e.g. a failed write, which throws) yields a nonzero exit.
-	const changed = await applyChanges(cwd, {
+	const {
+		present,
 		toAdd,
 		toMove,
+		toRemain,
 		toRemove,
-	});
-	console.error(changed
-		? '\nUpdated `package.json`; run `npm install` (or your package manager’s equivalent) to sync.'
-		: '\nNo changes needed.');
-} else {
-	// report-only: the exit code is a bitmask of the pending change kinds, so a clean project exits zero.
-	const code = exitCode({
+	} = await getDelTa(cwd);
+
+	const report = formatReport({
+		present,
 		toAdd,
 		toMove,
 		toRemove,
 	});
-	process.exitCode = code;
-	if (code > 0) {
-		console.error('\nRe-run with `--update` (`-u`) to apply these changes to `package.json`.');
+
+	if (json) {
+		console.log(JSON.stringify({
+			present: Object.fromEntries(present),
+			toAdd: Object.fromEntries(toAdd),
+			toMove: Object.fromEntries(toMove),
+			toRemain: Array.from(toRemain),
+			toRemove,
+		}, null, '\t'));
+		console.error(report);
+	} else {
+		console.log(report);
+	}
+
+	if (update || (auto && npmCommand !== 'ci')) {
+		// `--update` applies the changes, leaving the project clean, so a successful run exits zero;
+		// only an error (e.g. a failed write, which throws) yields a nonzero exit.
+		const changed = await applyChanges(cwd, {
+			toAdd,
+			toMove,
+			toRemove,
+		});
+		console.error(changed
+			? '\nUpdated `package.json`; run `npm install` (or your package manager’s equivalent) to sync.'
+			: '\nNo changes needed.');
+	} else {
+		const code = exitCode({
+			toAdd,
+			toMove,
+			toRemove,
+		});
+		if (auto) {
+			// `--auto` under `npm ci`: leave the exit code at zero so a CI install never fails; the
+			// report above already lists what `npm install` would change.
+			if (code > 0) {
+				console.error('\n`npm ci` detected; `package.json` left unchanged. Run `npm install` or `dt-clean --update` to apply these changes.');
+			}
+		} else {
+			// report-only: the exit code is a bitmask of the pending change kinds, so a clean project exits zero.
+			process.exitCode = code;
+			if (code > 0) {
+				console.error('\nRe-run with `--update` (`-u`) to apply these changes to `package.json`.');
+			}
+		}
 	}
 }

package/detectIndent.d.ts

@@ -0,0 +1,3 @@
+declare function detectIndent(raw: string): string;
+
+export = detectIndent;

package/detectIndent.mjs

@@ -0,0 +1,5 @@
+/** @type {import('./detectIndent.d.ts')} */
+export default function detectIndent(raw) {
+	const match = (/^[ \t]+/m).exec(raw);
+	return match?.[0] ?? '\t';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dt-clean",
-	"version": "1.0.1",
+	"version": "1.1.1",
 	"description": "Ensures the only DefinitelyTyped (`@types`) packages you have installed are the ones you need",
 	"bin": "./bin.mjs",
 	"exports": {
@@ -23,7 +23,8 @@
 		"lint": "eslint .",
 		"posttest": "npx npm@'>= 10.2' audit --production",
 		"version": "auto-changelog && git add CHANGELOG.md",
-		"postversion": "auto-changelog && git add CHANGELOG.md && git commit --no-edit --amend && git tag -f \"v$(node -e \"console.log(require('./package.json').version)\")\""
+		"postversion": "auto-changelog && git add CHANGELOG.md && git commit --no-edit --amend && git tag -f \"v$(node -e \"console.log(require('./package.json').version)\")\"",
+		"dependencies": "dt-clean --auto"
 	},
 	"repository": {
 		"type": "git",
@@ -50,6 +51,7 @@
 		"@types/semver": "^7.7.1",
 		"auto-changelog": "^2.6.0",
 		"c8": "^11.0.0",
+		"dt-clean": "file:./",
 		"eslint": "^10.5.0",
 		"esmock": "^2.7.6",
 		"globals": "^17.6.0",

package/setup.d.ts

@@ -0,0 +1,12 @@
+declare function setup(cwd: string): Promise<setup.SetupResult>;
+
+declare namespace setup {
+    type DependencyHook = 'predependencies' | 'dependencies' | 'postdependencies';
+
+    type SetupResult = {
+        action: 'present' | 'exists' | 'set' | 'moved' | 'chained';
+        script: DependencyHook;
+    };
+}
+
+export = setup;

package/setup.mjs

@@ -0,0 +1,82 @@
+import { join } from 'path';
+import { readFile, writeFile } from 'fs/promises';
+
+import detectIndent from '#/detectIndent';
+
+/** @import { PackageJSON } from './types/types.d.ts' */
+/** @import { SetupResult } from './setup.d.ts' */
+
+const AUTO = 'dt-clean --auto';
+
+// listed most-preferred first: the `dependencies` event itself, then its `post`/`pre` hooks.
+const HOOKS = /** @type {const} */ ([
+	'dependencies',
+	'postdependencies',
+	'predependencies',
+]);
+
+/** @param {string | undefined} script */
+function hasAuto(script) {
+	// matches a `dt-clean … --auto` invocation confined to one `&&`/`;`/`|`-delimited segment
+	return typeof script === 'string' && (/\bdt-clean\b[^&|;]*--auto\b/).test(script);
+}
+
+/** @param {string | undefined} script */
+function hasDtClean(script) {
+	return typeof script === 'string' && (/\bdt-clean\b/).test(script);
+}
+
+/** @type {import('./setup.d.ts')} */
+export default async function setup(cwd) {
+	const packageJSONpath = join(cwd, 'package.json');
+	const raw = `${await readFile(packageJSONpath)}`;
+
+	/** @type {PackageJSON} */
+	const pkg = JSON.parse(raw);
+
+	/** @type {NonNullable<PackageJSON['scripts']>} */
+	const scripts = { ...pkg.scripts };
+
+	// a standalone `dt-clean --auto` we wrote ourselves, which we may therefore safely relocate.
+	const owned = HOOKS.find((hook) => scripts[hook] === AUTO);
+
+	if (!owned) {
+		// a `dt-clean --auto` we didn't write (chained or customized): leave it exactly as-is.
+		const wired = HOOKS.find((hook) => hasAuto(scripts[hook]));
+		if (wired) {
+			return { action: 'present', script: wired };
+		}
+		// some other `dt-clean` invocation: don't add a second one.
+		const existing = HOOKS.find((hook) => hasDtClean(scripts[hook]));
+		if (existing) {
+			return { action: 'exists', script: existing };
+		}
+	}
+
+	// the most-preferred hook our invocation should occupy: free, or already holding it.
+	const target = HOOKS.find((hook) => !scripts[hook] || scripts[hook] === AUTO);
+
+	if (owned && owned === target) {
+		return { action: 'present', script: owned };
+	}
+
+	/** @type {SetupResult} */
+	let result;
+	if (target) {
+		if (owned) {
+			// a more-preferred hook is now free: relocate to it.
+			delete scripts[owned];
+		}
+		scripts[target] = AUTO;
+		result = { action: owned ? 'moved' : 'set', script: target };
+	} else {
+		// every hook is occupied, so chain onto `dependencies` rather than clobber anything.
+		scripts.dependencies = `${scripts.dependencies} && ${AUTO}`;
+		result = { action: 'chained', script: 'dependencies' };
+	}
+
+	const next = { ...pkg, scripts };
+	await writeFile(packageJSONpath, `${JSON.stringify(next, null, detectIndent(raw))}\n`);
+
+	return result;
+}