@rtorcato/js-tooling 2.18.0 → 2.19.1

package/README.md

@@ -17,12 +17,65 @@ Most tooling libraries give you one piece — just TypeScript configs, or just a
 
 **[Full documentation →](https://rtorcato.github.io/js-tooling/)**
 
-## Quick start
+## Start a new project
+
+Interactive wizard — answers every prompt, scaffolds the whole project:
 
 ```bash
 npx @rtorcato/js-tooling setup
 ```
 
+Non-interactive — scaffold from a named preset in one shot (CI-friendly):
+
+```bash
+npx @rtorcato/js-tooling setup --preset library -d ./my-lib --skip-install
+# presets: library | web-app | node-api | nextjs-app | react-app
+```
+
+Just one config file? Use `copy`:
+
+```bash
+npx @rtorcato/js-tooling copy biome        # → biome.json
+npx @rtorcato/js-tooling copy tsconfig     # → tsconfig.json
+npx @rtorcato/js-tooling copy changesets   # → .changeset/config.json
+npx @rtorcato/js-tooling copy oxlint       # → .oxlintrc.json
+npx @rtorcato/js-tooling copy claude-skill # → .claude/skills/js-tooling.md
+```
+
+**Already have a project?** Don't rerun `setup` — use `doctor` + `fix`:
+
+```bash
+npx @rtorcato/js-tooling doctor   # find what's missing or drifted
+npx @rtorcato/js-tooling fix      # apply scaffolders, prompting per item
+```
+
+See the [Getting Started guide](https://rtorcato.github.io/js-tooling/guides/getting-started/) for the full walkthrough.
+
+## AI agent rules
+
+The package ships rules that teach AI coding agents to drive the CLI
+(`doctor` / `fix` / `setup`) non-interactively. Install for your agent — all
+generated from one source, so guidance never drifts between them:
+
+```bash
+npx @rtorcato/js-tooling fix claude-skill --yes           # → .claude/skills/js-tooling.md
+npx @rtorcato/js-tooling fix cursor-rules --yes           # → .cursor/rules/js-tooling.mdc
+npx @rtorcato/js-tooling fix copilot-instructions --yes   # → .github/copilot-instructions.md
+npx @rtorcato/js-tooling fix agents-md --yes              # → AGENTS.md
+```
+
+`copilot-instructions` and `agents-md` upsert a delimited block, so your own
+content in those shared files is never clobbered. Re-running updates the block
+in place on upgrade.
+
+Prefer a symlink that auto-syncs the Claude skill on every upgrade?
+
+```bash
+mkdir -p .claude/skills
+ln -sf ../../node_modules/@rtorcato/js-tooling/tooling/claude/js-tooling.md \
+  .claude/skills/js-tooling.md
+```
+
 ## What's new
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.

package/dist/cli/commands/doctor.js

@@ -716,28 +716,28 @@ async function checkAreTheTypesWrong(_dir, pkg) {
         ...(pkg?.devDependencies ?? {}),
     };
     const scripts = pkg?.scripts ?? {};
-    const hasDep = !!deps['are-the-types-wrong'];
-    const hasScript = Object.values(scripts).some((s) => /\battw\b|are-the-types-wrong/.test(s));
+    const hasDep = !!deps['@arethetypeswrong/cli'];
+    const hasScript = Object.values(scripts).some((s) => /\battw\b/.test(s));
     if (hasDep && hasScript) {
         return {
             check: 'are-the-types-wrong',
             status: 'ok',
-            detail: 'are-the-types-wrong installed and wired into a script',
+            detail: '@arethetypeswrong/cli installed and wired into a script',
         };
     }
     if (hasDep) {
         return {
             check: 'are-the-types-wrong',
             status: 'drift',
-            detail: 'are-the-types-wrong installed but no script runs it',
-            hint: 'Add `"attw": "attw --pack"` to package.json scripts and call it from your verify/CI chain',
+            detail: '@arethetypeswrong/cli installed but no script runs it',
+            hint: 'Run `npx @rtorcato/js-tooling fix attw` to add an `attw` script and wire it into verify',
         };
     }
     return {
         check: 'are-the-types-wrong',
         status: 'optional-missing',
-        detail: 'are-the-types-wrong not configured',
-        hint: 'Run `pnpm add -D are-the-types-wrong && attw --pack` to validate TypeScript exports before publishing',
+        detail: '@arethetypeswrong/cli not configured',
+        hint: 'Run `npx @rtorcato/js-tooling fix attw` to validate TypeScript exports before publishing',
     };
 }
 async function checkTreeshakeSetup(dir, pkg) {

package/dist/cli/commands/fix.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { createPatch } from 'diff';
 import fs from 'fs-extra';
 import inquirer from 'inquirer';
+import { installAgentRules } from '../generators/agent-rules.js';
 import { generateSemanticReleaseConfig } from '../generators/build.js';
 import { generateCommitlintConfig, generateHuskyConfig, generatePrePushHook, } from '../generators/git.js';
 import { generateGitHubActions } from '../generators/github-actions.js';
@@ -59,6 +60,24 @@ async function readPackageJson(dir) {
         return null;
     }
 }
+/** True when any (possibly nested) exports condition declares a `require`/CJS entry. */
+function hasRequireCondition(exports) {
+    if (!exports || typeof exports !== 'object')
+        return false;
+    for (const value of Object.values(exports)) {
+        if (value && typeof value === 'object') {
+            if ('require' in value)
+                return true;
+            if (hasRequireCondition(value))
+                return true;
+        }
+    }
+    return false;
+}
+/** ESM-only = `"type": "module"` and no CJS/`require` resolution in exports. */
+function isEsmOnly(pkg) {
+    return pkg.type === 'module' && !hasRequireCondition(pkg.exports);
+}
 const FIXERS = [
     {
         target: 'biome',
@@ -408,6 +427,86 @@ const FIXERS = [
             return { filesWritten };
         },
     },
+    {
+        target: 'attw',
+        description: 'Install @arethetypeswrong/cli + add an `attw` script (esm-only profile when applicable) and wire it into verify',
+        appliesTo: ['are-the-types-wrong'],
+        outputs: ['package.json (devDependencies + scripts.attw)'],
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir, pkg }) {
+            const pkgPath = path.join(targetDir, 'package.json');
+            if (!pkg) {
+                console.log(chalk.yellow('   no package.json found — skipping'));
+                return { filesWritten: [] };
+            }
+            const updated = { ...pkg };
+            const devDeps = {
+                ...(updated.devDependencies ?? {}),
+            };
+            if (!devDeps['@arethetypeswrong/cli'])
+                devDeps['@arethetypeswrong/cli'] = '^0.18.2';
+            updated.devDependencies = devDeps;
+            const scripts = { ...(updated.scripts ?? {}) };
+            scripts.attw = isEsmOnly(pkg) ? 'attw --pack --profile esm-only' : 'attw --pack';
+            if (scripts.verify && !/\battw\b/.test(scripts.verify)) {
+                scripts.verify = `${scripts.verify} && pnpm attw`;
+            }
+            updated.scripts = scripts;
+            await fs.writeJson(pkgPath, updated, { spaces: 2 });
+            return { filesWritten: ['package.json'] };
+        },
+    },
+    {
+        target: 'claude-skill',
+        description: 'Install the js-tooling Claude Code skill into .claude/skills/',
+        appliesTo: ['Claude skill'],
+        outputs: ['.claude/skills/js-tooling.md'],
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('claude-skill', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'cursor-rules',
+        description: 'Install the js-tooling rules for Cursor (.cursor/rules/js-tooling.mdc)',
+        appliesTo: ['Cursor rules'],
+        outputs: ['.cursor/rules/js-tooling.mdc'],
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const written = await installAgentRules(targetDir, 'cursor');
+            return { filesWritten: [written] };
+        },
+    },
+    {
+        target: 'copilot-instructions',
+        description: 'Install the js-tooling rules for GitHub Copilot (.github/copilot-instructions.md)',
+        appliesTo: ['Copilot instructions'],
+        outputs: ['.github/copilot-instructions.md'],
+        // Upserts a delimited block — never clobbers the consumer's own instructions.
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const written = await installAgentRules(targetDir, 'copilot');
+            return { filesWritten: [written] };
+        },
+    },
+    {
+        target: 'agents-md',
+        description: 'Install the js-tooling rules into AGENTS.md (universal agent instructions)',
+        appliesTo: ['AGENTS.md rules'],
+        outputs: ['AGENTS.md'],
+        // Upserts a delimited block — never clobbers existing AGENTS.md content.
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const written = await installAgentRules(targetDir, 'agents-md');
+            return { filesWritten: [written] };
+        },
+    },
     {
         target: 'package-json',
         description: 'Add @rtorcato/js-tooling to devDependencies',

package/dist/cli/generators/agent-rules.js

@@ -0,0 +1,67 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { getPackageRoot } from '../utils/copy-preset.js';
+/**
+ * All agent rule files are generated from one source of truth — the shipped
+ * Claude skill — so the guidance never drifts between agents. Only the
+ * location and the frontmatter differ per agent.
+ */
+const SOURCE = 'tooling/claude/js-tooling.md';
+const BLOCK_START = '<!-- js-tooling:start -->';
+const BLOCK_END = '<!-- js-tooling:end -->';
+/** Read the shipped skill and split its frontmatter from the markdown body. */
+async function readSkill() {
+    const raw = await fs.readFile(path.join(getPackageRoot(), SOURCE), 'utf8');
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!match)
+        return { description: '', body: raw.trim() };
+    const description = (match[1].match(/^description:\s*(.+)$/m)?.[1] ?? '').trim();
+    return { description, body: match[2].trim() };
+}
+/**
+ * Upsert a delimited js-tooling block into a file that may already hold the
+ * consumer's own content (AGENTS.md, copilot-instructions). Replaces an
+ * existing block, appends if the file exists without one, creates otherwise.
+ * Never clobbers surrounding content.
+ */
+async function upsertBlock(filePath, body) {
+    const block = `${BLOCK_START}\n${body}\n${BLOCK_END}`;
+    if (await fs.pathExists(filePath)) {
+        const existing = await fs.readFile(filePath, 'utf8');
+        const start = existing.indexOf(BLOCK_START);
+        const end = existing.indexOf(BLOCK_END);
+        if (start !== -1 && end !== -1) {
+            const next = existing.slice(0, start) + block + existing.slice(end + BLOCK_END.length);
+            await fs.writeFile(filePath, next);
+            return;
+        }
+        await fs.writeFile(filePath, `${existing.trimEnd()}\n\n${block}\n`);
+        return;
+    }
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, `${block}\n`);
+}
+/** Install the js-tooling rules for one agent. Returns the written path (relative). */
+export async function installAgentRules(targetDir, agent) {
+    const { description, body } = await readSkill();
+    switch (agent) {
+        case 'cursor': {
+            const rel = path.join('.cursor', 'rules', 'js-tooling.mdc');
+            const file = path.join(targetDir, rel);
+            const frontmatter = `---\ndescription: ${description}\nglobs:\nalwaysApply: false\n---\n\n`;
+            await fs.ensureDir(path.dirname(file));
+            await fs.writeFile(file, `${frontmatter}${body}\n`);
+            return rel;
+        }
+        case 'copilot': {
+            const rel = path.join('.github', 'copilot-instructions.md');
+            await upsertBlock(path.join(targetDir, rel), body);
+            return rel;
+        }
+        case 'agents-md': {
+            const rel = 'AGENTS.md';
+            await upsertBlock(path.join(targetDir, rel), body);
+            return rel;
+        }
+    }
+}

