@rtorcato/js-tooling 2.17.1 → 2.19.0

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

@@ -89,6 +89,24 @@ const FILE_CHECKS = [
         matcher: /@rtorcato\/js-tooling\/commitlint\/config/,
         optional: true,
     },
+    {
+        check: 'Oxlint',
+        candidates: ['.oxlintrc.json', 'oxlintrc.json'],
+        // Oxlint configs are project-owned (extends from npm packages isn't
+        // reliably supported), so any well-formed file counts as ok.
+        expected: 'is a valid Oxlint configuration',
+        matcher: /"(rules|plugins|categories|extends)"/,
+        optional: true,
+        hint: 'Run `npx @rtorcato/js-tooling copy oxlint` to scaffold',
+    },
+    {
+        check: 'Changesets',
+        candidates: ['.changeset/config.json'],
+        expected: 'is a valid Changesets configuration',
+        matcher: /"(changelog|access|baseBranch)"/,
+        optional: true,
+        hint: 'Run `npx @rtorcato/js-tooling copy changesets` to scaffold',
+    },
 ];
 async function checkFile(dir, spec) {
     for (const candidate of spec.candidates) {
@@ -451,7 +469,25 @@ async function checkSemanticRelease(dir, pkg) {
             break;
         }
     }
+    const hasChangesets = await fs.pathExists(path.join(dir, '.changeset', 'config.json'));
+    // Conflict: both semantic-release and Changesets configured.
+    if ((inPkg || configFile) && hasChangesets) {
+        return {
+            check: 'semantic-release',
+            status: 'drift',
+            detail: 'both semantic-release and Changesets are configured',
+            hint: 'Pick one release tool — remove either the semantic-release config or the .changeset/ directory',
+        };
+    }
     if (!inPkg && !configFile) {
+        // Changesets present — treat semantic-release as intentionally not used.
+        if (hasChangesets) {
+            return {
+                check: 'semantic-release',
+                status: 'ok',
+                detail: 'using Changesets (.changeset/config.json) instead',
+            };
+        }
         return {
             check: 'semantic-release',
             status: isPrivate ? 'optional-missing' : 'drift',
@@ -680,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

@@ -1,7 +1,10 @@
 import path from 'node:path';
+import os from 'node:os';
 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';
@@ -57,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',
@@ -202,6 +223,28 @@ const FIXERS = [
             return { filesWritten: ['release.config.mjs'] };
         },
     },
+    {
+        target: 'changesets',
+        description: 'Scaffold .changeset/config.json (alternative to semantic-release)',
+        appliesTo: ['Changesets'],
+        outputs: ['.changeset/config.json'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('changesets', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'oxlint',
+        description: 'Scaffold .oxlintrc.json (additive to Biome/ESLint)',
+        appliesTo: ['Oxlint'],
+        outputs: ['.oxlintrc.json'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('oxlint', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
     {
         target: 'github-actions',
         description: 'Scaffold .github/workflows/ci.yml',
@@ -384,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',
@@ -464,6 +587,117 @@ export function listFixers() {
         canFixDrift: f.canFixDrift ?? false,
     }));
 }
+// Fixer outputs sometimes carry annotations like
+// "package.json (lint-staged field)" — strip them to get a usable filesystem path.
+function outputToRelativePath(output) {
+    return output.split(' ')[0] ?? output;
+}
+function shouldColorise() {
+    // Respect NO_COLOR (https://no-color.org) and chalk's own detection.
+    if (process.env.NO_COLOR && process.env.NO_COLOR !== '')
+        return false;
+    return chalk.level > 0;
+}
+function colorisePatch(patch) {
+    if (!shouldColorise())
+        return patch;
+    return patch
+        .split('\n')
+        .map((line) => {
+        if (line.startsWith('+++') || line.startsWith('---'))
+            return chalk.bold(line);
+        if (line.startsWith('@@'))
+            return chalk.cyan(line);
+        if (line.startsWith('+'))
+            return chalk.green(line);
+        if (line.startsWith('-'))
+            return chalk.red(line);
+        return line;
+    })
+        .join('\n');
+}
+/**
+ * Shadow-run a fixer in a temp copy of the target directory and return per-output
+ * diffs. We copy the real target into tmp so fixers that read existing state
+ * (e.g. husky reading package.json) still produce realistic output.
+ */
+async function previewFixer(fixer, result, targetDir, pkg, lock) {
+    // Pick a tmp root that is NOT inside targetDir. macOS sometimes hands us a
+    // $TMPDIR that lives under the working dir (e.g. when the caller is itself
+    // running inside a tempdir tree), which would make fs.copy fail with
+    // "subdirectory of itself". Fall back to the parent of targetDir if so.
+    const resolvedTarget = path.resolve(targetDir);
+    let tmpRoot = path.resolve(os.tmpdir());
+    if (tmpRoot === resolvedTarget || tmpRoot.startsWith(resolvedTarget + path.sep)) {
+        tmpRoot = path.dirname(resolvedTarget);
+    }
+    const tmpDir = await fs.mkdtemp(path.join(tmpRoot, 'js-tooling-fix-preview-'));
+    try {
+        await fs.copy(targetDir, tmpDir, {
+            filter: (src) => {
+                const rel = path.relative(targetDir, src);
+                if (!rel)
+                    return true;
+                const first = rel.split(path.sep)[0];
+                // Skip large/derived dirs that fixers never touch — keeps preview fast on
+                // big repos.
+                return first !== 'node_modules' && first !== 'dist' && first !== 'build' && first !== '.git';
+            },
+        });
+        await fixer.run({ targetDir: tmpDir, pkg, result, lock });
+        const previews = [];
+        const seen = new Set();
+        for (const output of fixer.outputs) {
+            const rel = outputToRelativePath(output);
+            if (seen.has(rel))
+                continue;
+            seen.add(rel);
+            const tmpPath = path.join(tmpDir, rel);
+            const realPath = path.join(targetDir, rel);
+            if (!(await fs.pathExists(tmpPath)))
+                continue;
+            const newContent = await fs.readFile(tmpPath, 'utf-8');
+            const existed = await fs.pathExists(realPath);
+            const oldContent = existed ? await fs.readFile(realPath, 'utf-8') : '';
+            if (newContent === oldContent) {
+                previews.push({ path: rel, kind: 'unchanged', patch: null });
+                continue;
+            }
+            const patch = createPatch(rel, oldContent, newContent, undefined, undefined, { context: 3 });
+            previews.push({
+                path: rel,
+                kind: existed ? 'modify' : 'create',
+                patch: colorisePatch(patch),
+            });
+        }
+        return previews;
+    }
+    finally {
+        await fs.remove(tmpDir).catch(() => {
+            // Best-effort cleanup; tmp dirs get GC'd by the OS eventually.
+        });
+    }
+}
+function printPreviews(previews) {
+    if (previews.length === 0) {
+        console.log(chalk.gray('  (no preview available — fixer produced no recognisable outputs)'));
+        return;
+    }
+    for (const p of previews) {
+        if (p.kind === 'unchanged') {
+            console.log(chalk.gray(`  ${p.path} — unchanged`));
+            continue;
+        }
+        const label = p.kind === 'create' ? chalk.green('create') : chalk.yellow('modify');
+        console.log(`  ${label} ${chalk.bold(p.path)}`);
+        if (p.patch) {
+            console.log(p.patch
+                .split('\n')
+                .map((l) => `    ${l}`)
+                .join('\n'));
+        }
+    }
+}
 async function applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent) {
     if (dryRun) {
         if (!silent) {
@@ -526,6 +760,8 @@ export async function fixCommand(target, options = {}) {
     // JSON mode implies --yes so prompts don't corrupt the output stream.
     const assumeYes = options.yes === true || json;
     const silent = json;
+    // Diff preview is interactive-only — suppress in JSON mode.
+    const showDiff = options.diff === true && !json;
     if (options.list) {
         const summary = listFixers();
         if (json) {
@@ -654,6 +890,10 @@ export async function fixCommand(target, options = {}) {
             console.log(chalk.cyan(`\n🔧 ${fixer.target} — ${chalk.bold(result.check)} is ${effectiveResult.status}\n`));
         }
         const conflict = noteLockConflict(result.check);
+        if (showDiff && (fixer.riskLevel ?? 'destructive') !== 'safe-add') {
+            const previews = await previewFixer(fixer, effectiveResult, targetDir, pkg, lock);
+            printPreviews(previews);
+        }
         const ok = await confirmApply(fixer, effectiveResult, assumeYes);
         if (!ok) {
             actions.push(recordFor(fixer.target, result.check, effectiveResult.status, 'skipped', [], conflict));
@@ -695,6 +935,10 @@ export async function fixCommand(target, options = {}) {
             console.log(`  ${chalk.bold(result.check)} (${result.status}) → ${fixer.target}`);
         }
         const conflict = noteLockConflict(result.check);
+        if (showDiff && (fixer.riskLevel ?? 'destructive') !== 'safe-add') {
+            const previews = await previewFixer(fixer, result, targetDir, pkg, lock);
+            printPreviews(previews);
+        }
         const ok = await confirmApply(fixer, result, assumeYes);
         if (!ok) {
             actions.push(recordFor(fixer.target, result.check, result.status, 'skipped', [], conflict));

package/dist/cli/commands/setup-presets.js

@@ -125,6 +125,8 @@ export const CONFIG_SCHEMA = {
         gitHooks: { type: 'boolean' },
         commitLint: { type: 'boolean' },
         semanticRelease: { type: 'boolean' },
+        changesets: { type: 'boolean' },
+        oxlint: { type: 'boolean' },
         securityAutomation: { type: 'boolean' },
         bundler: { type: 'string', enum: ['tsup', 'esbuild', 'vite', 'none'] },
         treeshakeCheck: { type: 'boolean' },
@@ -192,6 +194,10 @@ export function computeFileList(config) {
         files.push('vite.config.ts');
     if (config.semanticRelease)
         files.push('release.config.mjs');
+    if (config.changesets)
+        files.push('.changeset/config.json');
+    if (config.oxlint)
+        files.push('.oxlintrc.json');
     if (config.treeshakeCheck && config.projectType === 'library') {
         files.push('apps/treeshake-check/package.json', 'apps/treeshake-check/check.mjs', 'apps/treeshake-check/src/entry.ts');
     }

package/dist/cli/commands/setup.js

@@ -146,6 +146,13 @@ async function promptForConfig() {
             },
             when: (answers) => answers.lintingTool === 'eslint' || answers.lintingTool === 'both',
         },
+        {
+            type: 'confirm',
+            name: 'oxlint',
+            message: '🦀 Also run Oxlint alongside (50–100× faster than ESLint)?',
+            default: false,
+            when: (answers) => answers.lintingTool !== 'none',
+        },
         {
             type: 'list',
             name: 'testingFramework',
@@ -184,10 +191,15 @@ async function promptForConfig() {
             when: (answers) => answers.gitHooks,
         },
         {
-            type: 'confirm',
-            name: 'semanticRelease',
-            message: '🚀 Set up semantic release for automated versioning?',
-            default: (answers) => answers.projectType === 'library',
+            type: 'list',
+            name: 'releaseTool',
+            message: '🚀 Automated release tool?',
+            choices: [
+                { name: '📦 semantic-release (commit-message-driven)', value: 'semantic-release' },
+                { name: '📝 Changesets (changeset-file-driven, monorepo-friendly)', value: 'changesets' },
+                { name: '❌ None', value: 'none' },
+            ],
+            default: 'semantic-release',
             when: (answers) => answers.projectType === 'library',
         },
         {
@@ -245,7 +257,9 @@ async function promptForConfig() {
         },
         gitHooks: answers.gitHooks || false,
         commitLint: answers.commitLint || false,
-        semanticRelease: answers.semanticRelease || false,
+        semanticRelease: answers.releaseTool === 'semantic-release',
+        changesets: answers.releaseTool === 'changesets',
+        oxlint: answers.oxlint || false,
         securityAutomation: answers.securityAutomation ?? false,
         bundler: answers.bundler || 'none',
         treeshakeCheck: answers.treeshakeCheck || false,

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/build.js

@@ -14,6 +14,10 @@ export async function generateBuildConfigs(config, targetDir) {
     if (config.semanticRelease) {
         await generateSemanticReleaseConfig(targetDir);
     }
+    // Generate Changesets config (alternative to semantic-release)
+    if (config.changesets) {
+        await generateChangesetsConfig(targetDir);
+    }
 }
 async function generateTsupConfig(targetDir) {
     const tsupConfigPath = path.join(targetDir, 'tsup.config.ts');
@@ -73,3 +77,10 @@ export async function generateSemanticReleaseConfig(targetDir) {
 `;
     await fs.writeFile(releaseConfigPath, releaseConfig);
 }
+export async function generateChangesetsConfig(targetDir) {
+    // Drop the canonical Changesets config into .changeset/config.json. The user
+    // owns this file once it's in their repo; subsequent `pnpm changeset` runs
+    // create per-change markdown files alongside it.
+    const { copyPreset } = await import('../utils/copy-preset.js');
+    await copyPreset('changesets', targetDir);
+}

package/dist/cli/generators/linting.js

@@ -13,6 +13,17 @@ export async function generateLintingConfigs(config, targetDir) {
     if (config.linting.tool === 'eslint') {
         await generatePrettierConfig(targetDir);
     }
+    // Generate Oxlint config (additive — runs alongside Biome/ESLint)
+    if (config.oxlint) {
+        await generateOxlintConfig(targetDir);
+    }
+}
+export async function generateOxlintConfig(targetDir) {
+    // Oxlint's `extends` resolution from npm packages isn't reliably supported,
+    // so we copy the full preset rather than write a thin pointer file (same
+    // pattern as biome.jsonc — the user owns the file once it's in their repo).
+    const { copyPreset } = await import('../utils/copy-preset.js');
+    await copyPreset('oxlint', targetDir);
 }
 export async function generateBiomeConfig(targetDir) {
     const biomeConfigPath = path.join(targetDir, 'biome.jsonc');

package/dist/cli/index.js

@@ -142,6 +142,18 @@ const TOOL_CATALOG = [
         ],
         fixTarget: 'semantic-release',
     },
+    {
+        name: 'Changesets',
+        description: 'Monorepo-friendly release tool (alternative to semantic-release)',
+        exports: ['@rtorcato/js-tooling/changesets'],
+        fixTarget: 'changesets',
+    },
+    {
+        name: 'Oxlint',
+        description: 'Rust-based linter (additive to Biome/ESLint)',
+        exports: ['@rtorcato/js-tooling/oxlint'],
+        fixTarget: 'oxlint',
+    },
     {
         name: 'tsup',
         description: 'TypeScript bundler configuration',
@@ -235,6 +247,7 @@ program
     .option('--json', 'Emit machine-readable JSON output (implies --yes)')
     .option('--list', 'List all registered fix targets and exit')
     .option('--resync', 'Re-scaffold every file recorded in .js-tooling.json')
+    .option('--diff', 'Show a unified diff of each change before confirming')
     .action((target, options) => fixCommand(target, {
     directory: options.directory,
     yes: options.yes,
@@ -242,6 +255,7 @@ program
     json: options.json,
     list: options.list,
     resync: options.resync,
+    diff: options.diff,
 }));
 program.hook('preAction', async (_, actionCommand) => {
     const name = actionCommand.name();

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

@@ -6,11 +6,26 @@ export const PRESETS = {
         target: 'biome.json',
         desc: 'Biome formatter and linter configuration',
     },
+    changesets: {
+        source: 'tooling/changesets/config.json',
+        target: '.changeset/config.json',
+        desc: 'Changesets release-tool configuration',
+    },
+    oxlint: {
+        source: 'tooling/oxlint/oxlintrc.json',
+        target: '.oxlintrc.json',
+        desc: 'Oxlint linter configuration (additive to Biome)',
+    },
     tsconfig: {
         source: 'tooling/typescript/tsconfig.base.json',
         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.17.1",
+	"version": "2.19.0",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [
@@ -9,6 +9,7 @@
 		"eslint"
 	],
 	"author": "Richard Torcato",
+	"packageManager": "pnpm@11.1.3",
 	"sideEffects": false,
 	"license": "MIT",
 	"repository": {
@@ -23,6 +24,8 @@
 		"build": "pnpm build-cli",
 		"build-cli": "rimraf ./dist/cli && tsc --project src/cli/tsconfig.json",
 		"prepublishOnly": "./scripts/fix-bins.sh",
+		"dev": "pnpm --filter @rtorcato/docs dev",
+		"docs:build": "pnpm --filter @rtorcato/docs build",
 		"==================== Common ====================": "",
 		"lint": "pnpm exec biome lint --config-path=tooling/biome/biome.json src scripts",
 		"format": "pnpm exec biome format --config-path=tooling/biome/biome.json src scripts",
@@ -70,9 +73,12 @@
 		"tooling/tests/ssr-safety.d.mts",
 		"tooling/tsup/index.ts",
 		"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": {
@@ -143,6 +149,8 @@
 		},
 		"./tsup": "./tooling/tsup/index.ts",
 		"./biome": "./tooling/biome/biome.json",
+		"./changesets": "./tooling/changesets/config.json",
+		"./oxlint": "./tooling/oxlint/oxlintrc.json",
 		"./typedoc": "./tooling/typedoc/typedoc.json",
 		"./semantic-release": {
 			"types": "./tooling/semantic-release/index.d.mts",
@@ -168,11 +176,13 @@
 	"dependencies": {
 		"chalk": "^5.6.2",
 		"commander": "^14.0.3",
+		"diff": "^9.0.0",
 		"fs-extra": "^11.3.2",
 		"inquirer": "^14.0.2"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.16",
+		"@types/diff": "^8.0.0",
 		"@commitlint/cli": "^20.1.0",
 		"@commitlint/config-conventional": "^21.0.2",
 		"@commitlint/types": "^20.0.0",
@@ -190,8 +200,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",
@@ -199,9 +209,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",
@@ -214,8 +224,8 @@
 		"ts-jest": "^29.4.11",
 		"tsup": "8.5.1",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.60.0",
-		"vitest": "4.0.3"
+		"typescript-eslint": "^8.61.1",
+		"vitest": "^4.1.8"
 	},
 	"peerDependencies": {
 		"@biomejs/biome": "^2.0.0",
@@ -232,6 +242,7 @@
 		"@semantic-release/github": "^12.0.8",
 		"@semantic-release/npm": "^13.0.0",
 		"@semantic-release/release-notes-generator": "^14.0.0",
+		"@size-limit/preset-small-lib": "^12.0.0",
 		"@total-typescript/ts-reset": "^0.6.0",
 		"@typescript-eslint/eslint-plugin": "^8.0.0",
 		"@typescript-eslint/parser": "^8.0.0",
@@ -245,7 +256,6 @@
 		"prettier": "^3.0.0",
 		"semantic-release": "^25.0.0",
 		"size-limit": "^12.0.0",
-		"@size-limit/preset-small-lib": "^12.0.0",
 		"ts-jest": "^29.0.0",
 		"tsup": "^8.0.0",
 		"typescript": ">=5.0.0",

package/tooling/changesets/README.md

@@ -0,0 +1,35 @@
+# Changesets preset
+
+Shared [Changesets](https://github.com/changesets/changesets) configuration for projects using `@rtorcato/js-tooling`.
+
+Changesets is a **monorepo-friendly alternative to semantic-release**. The release workflow is the same shape (CI bumps versions, generates a changelog, publishes to npm), but the *intent* is captured in changeset markdown files at PR time rather than parsed from commit messages.
+
+Pick one — Changesets or semantic-release — per repo. The `doctor` check flags repos configured for both.
+
+## Usage
+
+```bash
+npx @rtorcato/js-tooling copy changesets
+```
+
+This scaffolds `.changeset/config.json` from this preset. After that:
+
+```bash
+pnpm changeset           # interactive — author a changeset for the current change
+pnpm changeset version   # consume changesets, bump versions, write CHANGELOG.md
+pnpm changeset publish   # publish to npm
+```
+
+CI typically runs the [Changesets release bot](https://github.com/changesets/action), which opens a "Version Packages" PR when changesets are present and publishes on merge.
+
+## Why pick this over semantic-release
+
+- **Monorepos** — Changesets handles multi-package version bumps in a way semantic-release doesn't out of the box.
+- **Explicit intent** — Authors declare a change's bump level in the changeset file rather than encoding it in commit message conventions, which is more forgiving for human commits.
+- **Pre-release flows** — `--snapshot` and `pre enter <tag>` are first-class.
+
+## Why pick semantic-release instead
+
+- **Single-package repos** — Less ceremony; nothing to author per change.
+- **Strict conventional-commits discipline already in place.**
+- **Existing CI built around the `npm run release` path.**

package/tooling/changesets/config.json

@@ -0,0 +1,11 @@
+{
+	"$schema": "https://unpkg.com/@changesets/config@3.0.5/schema.json",
+	"changelog": "@changesets/cli/changelog",
+	"commit": false,
+	"fixed": [],
+	"linked": [],
+	"access": "public",
+	"baseBranch": "main",
+	"updateInternalDependencies": "patch",
+	"ignore": []
+}

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/oxlint/README.md

@@ -0,0 +1,25 @@
+# Oxlint preset
+
+Shared [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) configuration for projects using `@rtorcato/js-tooling`.
+
+Oxlint is a Rust-based linter that's 50–100× faster than ESLint. It is intentionally **additive** to Biome — Biome handles formatting and the broad lint baseline, Oxlint adds a faster pass for the type-aware and import rules Biome doesn't cover yet.
+
+## Usage
+
+```bash
+npx @rtorcato/js-tooling copy oxlint
+```
+
+This drops `.oxlintrc.json` at the project root, extending the conventions in this preset. Run it with:
+
+```bash
+pnpm oxlint
+# or
+npx oxlint
+```
+
+## Notes
+
+- Oxlint shares its rule catalog with ESLint's plugins (`typescript`, `unicorn`, `oxc`, `import`), so most ESLint rules you know already work here.
+- The preset disables Biome-overlapping rules to keep CI noise down — Biome stays the source of truth for formatting and the baseline lint set.
+- For projects without Biome, you can run Oxlint standalone and re-enable the `style` and `pedantic` categories.

package/tooling/oxlint/oxlintrc.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/npm/oxlint/configuration_schema.json",
+	"categories": {
+		"correctness": "error",
+		"perf": "warn",
+		"suspicious": "warn",
+		"pedantic": "off",
+		"style": "off",
+		"restriction": "off",
+		"nursery": "off"
+	},
+	"plugins": ["typescript", "unicorn", "oxc", "import"],
+	"rules": {
+		"no-console": "warn",
+		"no-debugger": "error",
+		"no-empty": "warn",
+		"no-unused-vars": "off",
+		"@typescript-eslint/no-unused-vars": [
+			"warn",
+			{ "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }
+		],
+		"unicorn/filename-case": "off",
+		"unicorn/no-null": "off",
+		"unicorn/prevent-abbreviations": "off",
+		"import/no-default-export": "off"
+	},
+	"ignorePatterns": ["node_modules", "dist", "build", "coverage", ".next", "*.d.ts"]
+}