@rtorcato/repo-tooling 3.34.0 → 3.36.0

package/AGENTS.md

@@ -94,11 +94,11 @@ npx @rtorcato/repo-tooling fix claude-skills --yes --json
 
 ## Drift policy (important)
 
-`fix` defaults the confirm prompt to **No** for drift cases (existing file that doesn't extend our preset). The `--yes` flag is required to overwrite drift. Safe-merge fixers (`engines`, `husky`, `package-json`) never overwrite — they add/merge — and use friendlier prompt wording. `fix --json` implies `--yes` (prompts would corrupt JSON output).
+`fix` defaults the confirm prompt to **No** for drift cases (existing file that doesn't extend our preset). The `--yes` flag is required to overwrite drift. Safe-merge fixers (`biome`, `engines`, `husky`, `package-json`) never overwrite — they add/merge — and use friendlier prompt wording. `fix --json` implies `--yes` (prompts would corrupt JSON output).
 
 Fixers marked `explicitOnly` are exempt from `fix` all *and* from `fix --yes` — they only run when named as the target. Today that is `claude-skills`, the one fixer whose blast radius is outside the repo.
 
-A fixer may also **refuse** — the target file holds something the generator cannot reproduce, so overwriting would destroy it. Today that is `dependabot` against a config with repo-local `ignore:` rules (#422). A targeted `fix dependabot` then exits 1 with `error: dependabot-ignore-rules`; a bulk `fix --yes` records it `skipped` and carries on with the rest. Neither `--yes` nor `--json` overrides it — resolve the named rules by hand and re-run.
+A fixer may also **refuse** — the target file holds something the generator cannot reproduce, so overwriting would destroy it. Today that is `dependabot` against a config with repo-local `ignore:` rules (#422), and `biome` against a `biome.json` that does not parse, whose settings cannot be merged (#587). A targeted `fix dependabot` then exits 1 with `error: dependabot-ignore-rules`; a bulk `fix --yes` records it `skipped` and carries on with the rest. Neither `--yes` nor `--json` overrides it — resolve the named rules by hand and re-run.
 
 ## Source-of-truth files in the repo
 

package/dist/cli/commands/doctor.js

@@ -22,7 +22,7 @@ import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { compareRulesWithReference } from '../utils/reference-rules.js';
 import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
 import { checkAiSetup, checkBrand, checkCodeowners, checkClaudeSkills, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, checkRecommendedMcp, checkRequiredSkills, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
-import { allDeps, checkAreTheTypesWrong, checkBiome, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkExportsBuildable, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
+import { allDeps, checkAreTheTypesWrong, checkBiome, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkExportsBuildable, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPeerVersions, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
 export { evaluateNodeVersion };
 const PACKAGE = '@rtorcato/repo-tooling';
 // Detects the broken-release-on-protected-main footgun: a workflow that runs
@@ -366,6 +366,7 @@ export async function runDoctor(dir, skillsDir) {
     results.push(await checkPackageManager(targetDir, pkg));
     results.push(await checkConfigSchemaVersions(targetDir, pkg));
     results.push(checkGitDependencies(pkg));
+    results.push(await checkPeerVersions(targetDir, pkg));
     results.push(await checkVscodeExtensions(targetDir));
     results.push(await checkNodeVersionPin(targetDir));
     results.push(await checkNodeVersionConsistency(targetDir, pkg));

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

@@ -92,7 +92,10 @@ export function buildPresetConfig(name, projectName) {
                 ...BASE,
                 projectName,
                 projectType: 'react-app',
-                typescript: { enabled: true, config: 'react' },
+                // vite-app, not react: this preset ships a Vite bundler, so
+                // `import.meta.env` has to typecheck, and typecheck is the app's CI
+                // gate rather than a build, so its tests are checked too (#592).
+                typescript: { enabled: true, config: 'vite-app' },
                 testing: { framework: 'vitest', environment: 'browser' },
                 bundler: 'vite',
             };
@@ -164,7 +167,7 @@ export const CONFIG_SCHEMA = {
             required: ['enabled', 'config'],
             properties: {
                 enabled: { type: 'boolean' },
-                config: { type: 'string', enum: ['base', 'react', 'next', 'node', 'express'] },
+                config: { type: 'string', enum: ['base', 'react', 'vite-app', 'next', 'node', 'express'] },
             },
         },
         linting: {

package/dist/cli/commands/setup.js

@@ -322,7 +322,13 @@ async function promptForConfig(targetDir, seed) {
                     return [{ name: '⚡ Next.js', value: 'next' }, ...baseChoices];
                 }
                 if (answers.projectType === 'react-app' || answers.projectType === 'web-app') {
-                    return [{ name: '⚛️  React', value: 'react' }, ...baseChoices];
+                    return [
+                        // First, so it's the default: most React projects are apps, and the
+                        // react preset is library-shaped — no vite/client, tests excluded.
+                        { name: '⚛️  React + Vite app', value: 'vite-app' },
+                        { name: '📦 React library', value: 'react' },
+                        ...baseChoices,
+                    ];
                 }
                 if (answers.projectType === 'node-api') {
                     return [

package/dist/cli/generators/claude-skills.js

@@ -14,9 +14,17 @@ import { shellQuote } from '../utils/shell.js';
 import { isNewerVersion, resolveShippedVersion } from '../utils/version.js';
 /**
  * Skills this package owns the content of and keeps up to date. The loop first —
- * it is the pipeline; the other three are its drivers (burst, on-ramp, status).
+ * it is the pipeline; the next three are its drivers (burst, on-ramp, status).
+ * `dogfood` stands apart: it tests the consuming repo's own tooling rather than
+ * driving the loop, and it is the only one that writes nothing outside a temp dir.
  */
-export const SHIPPED_SKILLS = ['ai-issue-loop', 'ai-workflow', 'ai-issue', 'ai-loop-status'];
+export const SHIPPED_SKILLS = [
+    'ai-issue-loop',
+    'ai-workflow',
+    'ai-issue',
+    'ai-loop-status',
+    'dogfood',
+];
 /** The primary skill — the default everywhere a single name is accepted. */
 export const SHIPPED_SKILL = 'ai-issue-loop';
 /**

package/dist/cli/generators/linting.js

@@ -1,5 +1,6 @@
 import fs from 'fs-extra';
 import path from 'node:path';
+import { parseJsonc } from '../utils/jsonc.js';
 export async function generateLintingConfigs(config, targetDir) {
     // Generate Biome config
     if (config.linting.tool === 'biome' || config.linting.tool === 'both') {
@@ -46,22 +47,58 @@ export const BIOME_LEGACY_CONFIG = 'biome.jsonc';
  * for autocomplete and validation, which is the only reason the key is there.
  */
 const BIOME_SCHEMA_URL = 'https://biomejs.dev/schemas/latest/schema.json';
+/** The preset pointer this generator guarantees, and what already counts as it. */
+const BIOME_PRESET = '@rtorcato/repo-tooling/biome';
+/** Kept in step with doctor's matcher — the old js-tooling path still counts. */
+const BIOME_PRESET_REF = /@rtorcato\/(?:js|repo)-tooling\/biome/;
 /**
  * The thin pointer config — the same shape this repo dogfoods. `fix biome` used
  * to copy the whole preset inline instead, which meant the scaffolded file
  * carried no `@rtorcato/repo-tooling/biome` reference for doctor's Biome check
  * to match, and preset improvements never reached consumers.
+ *
+ * A merge, not a rewrite (#587): only `$schema`, `extends` and a
+ * `linter.enabled: false` kill switch are this generator's to own, so every
+ * other key an existing biome.json carries — `files.includes`, a css parser
+ * flag, rule overrides — survives. Returns null and writes nothing when the
+ * existing file doesn't parse, since there is no way to merge into it and
+ * overwriting would destroy settings we cannot even read.
  */
 export async function generateBiomeConfig(targetDir) {
+    const file = path.join(targetDir, BIOME_CONFIG);
+    let existing = {};
+    if (await fs.pathExists(file)) {
+        const parsed = parseJsonc(await fs.readFile(file, 'utf-8'));
+        if (!parsed)
+            return null;
+        existing = parsed;
+    }
     // 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 { $schema: _schema, extends: prevExtends, linter, ...rest } = existing;
+    const prev = Array.isArray(prevExtends)
+        ? prevExtends
+        : typeof prevExtends === 'string'
+            ? [prevExtends]
+            : [];
+    const extendsList = prev.some((e) => typeof e === 'string' && BIOME_PRESET_REF.test(e))
+        ? prev
+        : [BIOME_PRESET, ...prev];
+    // The one consumer key that isn't kept: `linter.enabled: false` is precisely
+    // the drift doctor flags, so preserving it would leave the repo red after a
+    // run that reported success. Rule overrides under `linter.rules` stay.
+    const nextLinter = linter && typeof linter === 'object' ? { ...linter } : undefined;
+    if (nextLinter?.enabled === false)
+        delete nextLinter.enabled;
     const biomeConfig = {
         $schema: BIOME_SCHEMA_URL,
-        extends: ['@rtorcato/repo-tooling/biome'],
+        extends: extendsList,
+        ...(nextLinter && Object.keys(nextLinter).length > 0 ? { linter: nextLinter } : {}),
+        ...rest,
     };
-    await fs.writeJson(path.join(targetDir, BIOME_CONFIG), biomeConfig, { spaces: 2 });
+    await fs.writeJson(file, biomeConfig, { spaces: 2 });
     await fs.remove(path.join(targetDir, BIOME_LEGACY_CONFIG));
     return BIOME_CONFIG;
 }

package/dist/cli/generators/pnpm-workspace.js

@@ -66,13 +66,13 @@ function section(yaml, key) {
  * the release-age exemption is scope-derived, and a repo with no scope to
  * derive doesn't get that setting at all.
  */
-function settingsFor(glob) {
-    return glob ? [...BASE_SETTINGS, releaseAgeSetting(glob)] : BASE_SETTINGS;
+function settingsFor(glob, yaml, needsEsbuild) {
+    const builds = allowBuildsSetting(yaml, needsEsbuild);
+    return [...BASE_SETTINGS, ...(builds ? [builds] : []), ...(glob ? [releaseAgeSetting(glob)] : [])];
 }
 function releaseAgeSetting(glob) {
     return {
         label: `minimumReleaseAgeExclude: ${glob}`,
-        applies: () => true,
         satisfied: (yaml) => (section(yaml, 'minimumReleaseAgeExclude') ?? []).some((l) => l.includes(glob)),
         key: 'minimumReleaseAgeExclude',
         block: `# Exempt this package's own scope from pnpm's minimumReleaseAge cutoff, so a
@@ -86,7 +86,6 @@ minimumReleaseAgeExclude:
 const BASE_SETTINGS = [
     {
         label: 'verifyDepsBeforeRun: false',
-        applies: () => true,
         // Any explicit value counts — a repo that deliberately opted into
         // verification shouldn't be nagged back to the family default.
         satisfied: (yaml) => /^verifyDepsBeforeRun:/m.test(yaml),
@@ -97,23 +96,57 @@ verifyDepsBeforeRun: false
 `,
         item: '',
     },
-    {
-        label: 'allowBuilds: esbuild',
-        applies: (needsEsbuild) => needsEsbuild,
-        satisfied: (yaml) => (section(yaml, 'allowBuilds') ?? []).some((l) => /^\s*esbuild:/.test(l)),
+];
+/** A YAML scalar used as a map key: quoted unless it is plainly safe bare. */
+function asKey(name) {
+    return /^[a-z0-9][a-z0-9._-]*$/i.test(name) ? name : `'${name}'`;
+}
+/** Package names listed under `onlyBuiltDependencies:`, quotes stripped. */
+function onlyBuiltDependencies(yaml) {
+    return (section(yaml, 'onlyBuiltDependencies') ?? [])
+        .map((line) => /^\s+-\s*['"]?([^'"\s#]+)/.exec(line)?.[1])
+        .filter((name) => Boolean(name));
+}
+/** True when `name` already carries a decision under `allowBuilds:`. */
+function approved(yaml, name) {
+    const key = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return (section(yaml, 'allowBuilds') ?? []).some((l) => new RegExp(`^\\s*['"]?${key}['"]?\\s*:`).test(l));
+}
+/**
+ * pnpm 11 reads build approvals from `allowBuilds` and ignores the older
+ * `onlyBuiltDependencies` list, so that list is *mirrored* into the map rather
+ * than replaced by a fixed baseline: writing only `esbuild: true` over a file
+ * that already approved more packages would narrow the allowlist and break the
+ * install on the very pnpm version the map exists for (#588). Null when there
+ * is nothing to approve.
+ */
+function allowBuildsSetting(yaml, needsEsbuild) {
+    const packages = [
+        ...new Set([...(needsEsbuild ? ['esbuild'] : []), ...onlyBuiltDependencies(yaml)]),
+    ];
+    if (packages.length === 0)
+        return null;
+    const entry = (name) => `  ${asKey(name)}: true`;
+    return {
+        label: `allowBuilds: ${packages.join(', ')}`,
+        satisfied: (y) => packages.every((name) => approved(y, name)),
         key: 'allowBuilds',
         block: `# pnpm 11 reads build-script approvals from this map, not the older
 # onlyBuiltDependencies list, and fails the install outright without them.
 allowBuilds:
-  esbuild: true
+${packages.map(entry).join('\n')}
 `,
-        item: '  esbuild: true',
-    },
-];
+        // Only the undecided ones — a hand-vetted `false` is a decision and stays.
+        item: packages
+            .filter((name) => !approved(yaml, name))
+            .map(entry)
+            .join('\n'),
+    };
+}
 /** Managed settings absent from `yaml`, named as doctor reports them. */
 export function missingPnpmSettings(yaml, needsEsbuild, glob) {
-    return settingsFor(glob)
-        .filter((s) => s.applies(needsEsbuild) && !s.satisfied(yaml))
+    return settingsFor(glob, yaml, needsEsbuild)
+        .filter((s) => !s.satisfied(yaml))
         .map((s) => s.label);
 }
 /** Insert `item` directly under an existing `key:` line, keeping the rest untouched. */
@@ -126,8 +159,8 @@ function insertUnder(yaml, key, item) {
 /** Merge every missing managed setting into `yaml` and return the new contents. */
 export function upsertPnpmSettings(yaml, needsEsbuild, glob) {
     let next = yaml;
-    for (const setting of settingsFor(glob)) {
-        if (!setting.applies(needsEsbuild) || setting.satisfied(next))
+    for (const setting of settingsFor(glob, yaml, needsEsbuild)) {
+        if (setting.satisfied(next))
             continue;
         if (setting.item && section(next, setting.key)) {
             next = insertUnder(next, setting.key, setting.item);

package/dist/cli/utils/jsonc.js

@@ -0,0 +1,18 @@
+/**
+ * JSONC → object, or null when it genuinely won't parse. Biome and friends
+ * accept comments and trailing commas, so a bare `JSON.parse` would reject
+ * configs the tools themselves read fine.
+ *
+ * The first alternative consumes whole string literals, so a `//` or a comment
+ * opener inside one (a `$schema` URL, most obviously) is never mistaken for a
+ * comment.
+ */
+export function parseJsonc(text) {
+    const withoutComments = text.replace(/("(?:\\.|[^"\\])*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (_, str) => str ?? '');
+    try {
+        return JSON.parse(withoutComments.replace(/,(\s*[}\]])/g, '$1'));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/languages/js/checks.js

@@ -4,6 +4,7 @@ import { checkFile, hookHasUncommented } from '../../base/checks.js';
 import { realGitExec } from '../../base/git-identity.js';
 import { CLAUDE_SETTINGS_FILE, readClaudeSettings, workspaceSymlinkDirs, worktreeSymlinkDirs, } from '../../cli/generators/agent-rules.js';
 import { WORKSPACE_FILE, dependsOnEsbuild, familyGlob, missingPnpmSettings, } from '../../cli/generators/pnpm-workspace.js';
+import { parseJsonc } from '../../cli/utils/jsonc.js';
 const PACKAGE = '@rtorcato/repo-tooling';
 const NODE_MIN_MAJOR = 22;
 const NODE_LTS_REQUIREMENTS = {
@@ -44,23 +45,6 @@ export function evaluateNodeVersion(version) {
         detail: display,
     };
 }
-/**
- * JSONC → object, or null when it genuinely won't parse. `biome.jsonc` is a
- * declared candidate and the format allows comments and trailing commas, so
- * bare `JSON.parse` would reject configs Biome itself accepts.
- *
- * The first alternative consumes whole string literals, so a `//` or `/*`
- * inside one (a `$schema` URL, most obviously) is never mistaken for a comment.
- */
-function parseJsonc(text) {
-    const withoutComments = text.replace(/("(?:\\.|[^"\\])*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (_, str) => str ?? '');
-    try {
-        return JSON.parse(withoutComments.replace(/,(\s*[}\]])/g, '$1'));
-    }
-    catch {
-        return null;
-    }
-}
 const BIOME_PRESET_REF = /@rtorcato\/(?:js|repo)-tooling\/biome/;
 /**
  * Both shapes of a `biome.json` this package produces (#378): the thin
@@ -1549,6 +1533,10 @@ export function rangeFloor(range) {
 function compareFloor(a, b) {
     return a[0] - b[0] || a[1] - b[1];
 }
+/** Full major.minor.patch ordering, for comparing an installed version. */
+function compareVersion(a, b) {
+    return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
 /**
  * Config files whose `$schema` URL carries the tool version the config is
  * written for, and the package that reads them. One entry per tool; adding
@@ -1639,6 +1627,61 @@ export async function checkConfigSchemaVersions(dir, pkg) {
         hint: 'Raise the dependency floor to the version the config targets, or rewrite the config for the oldest version supported. Anyone resolving below the schema version gets a config-parse error that never mentions the version range.',
     };
 }
+/**
+ * Installed peer versions against the ranges this package declares (#591).
+ *
+ * `checkConfigSchemaVersions` compares *declared* ranges; this compares what is
+ * actually on disk. A consumer scaffolded by an older generator can sit on
+ * `@biomejs/biome` 2.4.5 while the shipped preset uses `linter.rules.preset`,
+ * a 2.5 key — and the only symptom is a parse error pointing inside a file the
+ * consumer never wrote. The peer warning that would have said so scrolled past
+ * at install time.
+ *
+ * ponytail: only the floor is compared. Ranges like `^20.0.0 || ^21.0.0` or
+ * `>=5.0.0` have no single ceiling worth enforcing, and flagging a newer major
+ * would fire on every repo that upgrades ahead of the range. Add a real semver
+ * satisfies() if a peer ever ships a breaking major we must keep out.
+ */
+export async function checkPeerVersions(dir, pkg) {
+    const check = 'Peer versions';
+    const modules = path.join(dir, 'node_modules');
+    // Running against a consumer, the contract lives in the installed copy;
+    // running against this repo itself, it is the repo's own package.json.
+    const self = pkg?.name === PACKAGE ? pkg : await readPackageJson(path.join(modules, PACKAGE));
+    const peers = self?.peerDependencies ?? {};
+    const stale = [];
+    let checked = 0;
+    for (const [name, range] of Object.entries(peers)) {
+        const floor = rangeFloor(range);
+        if (!floor)
+            continue;
+        // Absent means the peer is simply unused — every one of ours is optional.
+        const installed = (await readPackageJson(path.join(modules, name)))?.version;
+        const version = typeof installed === 'string' ? rangeFloor(installed) : null;
+        if (!version)
+            continue;
+        checked++;
+        if (compareVersion(version, floor) < 0) {
+            stale.push(`${name} ${installed} installed, ${PACKAGE} requires ${range}`);
+        }
+    }
+    if (checked === 0) {
+        return { check, status: 'ok', detail: 'no installed peers to compare' };
+    }
+    if (stale.length === 0) {
+        return {
+            check,
+            status: 'ok',
+            detail: `${checked} installed peer${checked === 1 ? '' : 's'} satisfy the declared ranges`,
+        };
+    }
+    return {
+        check,
+        status: 'drift',
+        detail: `${stale.length} peer${stale.length === 1 ? '' : 's'} installed below the declared range: ${stale.join('; ')}`,
+        hint: 'Upgrade the named packages — a preset written for a newer version fails inside a file you cannot edit, with an error that never mentions the version.',
+    };
+}
 /** npm git specifiers, including the bare `owner/repo` GitHub shorthand. */
 const GIT_PROTOCOL = /^(?:github|gitlab|bitbucket|gist):|^git\+|^git:\/\//;
 const GITHUB_SHORTHAND = /^[A-Za-z0-9][\w.-]*\/[A-Za-z0-9][\w.-]*(?:#.*)?$/;

package/dist/languages/js/fixers.js

@@ -76,6 +76,9 @@ import { generateTypedocConfig, generateTypedocWorkflow } from '../../cli/genera
 import { copyPreset } from '../../cli/utils/copy-preset.js';
 import { identifiablePresetHashes } from '../../cli/utils/copied-assets.js';
 import { LOCKFILE_NAME, writeLockfile } from '../../cli/utils/lockfile.js';
+// The fixer contract moved to src/base/fixers.ts when Swift became the second
+// module (#286) — import it from there.
+import { FixerAbort } from '../../base/fixers.js';
 /** Exported so doctor can render the preset ci.yml it compares against (#349). */
 export function inferProjectConfig(pkg) {
     const deps = {
@@ -173,14 +176,21 @@ const GH_WORKFLOW_FIXERS = GH_WORKFLOWS.map((name) => ({
 export const FIXERS = [
     {
         target: 'biome',
-        description: `Scaffold ${BIOME_CONFIG} extending the @rtorcato/repo-tooling preset, plus the scripts that run it`,
+        description: `Point ${BIOME_CONFIG} at the @rtorcato/repo-tooling preset (merged into any existing config), plus the scripts that run it`,
         appliesTo: ['Biome'],
         outputs: [BIOME_CONFIG, 'package.json (scripts)'],
+        // safe-merge: only $schema/extends are rewritten, other keys are kept.
+        riskLevel: 'safe-merge',
         canFixDrift: true,
         async run({ targetDir }) {
             // Shares generateBiomeConfig with the setup/resync path — the two used to
             // scaffold different filenames with different contents (#365).
             const written = await generateBiomeConfig(targetDir);
+            // null means an existing config that won't parse. Refuse rather than
+            // replace it: its settings are unreadable, so they're unrecoverable (#587).
+            if (!written) {
+                throw new FixerAbort('biome-unparseable', `refusing to overwrite ${BIOME_CONFIG} — it does not parse as JSON/JSONC, so its settings cannot be merged`, `fix the syntax error in ${BIOME_CONFIG} (or delete it) and re-run \`fix biome\``);
+            }
             const filesWritten = [written];
             // A config with no way to run it left `pnpm check` undefined, which the
             // generated CI called and `fix verify` needed to compose a chain (#364).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.34.0",
+	"version": "3.36.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -158,6 +158,7 @@
 		"./typescript/node": "./tooling/typescript/tsconfig.node.json",
 		"./typescript/bun": "./tooling/typescript/tsconfig.bun.json",
 		"./typescript/react": "./tooling/typescript/tsconfig.react.json",
+		"./typescript/vite-app": "./tooling/typescript/tsconfig.vite-app.json",
 		"./typescript/test": "./tooling/typescript/tsconfig.test.json",
 		"./typescript/reset": "./tooling/typescript/reset.d.ts",
 		"./typescript/base@1": "./tooling/typescript/v1/tsconfig.base.json",
@@ -264,7 +265,7 @@
 		"cz-conventional-changelog": "^3.3.0",
 		"esbuild": "^0.28.2",
 		"esbuild-node-externals": "^2.0.0",
-		"eslint": "10.8.1",
+		"eslint": "10.9.1",
 		"eslint-plugin-import": "^2.32.0",
 		"eslint-plugin-jest": "29.16.1",
 		"husky": "^9.1.7",

package/skills/ai-issue-loop/SKILL.md

@@ -1483,13 +1483,31 @@ do the linking here:
 
 ```bash
 DIRS=$(jq -r '.worktree.symlinkDirectories[]? // empty' "$ROOT/.claude/settings.json" 2>/dev/null)
-for d in $DIRS; do
+printf '%s\n' "$DIRS" | while IFS= read -r d; do
+  [ -n "$d" ] || continue
   [ -d "$ROOT/$d" ] || continue          # an entry pointing at nothing links nothing
   mkdir -p "$(dirname "$WT_ROOT/$SLUG/$d")"
   ln -s "$ROOT/$d" "$WT_ROOT/$SLUG/$d"
 done
+
+# assert it happened — an unlinked worktree must never reach an implementer
+MISSING=$(printf '%s\n' "$DIRS" | while IFS= read -r d; do
+  [ -n "$d" ] && [ -d "$ROOT/$d" ] && [ ! -L "$WT_ROOT/$SLUG/$d" ] && printf '%s ' "$d"
+done)
+[ -z "$MISSING" ] || echo "FATAL: $SLUG has no symlink for: $MISSING"
 ```
 
+**Iterate line by line — never `for d in $DIRS`.** Your shell may be zsh, which
+does not word-split an unquoted expansion: `$DIRS` arrives as *one* word with
+embedded newlines, `[ -d ]` fails against that nonsense path, and the loop links
+**nothing** (#585). Same class as the Pass 2 glob hazard below, and just as
+silent — the `pnpm install` fallback is gated on `$DIRS` being *empty*, which it
+is not, so the worktree gets neither links nor an install, and the implementer
+meets `Cannot find module` on its first test run, reading as the issue's fault
+rather than the harness's. That is what the `MISSING` assertion is for: if it
+prints, do **not** spawn an implementer — run `pnpm install` in the worktree, or
+return the issue to `ai-ready`, drop `ai-wip`, and move on.
+
 **Read the setting, do not rely on it.** `worktree.symlinkDirectories` is a
 **Claude Code** setting, honoured by `EnterWorktree` — which this pipeline
 forbids outright (see below) and replaces with a raw `git worktree add`. So the

package/skills/dogfood/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: dogfood
+description: |
+  Run this repo's own tooling against throwaway greenfield fixtures in a temp
+  directory and report what breaks. Use when the user asks to "dogfood",
+  "test the tool on a fresh repo", "see what happens on a new project", or
+  invokes `/dogfood`. Asks what to exercise before it starts. Writes only
+  under a temp directory, never touches the repo's working tree, and never
+  deletes anything — it hands the path back for the user to remove.
+---
+
+# dogfood
+
+Point the repo's own tooling at repos it has never seen and find out what it
+does wrong. Arguments: $ARGUMENTS
+
+**The bugs live where the tool meets content it did not write.** An empty
+directory finds nothing — every finding from the run this skill is based on came
+from a fixture that already had a `package.json`, a manifest, or a source file
+with an opinion in it. Scaffolding onto nothing is the one case the authors
+already tested.
+
+## What this never does
+
+- **Never writes outside its temp directory.** Not the repo's working tree, not
+  `~/.claude`, not a global git config (`git config --global` writes a stowed
+  dotfile on this machine).
+- **Never deletes.** `rm` is often permission-blocked for an agent, and a
+  half-deleted fixture is worse than a kept one. Report the path and size at the
+  end; the user removes it when they are done reading it.
+- **Never files an issue without asking**, and never labels one `ai-ready` —
+  that label is the human's gate into `ai-issue-loop`.
+
+## Step 1 — ask what to exercise
+
+Use `AskUserQuestion`. Look at the repo first so the options are real — read its
+`package.json` `bin`, its CLI's `--help`, or its presets/templates directory —
+then ask:
+
+1. **What to exercise.** Offer the actual entry points found (multiSelect).
+   For a scaffolding tool that is its presets; for a linter its rule sets; for a
+   codemod its transforms.
+2. **Fixture shape.** *Realistic pre-existing repos* (recommended — this is what
+   finds bugs) vs *empty directories* (only worth it to check the happy path
+   still works).
+3. **What to do with findings.** *Report in the transcript only* (recommended
+   for a first run) vs *also file GitHub issues*. If they choose issues, every
+   one opens with `🤖 *Filed by an agent via dogfood.*` and carries no
+   `ai-ready` label.
+
+Skip a question the arguments already answer.
+
+## Step 2 — pin the build and the version
+
+**A finding with no version stamp is unreproducible and will be argued with.**
+Build from source, and record the commit — not the version in `package.json`,
+which under semantic-release without `@semantic-release/git` never moves:
+
+```bash
+ROOT=$(git rev-parse --show-toplevel)
+cd "$ROOT" && pnpm build-cli          # or whatever CLAUDE.md says the build is
+REF=$(git -C "$ROOT" rev-parse --short HEAD)
+DIRTY=$(git -C "$ROOT" status --porcelain | head -1)
+```
+
+Say in every finding: *Reproduced with `dist/` built from `<REF>`*, and mention
+it if the tree was dirty. Invoke the built artefact directly
+(`node "$ROOT/dist/cli/index.js" …`) — never `npx <package>`, which silently
+tests the *published* version instead of the working tree.
+
+## Step 3 — make the temp root, once
+
+```bash
+BASE="${TMPDIR:-/tmp}/dogfood-$REF-$$"
+mkdir -p "$BASE"
+echo "$BASE"
+```
+
+**Pin `$BASE` as an absolute path and reuse that literal for the rest of the
+run.** `$TMPDIR` resolves differently inside and outside the command sandbox, so
+re-expanding it in a later command lands in a different directory and the run
+silently splits in two. A unique suffix means a re-run never collides, which is
+what makes never-deleting safe.
+
+## Step 4 — build each fixture, and commit it
+
+A fixture is a *plausible* repo, not a stub. Give it the things the tool will
+read and be tempted to rewrite: a real name (scoped and unscoped both matter —
+a scope is a code path), a source file, a manifest that already declares
+something, an existing script.
+
+Then **`git init` and commit it**. That baseline commit is the whole trick:
+
+```bash
+git -C "$BASE/$NAME" init -q
+git -C "$BASE/$NAME" add -A
+git -C "$BASE/$NAME" -c user.email=dogfood@local -c user.name=dogfood commit -qm baseline
+```
+
+`-c` on the command, never `git config --global`. Without the commit, "what did
+the tool overwrite" is a question nobody can answer afterwards.
+
+## Step 5 — before, run, after
+
+```bash
+node "$ROOT/dist/cli/index.js" doctor --json > "$BASE/$NAME.before.json" 2>&1 || true
+node "$ROOT/dist/cli/index.js" setup --preset <p> --yes > "$BASE/$NAME.setup.log" 2>&1; echo "exit=$?"
+node "$ROOT/dist/cli/index.js" doctor --json > "$BASE/$NAME.after.json" 2>&1 || true
+```
+
+`> file 2>&1`, in that order — `2>&1 > file` leaves stderr on the terminal, which
+is where the interesting output usually is. `|| true` because a diagnostic
+command exiting non-zero *is* data, not a reason to abort the run.
+
+## Step 6 — the three checks that actually find things
+
+Run all three on every fixture. Each one found a distinct real bug.
+
+### a. What did it overwrite?
+
+```bash
+git -C "$BASE/$NAME" diff --stat
+git -C "$BASE/$NAME" diff -- <every file the tool claims to merge rather than replace>
+```
+
+A tool that says it preserves your `name`, `version`, and scripts is making a
+promise; the diff is where you check it. This is how a preset was caught
+renaming a package after its directory and orphaning the sources — **and the
+build still exited 0**, because the build system ignored the now-undeclared
+directory. A green build is not evidence.
+
+### b. Does it pass its own check?
+
+```bash
+node "$ROOT/dist/cli/index.js" doctor; echo "exit=$?"
+```
+
+Non-zero on a repo the tool itself just created is a bug every time, however
+small the detail. "Run setup, you're aligned" either holds or the promise is
+worthless — and a user's CI or pre-commit hook keys on exactly that exit code.
+Diff `before.json` against `after.json` too: a check that *stopped* running is
+invisible in the exit code.
+
+### c. Does the contract it wrote actually hold?
+
+The subtlest class, and the most damaging. The tool writes a *declaration* —
+`exports`, `main`, entry points, a target list — and separately preserves a
+*producer* — the build script. Nothing checks that the producer emits what the
+declaration promises. So:
+
+```bash
+cd "$BASE/$NAME" && <the repo's own build> && ls -R dist 2>/dev/null
+```
+
+then read the manifest and confirm every path it names exists on disk. A package
+whose `main` points at a file its own `build` cannot emit publishes green and
+breaks every consumer.
+
+## Step 7 — report
+
+Per fixture, one short block: preset, exit codes, and each finding as
+*what happened → why it matters → the evidence*. Paste the diff hunk or the JSON
+line; a paraphrase is not a reproduction.
+
+Rank by **silence, not severity**. A loud failure gets noticed by whoever hits
+it. A wrong result that exits 0 does not, and that is the finding worth the
+user's attention — lead with it.
+
+If the user chose to file issues, one issue per finding, ≤30 lines each: what,
+the minimal reproduction, the version stamp, and a `## What to change` section
+that names the options rather than picking one. Attach no `ai-ready`.
+
+**Say what you could not test.** A preset you skipped, a build you could not
+run, an area still in flight — an unexamined corner reported as unexamined is
+useful; one left silent reads as covered.
+
+## Step 8 — hand back the temp directory
+
+Last line of the run, always:
+
+```bash
+du -sh "$BASE"
+```
+
+Tell the user the path and the size, and give them the exact command:
+
+```
+! rm -rf <BASE>
+```
+
+The `!` prefix runs it in their session. Do not run it yourself, do not offer to
+run it later, and do not delete it on a subsequent invocation — the fixtures are
+the evidence behind every finding, and they are worth more than the disk.
+
+## Gotchas that cost real time
+
+- **Shell aliases corrupt captured output.** `ls` aliased to a colouriser emits
+  escape codes into anything you parse. `unalias ls` / `unalias g` first, or use
+  `command ls`.
+- **Ambient `GIT_DIR` / `GIT_WORK_TREE` / `GIT_CONFIG*` outrank `-C`.** If any is
+  exported, every fixture git command silently operates on the wrong repo.
+  `env -u GIT_DIR -u GIT_WORK_TREE git …` when in doubt.
+- **A function, not a variable, for a wrapped command.** `G="env -u X git"` does
+  not word-split under zsh; define `g() { env -u X git "$@"; }`.
+- **`pnpm install` may need the sandbox disabled** — it writes to a store outside
+  the working directory. That is a legitimate escalation for this one command.
+- **Never reuse a fixture between runs.** A second `setup` over an
+  already-set-up repo tests idempotency, which is a different question; mixing
+  the two makes both answers unreliable.

package/tooling/biome/preset.json

@@ -54,6 +54,12 @@
       "semicolons": "asNeeded"
     }
   },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true,
+      "cssModules": true
+    }
+  },
   "json": {
     "formatter": {
       "indentStyle": "space",

package/tooling/claude/repo-tooling.md

@@ -63,7 +63,7 @@ npx @rtorcato/repo-tooling setup --config project.json -d ./my-lib --skip-instal
 
 ## Drift policy (don't surprise the user)
 
-- Safe-merge fixers (`engines`, `husky`, `package-json`) never overwrite — they add/merge.
+- Safe-merge fixers (`biome`, `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,

package/tooling/typescript/tsconfig.vite-app.json

@@ -0,0 +1,16 @@
+{
+  "extends": "./tsconfig.react.json",
+  "compilerOptions": {
+    // `vite/client` is what makes `import.meta.env` and the `?url` / `?raw`
+    // import suffixes typecheck. It lives here rather than in the react preset
+    // because every `types` entry must resolve: adding it there would fail with
+    // TS2688 on any React project that doesn't install Vite — the same trap that
+    // got "tailwindcss" dropped from the react preset.
+    "types": ["react", "react-dom", "vitest", "vite/client"]
+  },
+  // An app's `typecheck` is a CI gate, not a build, so the tests are checked
+  // too — they're the code most likely to drift after a signature change. The
+  // react preset excludes them because a library's tsc run emits dist/.
+  "include": ["src", "index.d.ts", "types", "tests"],
+  "exclude": ["node_modules", "dist", "build", "out"]
+}