package/dist/cli/generators/git.js

@@ -57,19 +57,15 @@ npx --no -- commitlint --edit $1
     // lint-staged configuration in package.json
     const packageJsonPath = path.join(targetDir, 'package.json');
     const packageJson = await fs.readJson(packageJsonPath);
+    // No explicit `git add` — lint-staged stages tool output itself, and the
+    // extra add races its index lock. `--no-errors-on-unmatched` keeps biome
+    // from failing a commit when every matched file is biome-ignored.
+    const useBiome = config.linting.tool === 'biome' || config.linting.tool === 'both';
     packageJson['lint-staged'] = {
-        '*.{js,ts,jsx,tsx}': [
-            config.linting.tool === 'biome' || config.linting.tool === 'both'
-                ? 'biome check --fix'
-                : 'eslint --fix',
-            'git add',
-        ],
-        '*.{json,md,yml,yaml}': [
-            config.linting.tool === 'biome' || config.linting.tool === 'both'
-                ? 'biome format --write'
-                : 'prettier --write',
-            'git add',
-        ],
+        '*.{js,ts,jsx,tsx}': useBiome ? 'biome check --fix --no-errors-on-unmatched' : 'eslint --fix',
+        '*.{json,md,yml,yaml}': useBiome
+            ? 'biome format --write --no-errors-on-unmatched'
+            : 'prettier --write',
     };
     await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
 }

