@rtorcato/js-tooling 2.18.0 → 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

@@ -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/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.0",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [
@@ -78,6 +78,7 @@
 		"tooling/typedoc/typedoc.json",
 		"tooling/semantic-release/*.mjs",
 		"tooling/semantic-release/*.d.mts",
+		"tooling/claude/*.md",
 		"README.md"
 	],
 	"exports": {
@@ -199,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",
@@ -208,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",
@@ -223,7 +224,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/