package/dist/cli/generators/github-actions.js

@@ -53,7 +53,7 @@ jobs:
       - name: 📦 Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: .nvmrc
 
       - name: 📦 Setup pnpm
         uses: pnpm/action-setup@v4
@@ -88,7 +88,7 @@ jobs:
       - name: 📦 Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: .nvmrc
 
       - name: 📦 Setup pnpm
         uses: pnpm/action-setup@v4
@@ -118,7 +118,7 @@ ${hasTypeScript
       - name: 📦 Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: .nvmrc
 
       - name: 📦 Setup pnpm
         uses: pnpm/action-setup@v4
@@ -149,7 +149,7 @@ ${hasTests
       - name: 📦 Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: .nvmrc
 
       - name: 📦 Setup pnpm
         uses: pnpm/action-setup@v4
@@ -180,7 +180,7 @@ ${hasBuild
       - name: 📦 Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: .nvmrc
 
       - name: 📦 Setup pnpm
         uses: pnpm/action-setup@v4
@@ -229,7 +229,7 @@ ${isLibrary && config.semanticRelease
       - name: 📦 Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: .nvmrc
           registry-url: 'https://registry.npmjs.org'
 
       - name: 📦 Setup pnpm

package/dist/cli/generators/linting.js

@@ -27,13 +27,13 @@ export async function generateOxlintConfig(targetDir) {
 }
 export async function generateBiomeConfig(targetDir) {
     const biomeConfigPath = path.join(targetDir, 'biome.jsonc');
+    // Biome 2.x schema + shape. The base preset (extends) already defines the
+    // file globs via `files.includes`; emitting the old 1.x `include`/`ignore`
+    // keys here forced consumers to run `biome migrate` before `biome check`
+    // would run at all.
     const biomeConfig = {
-        $schema: 'https://biomejs.dev/schemas/1.9.4/schema.json',
+        $schema: 'https://biomejs.dev/schemas/2.3.0/schema.json',
         extends: ['@rtorcato/js-tooling/biome'],
-        files: {
-            include: ['src/**/*', '*.ts', '*.js', '*.tsx', '*.jsx'],
-            ignore: ['node_modules', 'dist', 'build', '.next'],
-        },
     };
     await fs.writeJson(biomeConfigPath, biomeConfig, { spaces: 2 });
 }

package/dist/cli/generators/package-json.js

@@ -26,16 +26,22 @@ export async function generatePackageJson(config, targetDir) {
             ...existingPackageJson?.devDependencies,
         },
     };
-    // Add additional package.json fields based on project type
+    // Add additional package.json fields based on project type.
+    // Exports must match tsup's output for a "type": "module" package with
+    // format: ['cjs','esm']: ESM → index.js, CJS → index.cjs, types →
+    // index.d.ts (ESM) / index.d.cts (CJS).
     if (config.projectType === 'library') {
-        packageJson.main = './dist/index.js';
-        packageJson.module = './dist/index.mjs';
+        packageJson.main = './dist/index.cjs';
+        packageJson.module = './dist/index.js';
         packageJson.types = './dist/index.d.ts';
         packageJson.exports = {
             '.': {
-                import: './dist/index.mjs',
-                require: './dist/index.js',
-                types: './dist/index.d.ts',
+                types: {
+                    import: './dist/index.d.ts',
+                    require: './dist/index.d.cts',
+                },
+                import: './dist/index.js',
+                require: './dist/index.cjs',
             },
         };
         packageJson.files = ['dist'];
@@ -43,6 +49,15 @@ export async function generatePackageJson(config, targetDir) {
             access: 'public',
         };
     }
+    // pnpm 11 refuses to run a dependency's build script unless it's approved.
+    // esbuild (pulled in by tsup/esbuild/vite) has one, so `pnpm install` exits
+    // 1 with ERR_PNPM_IGNORED_BUILDS until it's whitelisted here.
+    if (config.bundler === 'tsup' || config.bundler === 'esbuild' || config.bundler === 'vite') {
+        packageJson.pnpm = {
+            ...packageJson.pnpm,
+            onlyBuiltDependencies: ['esbuild'],
+        };
+    }
     await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
 }
 function getScripts(config, opts = {}) {
@@ -213,10 +228,14 @@ function getDependencies(config) {
         deps['@commitlint/cli'] = '^20.0.0';
         deps['@commitlint/config-conventional'] = '^20.0.0';
     }
-    // Semantic release
+    // Semantic release. The shipped github preset activates the changelog and
+    // git plugins (and @semantic-release/github), so they must be installed too
+    // or `semantic-release` crashes with "Cannot find module".
     if (config.semanticRelease) {
         deps['semantic-release'] = '^25.0.0';
         deps['@semantic-release/github'] = '^12.0.0';
+        deps['@semantic-release/changelog'] = '^6.0.0';
+        deps['@semantic-release/git'] = '^10.0.0';
     }
     return deps;
 }

package/dist/cli/utils/copy-preset.js

@@ -21,6 +21,11 @@ export const PRESETS = {
         target: 'tsconfig.json',
         desc: 'TypeScript base configuration',
     },
+    'claude-skill': {
+        source: 'tooling/claude/js-tooling.md',
+        target: '.claude/skills/js-tooling.md',
+        desc: 'Claude Code skill for driving the js-tooling CLI',
+    },
 };
 export function getPackageRoot() {
     const cliFile = new URL(import.meta.url).pathname;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/js-tooling",
-	"version": "2.18.0",
+	"version": "2.19.1",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [
@@ -71,13 +71,15 @@
 		"tooling/tests/exports-resolution.d.mts",
 		"tooling/tests/ssr-safety.mjs",
 		"tooling/tests/ssr-safety.d.mts",
-		"tooling/tsup/index.ts",
+		"tooling/tsup/index.mjs",
+		"tooling/tsup/index.d.mts",
 		"tooling/biome/biome.json",
 		"tooling/changesets/config.json",
 		"tooling/oxlint/oxlintrc.json",
 		"tooling/typedoc/typedoc.json",
 		"tooling/semantic-release/*.mjs",
 		"tooling/semantic-release/*.d.mts",
+		"tooling/claude/*.md",
 		"README.md"
 	],
 	"exports": {
@@ -146,7 +148,10 @@
 			"types": "./tooling/vitest/jsdom-shims.d.mts",
 			"import": "./tooling/vitest/jsdom-shims.mjs"
 		},
-		"./tsup": "./tooling/tsup/index.ts",
+		"./tsup": {
+			"types": "./tooling/tsup/index.d.mts",
+			"import": "./tooling/tsup/index.mjs"
+		},
 		"./biome": "./tooling/biome/biome.json",
 		"./changesets": "./tooling/changesets/config.json",
 		"./oxlint": "./tooling/oxlint/oxlintrc.json",
@@ -199,8 +204,8 @@
 		"@total-typescript/ts-reset": "0.6.1",
 		"@types/fs-extra": "^11.0.4",
 		"@types/node": "^25.9.2",
-		"@typescript-eslint/eslint-plugin": "^8.46.2",
-		"@typescript-eslint/parser": "^8.46.2",
+		"@typescript-eslint/eslint-plugin": "^8.61.1",
+		"@typescript-eslint/parser": "^8.61.1",
 		"@vitejs/plugin-react": "^5.1.0",
 		"@vitest/coverage-v8": "^4.0.3",
 		"commitizen": "^4.3.1",
@@ -208,9 +213,9 @@
 		"cz-conventional-changelog": "^3.3.0",
 		"esbuild": "^0.28.0",
 		"esbuild-node-externals": "^1.22.0",
-		"eslint": "9.38.0",
+		"eslint": "10.5.0",
 		"eslint-plugin-import": "^2.32.0",
-		"eslint-plugin-jest": "29.0.1",
+		"eslint-plugin-jest": "29.15.2",
 		"husky": "^9.1.7",
 		"is-ci": "^4.1.0",
 		"jest": "^29.7.0",
@@ -223,7 +228,7 @@
 		"ts-jest": "^29.4.11",
 		"tsup": "8.5.1",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.60.0",
+		"typescript-eslint": "^8.61.1",
 		"vitest": "^4.1.8"
 	},
 	"peerDependencies": {

package/tooling/claude/js-tooling.md

@@ -0,0 +1,78 @@
+---
+name: js-tooling
+description: Use when auditing or fixing TypeScript/JavaScript project tooling in a repo that depends on @rtorcato/js-tooling, or scaffolding a new project with it. Triggers on "audit my tooling", "fix tooling drift", "is my tsconfig/biome/vitest config right", "set up CI/semantic-release/dependabot", "scaffold a TS library/web-app/node-api", "run doctor", "run fix", or "/js-tooling". Drives the `@rtorcato/js-tooling` CLI non-interactively (--json --yes). NOT for hand-editing configs the CLI owns — let the CLI scaffold them so they stay in sync with the presets.
+---
+
+# js-tooling
+
+`@rtorcato/js-tooling` is a single-package TS/JS tooling distribution: every preset
+(TypeScript, Biome, ESLint, Prettier, Vitest/Jest, Commitlint, semantic-release,
+tsup/esbuild/Vite/Playwright) plus a CLI to scaffold and audit. Prefer the CLI over
+hand-editing the configs it owns — a manual edit drifts from the preset and `doctor`
+will flag it.
+
+Every command takes `--json` and a non-interactive mode; pair with `--yes` for
+autonomous use. `--json` implies `--yes` (a prompt would corrupt the JSON).
+
+Run via `npx @rtorcato/js-tooling <cmd>` (or the local `js-tooling` bin if installed).
+`-d <dir>` targets a directory other than cwd.
+
+## The two workflows you'll use most
+
+### Audit → fix → confirm (existing repo)
+
+```bash
+npx @rtorcato/js-tooling doctor --json                 # findings
+npx @rtorcato/js-tooling fix --yes --json              # apply every fixable finding
+npx @rtorcato/js-tooling doctor --json                 # confirm clean
+```
+
+`doctor` returns `{ directory, results: [{ check, status, detail, hint? }] }`.
+Status is one of:
+- `ok` — configured correctly, nothing to do.
+- `drift` — file exists but doesn't extend our preset. `fix` defaults the overwrite
+  prompt to **No**; `--yes` is required to overwrite.
+- `missing` — required and absent → fix it.
+- `optional-missing` — opt-in tool not configured. Only fix if the user wants that tool.
+
+`fix` returns `FixActionRecord[]` with `status: applied | dry-run | skipped | already-ok | unsupported`.
+
+### Targeted fix (one concern)
+
+```bash
+npx @rtorcato/js-tooling list --json                   # enumerate targets
+npx @rtorcato/js-tooling fix <target> --yes --json     # e.g. biome, vitest, dependabot, attw
+npx @rtorcato/js-tooling fix <target> --dry-run --json # preview writes
+npx @rtorcato/js-tooling fix <target> --diff           # unified diff before confirming
+```
+
+`list --json` is the source of truth for valid targets — read it, don't guess.
+
+## Scaffolding a new project
+
+```bash
+# Quick: from a named preset (library | web-app | node-api | nextjs-app | react-app)
+npx @rtorcato/js-tooling setup --preset library -d ./my-lib --skip-install
+
+# Full control: validate a config against the schema, preview, then write
+npx @rtorcato/js-tooling setup --config-schema > project-config.schema.json
+npx @rtorcato/js-tooling setup --config project.json --dry-run    # preview file list
+npx @rtorcato/js-tooling setup --config project.json -d ./my-lib --skip-install
+```
+
+## Drift policy (don't surprise the user)
+
+- Safe-merge fixers (`engines`, `husky`, `package-json`) never overwrite — they add/merge.
+- Drift on a config file (`biome`, `tsconfig`, …) is only overwritten with `--yes`.
+  Before overwriting drift the user wrote by hand, show `fix <target> --diff` first.
+- `optional-missing` ≠ broken. Don't install opt-in tools (typedoc, size-limit,
+  treeshake-check, attw, codeql) unless the user asked for that capability.
+
+## Rules
+
+- Let the CLI own its configs. If `doctor` says `drift`, fix via the CLI, don't hand-patch.
+- Use `--json` whenever you'll parse the result; use `--dry-run`/`--diff` before any
+  destructive overwrite.
+- After a `fix`, re-run `doctor` to confirm the finding cleared.
+
+Full docs: https://rtorcato.github.io/js-tooling/guides/cli/

package/tooling/tsup/index.d.mts

@@ -0,0 +1,8 @@
+import type { Options } from 'tsup'
+import type { defineConfig } from 'tsup'
+
+export type DefineConfig = ReturnType<typeof defineConfig>
+
+export declare const getConfig: (customOptions: Options, env: string) => DefineConfig
+
+export declare const baseOptions: (options: Options, env: string) => Options

package/tooling/tsup/index.mjs

@@ -0,0 +1,23 @@
+import { defineConfig } from 'tsup'
+
+export const getConfig = (customOptions, env) => {
+	return defineConfig((options = customOptions) => {
+		return baseOptions(options, env)
+	})
+}
+
+export const baseOptions = (options, env) => {
+	const opts = {
+		treeshake: true,
+		splitting: true,
+		format: ['cjs', 'esm'], // generate cjs and esm files
+		entry: ['src/**/*.ts'],
+		skipNodeModulesBundle: true, // Skips building dependencies for node modules
+		minify: !options.watch && env === 'production',
+		bundle: false,
+		clean: true, // clean up the dist folder
+		dts: true, // generate dts file for main module
+		...options,
+	}
+	return opts
+}

package/tooling/typescript/tsconfig.base.json

@@ -27,6 +27,10 @@
     // 📈 Performance
     "skipLibCheck": true, // Skip type checking of declaration files
     "incremental": true, // Enable incremental compilation
+    // Pin the build-info location so downstream emit tools (e.g. tsup's `dts`
+    // build) don't hit TS5074 from inheriting `incremental` without a file.
+    // ${configDir} resolves to the consuming project's dir (TS 5.5+).
+    "tsBuildInfoFile": "${configDir}/node_modules/.cache/tsconfig.tsbuildinfo",
     "disableSourceOfProjectReferenceRedirect": true, // Disable source of project reference redirect
 
     // 🚨 Strict Type Checking

package/tooling/tsup/index.ts

@@ -1,50 +0,0 @@
-import type { Options } from 'tsup'
-import { defineConfig } from 'tsup'
-
-export type DefineConfig = ReturnType<typeof defineConfig>
-
-export const getConfig: (customOptions: Options, env: string) => DefineConfig = (
-	customOptions: Options,
-	env: string
-): DefineConfig => {
-	return defineConfig((options: Options = customOptions) => {
-		return baseOptions(options, env)
-	})
-}
-
-export const baseOptions = (options: Options, env: string): Options => {
-	const opts: Options = {
-		treeshake: true,
-		splitting: true,
-		// target: 'es2020',
-		// target: 'nodeNext',
-		format: ['cjs', 'esm'], // generate cjs and esm files
-		entry: [
-			// './src/index.ts',
-			'src/**/*.ts',
-			// './src/**/*!(index).ts?(x)',
-			// '!./src/**/*.spec.*',
-			// '!./src/**/*.stories.*',
-		],
-		skipNodeModulesBundle: true, // Skips building dependencies for node modules
-		minify: !options.watch && env === 'production',
-		bundle: false, //env === 'production',
-		clean: true, // clean up the dist folder
-		dts: true, // generate dts file for main module
-		// sourcemap: env === 'production', // source map is only available in prod
-		// sourcemap: true,
-		// outDir: env === 'production' ? 'dist' : 'lib',
-		// outDir: 'dist',
-		// tsconfig: path.resolve(__dirname, './tsconfig.build.json'),
-		// esbuildOptions(options, context) {
-		//   options.outbase = './'
-		// },
-		// external: ['react'],
-		...options,
-		// banner: {js: '"use client";'},
-		// dts: {
-		//   footer: "declare module 'knex/types/tables';"
-		// },
-	}
-	return opts
-}