@rtorcato/js-tooling 2.2.0 → 2.4.0

package/dist/cli/commands/doctor.js

@@ -1,6 +1,7 @@
+import path from 'node:path';
 import chalk from 'chalk';
 import fs from 'fs-extra';
-import path from 'node:path';
+import { getFixTargetForCheck } from './fix-targets.js';
 const PACKAGE = '@rtorcato/js-tooling';
 const NODE_MIN_MAJOR = 22;
 const NODE_LTS_REQUIREMENTS = {
@@ -71,6 +72,7 @@ const FILE_CHECKS = [
         expected: `imports "${PACKAGE}/prettier"`,
         matcher: /@rtorcato\/js-tooling\/prettier/,
         optional: true,
+        hint: `Re-export from "${PACKAGE}/prettier" in prettier.config.mjs`,
     },
     {
         check: 'Vitest',
@@ -114,17 +116,29 @@ async function checkFile(dir, spec) {
         hint: spec.hint,
     };
 }
-async function checkPackageJson(dir) {
+async function readPackageJson(dir) {
     const filepath = path.join(dir, 'package.json');
-    if (!(await fs.pathExists(filepath))) {
+    if (!(await fs.pathExists(filepath)))
+        return null;
+    try {
+        return (await fs.readJson(filepath));
+    }
+    catch {
+        return null;
+    }
+}
+function checkPackageJson(pkg) {
+    if (!pkg) {
         return {
             check: 'package.json',
             status: 'missing',
             detail: 'no package.json found',
         };
     }
-    const pkg = await fs.readJson(filepath);
-    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    const deps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+    };
     if (deps[PACKAGE]) {
         return {
             check: 'package.json',
@@ -139,14 +153,345 @@ async function checkPackageJson(dir) {
         hint: `Run \`pnpm add -D ${PACKAGE}\``,
     };
 }
+function checkEnginesNode(pkg) {
+    if (!pkg) {
+        return {
+            check: 'engines.node',
+            status: 'missing',
+            detail: 'no package.json',
+        };
+    }
+    const engines = pkg.engines ?? {};
+    if (!engines.node) {
+        return {
+            check: 'engines.node',
+            status: 'drift',
+            detail: 'engines.node not set in package.json',
+            hint: `Add \`"engines": { "node": ">=${NODE_MIN_MAJOR}" }\` to package.json`,
+        };
+    }
+    return {
+        check: 'engines.node',
+        status: 'ok',
+        detail: `engines.node = ${engines.node}`,
+    };
+}
+async function checkEditorConfig(dir) {
+    const exists = await fs.pathExists(path.join(dir, '.editorconfig'));
+    return {
+        check: 'EditorConfig',
+        status: exists ? 'ok' : 'optional-missing',
+        detail: exists ? '.editorconfig found' : 'no .editorconfig',
+        hint: exists ? undefined : 'Add an .editorconfig for cross-editor formatting consistency',
+    };
+}
+async function checkNodeVersionPin(dir) {
+    for (const candidate of ['.nvmrc', '.node-version']) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            return {
+                check: 'Node version pin',
+                status: 'ok',
+                detail: `${candidate} found`,
+            };
+        }
+    }
+    return {
+        check: 'Node version pin',
+        status: 'optional-missing',
+        detail: 'no .nvmrc / .node-version',
+        hint: 'Add .nvmrc to pin Node version per repo (e.g. `echo 22 > .nvmrc`)',
+    };
+}
+async function checkHusky(dir, pkg) {
+    const huskyDir = await fs.pathExists(path.join(dir, '.husky'));
+    const scripts = pkg?.scripts ?? {};
+    const prepareScript = scripts.prepare ?? '';
+    const hasHookScript = /\bhusky\b/.test(prepareScript);
+    if (huskyDir && hasHookScript) {
+        return {
+            check: 'Husky',
+            status: 'ok',
+            detail: '.husky/ directory and prepare script configured',
+        };
+    }
+    if (huskyDir || hasHookScript) {
+        return {
+            check: 'Husky',
+            status: 'drift',
+            detail: huskyDir
+                ? '.husky/ exists but no `prepare: husky` script'
+                : '`prepare: husky` set but no .husky/ directory',
+            hint: 'Run `pnpm exec husky init` to scaffold both halves',
+        };
+    }
+    return {
+        check: 'Husky',
+        status: 'optional-missing',
+        detail: 'husky not configured',
+        hint: 'Run `pnpm add -D husky && pnpm exec husky init` to enable git hooks',
+    };
+}
+const LINT_STAGED_FILES = [
+    '.lintstagedrc',
+    '.lintstagedrc.json',
+    '.lintstagedrc.yaml',
+    '.lintstagedrc.yml',
+    '.lintstagedrc.js',
+    '.lintstagedrc.cjs',
+    '.lintstagedrc.mjs',
+    'lint-staged.config.js',
+    'lint-staged.config.cjs',
+    'lint-staged.config.mjs',
+];
+async function checkLintStaged(dir, pkg) {
+    const inPkg = pkg ? 'lint-staged' in pkg : false;
+    let inFile = null;
+    for (const candidate of LINT_STAGED_FILES) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            inFile = candidate;
+            break;
+        }
+    }
+    if (inPkg || inFile) {
+        return {
+            check: 'lint-staged',
+            status: 'ok',
+            detail: inPkg ? '`lint-staged` field in package.json' : `${inFile} found`,
+        };
+    }
+    return {
+        check: 'lint-staged',
+        status: 'optional-missing',
+        detail: 'lint-staged not configured',
+        hint: 'Add a `lint-staged` field to package.json and wire it into the husky pre-commit hook',
+    };
+}
+const KNIP_FILES = [
+    'knip.json',
+    'knip.jsonc',
+    'knip.ts',
+    'knip.config.ts',
+    'knip.config.js',
+    'knip.config.mjs',
+];
+async function checkKnip(dir, pkg) {
+    const inPkg = pkg ? 'knip' in pkg : false;
+    let inFile = null;
+    for (const candidate of KNIP_FILES) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            inFile = candidate;
+            break;
+        }
+    }
+    if (inPkg || inFile) {
+        return {
+            check: 'knip',
+            status: 'ok',
+            detail: inPkg ? '`knip` field in package.json' : `${inFile} found`,
+        };
+    }
+    return {
+        check: 'knip',
+        status: 'optional-missing',
+        detail: 'knip not configured',
+        hint: 'Add `knip` to detect unused files, deps, and exports',
+    };
+}
+const SEMANTIC_RELEASE_FILES = [
+    '.releaserc',
+    '.releaserc.json',
+    '.releaserc.yaml',
+    '.releaserc.yml',
+    '.releaserc.js',
+    '.releaserc.cjs',
+    'release.config.js',
+    'release.config.cjs',
+    'release.config.mjs',
+];
+async function checkSemanticRelease(dir, pkg) {
+    const isPrivate = pkg?.private === true;
+    const inPkg = pkg ? 'release' in pkg : false;
+    let configFile = null;
+    let configContent = null;
+    for (const candidate of SEMANTIC_RELEASE_FILES) {
+        const filepath = path.join(dir, candidate);
+        if (await fs.pathExists(filepath)) {
+            configFile = candidate;
+            try {
+                configContent = await fs.readFile(filepath, 'utf-8');
+            }
+            catch {
+                configContent = '';
+            }
+            break;
+        }
+    }
+    if (!inPkg && !configFile) {
+        return {
+            check: 'semantic-release',
+            status: isPrivate ? 'optional-missing' : 'drift',
+            detail: isPrivate
+                ? 'semantic-release not configured (package is private)'
+                : 'semantic-release not configured',
+            hint: isPrivate
+                ? undefined
+                : `Extend "${PACKAGE}/semantic-release" or "${PACKAGE}/semantic-release/github" in a release config`,
+        };
+    }
+    const presetRegex = /@rtorcato\/js-tooling\/semantic-release/;
+    const pkgReleaseStr = inPkg ? JSON.stringify(pkg?.release ?? '') : '';
+    const usesPreset = (configContent && presetRegex.test(configContent)) || presetRegex.test(pkgReleaseStr);
+    if (usesPreset) {
+        return {
+            check: 'semantic-release',
+            status: 'ok',
+            detail: configFile
+                ? `${configFile} extends ${PACKAGE}/semantic-release`
+                : `release field extends ${PACKAGE}/semantic-release`,
+        };
+    }
+    return {
+        check: 'semantic-release',
+        status: 'drift',
+        detail: configFile
+            ? `${configFile} does not extend ${PACKAGE}/semantic-release`
+            : '`release` field does not extend our preset',
+        hint: `Extend "${PACKAGE}/semantic-release" or "${PACKAGE}/semantic-release/github"`,
+    };
+}
+async function checkGitHubActions(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir))) {
+        return {
+            check: 'GitHub Actions',
+            status: 'optional-missing',
+            detail: 'no .github/workflows/',
+            hint: 'Run `npx @rtorcato/js-tooling setup` to scaffold a CI workflow',
+        };
+    }
+    try {
+        const files = await fs.readdir(workflowsDir);
+        const workflows = files.filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        if (workflows.length === 0) {
+            return {
+                check: 'GitHub Actions',
+                status: 'optional-missing',
+                detail: '.github/workflows/ is empty',
+                hint: 'Add a workflow file (e.g. ci.yml) under .github/workflows/',
+            };
+        }
+        return {
+            check: 'GitHub Actions',
+            status: 'ok',
+            detail: `${workflows.length} workflow${workflows.length === 1 ? '' : 's'} in .github/workflows/`,
+        };
+    }
+    catch {
+        return {
+            check: 'GitHub Actions',
+            status: 'optional-missing',
+            detail: 'unable to read .github/workflows/',
+        };
+    }
+}
+async function checkDependabot(dir) {
+    for (const candidate of ['.github/dependabot.yml', '.github/dependabot.yaml']) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            return {
+                check: 'Dependabot',
+                status: 'ok',
+                detail: `${candidate} found`,
+            };
+        }
+    }
+    return {
+        check: 'Dependabot',
+        status: 'optional-missing',
+        detail: 'no .github/dependabot.yml',
+        hint: 'Run `npx @rtorcato/js-tooling fix dependabot` to scaffold weekly dep updates',
+    };
+}
+async function checkCodeQL(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir))) {
+        return {
+            check: 'CodeQL',
+            status: 'optional-missing',
+            detail: 'no .github/workflows/',
+            hint: 'Run `npx @rtorcato/js-tooling fix codeql` to scaffold CodeQL security scanning',
+        };
+    }
+    for (const candidate of ['codeql.yml', 'codeql.yaml']) {
+        if (await fs.pathExists(path.join(workflowsDir, candidate))) {
+            return {
+                check: 'CodeQL',
+                status: 'ok',
+                detail: `.github/workflows/${candidate} found`,
+            };
+        }
+    }
+    try {
+        const files = await fs.readdir(workflowsDir);
+        for (const f of files) {
+            if (!(f.endsWith('.yml') || f.endsWith('.yaml')))
+                continue;
+            const content = await fs.readFile(path.join(workflowsDir, f), 'utf-8');
+            if (/github\/codeql-action/.test(content)) {
+                return {
+                    check: 'CodeQL',
+                    status: 'ok',
+                    detail: `codeql-action referenced in ${f}`,
+                };
+            }
+        }
+    }
+    catch {
+        // fall through to optional-missing
+    }
+    return {
+        check: 'CodeQL',
+        status: 'optional-missing',
+        detail: 'no codeql workflow found',
+        hint: 'Run `npx @rtorcato/js-tooling fix codeql` to scaffold CodeQL security scanning',
+    };
+}
+async function checkGitLabCI(dir) {
+    for (const candidate of ['.gitlab-ci.yml', '.gitlab-ci.yaml']) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            return {
+                check: 'GitLab CI',
+                status: 'ok',
+                detail: `${candidate} found`,
+            };
+        }
+    }
+    return {
+        check: 'GitLab CI',
+        status: 'optional-missing',
+        detail: 'no .gitlab-ci.yml',
+        hint: 'Add a .gitlab-ci.yml if this repo is hosted on GitLab',
+    };
+}
 export async function runDoctor(dir) {
     const targetDir = path.resolve(dir);
+    const pkg = await readPackageJson(targetDir);
     const results = [];
     results.push(evaluateNodeVersion(process.version));
-    results.push(await checkPackageJson(targetDir));
+    results.push(checkPackageJson(pkg));
+    results.push(checkEnginesNode(pkg));
+    results.push(await checkEditorConfig(targetDir));
+    results.push(await checkNodeVersionPin(targetDir));
     for (const spec of FILE_CHECKS) {
         results.push(await checkFile(targetDir, spec));
     }
+    results.push(await checkHusky(targetDir, pkg));
+    results.push(await checkLintStaged(targetDir, pkg));
+    results.push(await checkSemanticRelease(targetDir, pkg));
+    results.push(await checkKnip(targetDir, pkg));
+    results.push(await checkGitHubActions(targetDir));
+    results.push(await checkDependabot(targetDir));
+    results.push(await checkCodeQL(targetDir));
+    results.push(await checkGitLabCI(targetDir));
     return results;
 }
 const STATUS_ICONS = {
@@ -167,6 +512,30 @@ function statusLabel(status) {
             return chalk.gray('not configured');
     }
 }
+const MAX_NEXT_STEP_SUGGESTIONS = 8;
+export function nextStepSuggestions(results) {
+    const fixable = results.filter((r) => r.status === 'drift' || r.status === 'missing' || r.status === 'optional-missing');
+    const lines = [];
+    let overflow = 0;
+    for (const r of fixable) {
+        const target = getFixTargetForCheck(r.check);
+        if (!target)
+            continue;
+        if (lines.length >= MAX_NEXT_STEP_SUGGESTIONS) {
+            overflow++;
+            continue;
+        }
+        const verb = r.status === 'drift' ? 'align' : 'scaffold';
+        lines.push(`Run \`npx @rtorcato/js-tooling fix ${target}\` to ${verb} ${r.check}`);
+    }
+    if (overflow > 0) {
+        lines.push(`...and ${overflow} more — run \`npx @rtorcato/js-tooling fix\` to walk all findings`);
+    }
+    else if (lines.length > 0) {
+        lines.push('Run `npx @rtorcato/js-tooling fix` to walk all findings interactively');
+    }
+    return lines;
+}
 export function summarize(results) {
     return {
         ok: results.filter((r) => r.status === 'ok').length,
@@ -186,13 +555,21 @@ export async function doctorCommand(options = {}) {
         for (const r of results) {
             console.log(`  ${STATUS_ICONS[r.status]} ${chalk.bold(r.check)} — ${statusLabel(r.status)}`);
             console.log(`     ${chalk.gray(r.detail)}`);
-            if (r.hint && (r.status === 'drift' || r.status === 'missing')) {
+            if (r.hint && r.status !== 'ok') {
                 console.log(`     ${chalk.dim('hint:')} ${chalk.dim(r.hint)}`);
             }
         }
         const summary = summarize(results);
         console.log();
         console.log(`  Summary: ${chalk.green(`${summary.ok} ok`)}, ${chalk.yellow(`${summary.drift} drift`)}, ${chalk.red(`${summary.missing} missing`)}, ${chalk.gray(`${summary.optionalMissing} not configured`)}\n`);
+        const suggestions = nextStepSuggestions(results);
+        if (suggestions.length > 0) {
+            console.log(chalk.bold('  Next steps:'));
+            for (const s of suggestions) {
+                console.log(`    ${chalk.gray('-')} ${s}`);
+            }
+            console.log();
+        }
     }
     const summary = summarize(results);
     const exitCode = summary.drift > 0 || summary.missing > 0 ? 1 : 0;

package/dist/cli/commands/fix-targets.js

@@ -0,0 +1,22 @@
+export const FIX_TARGETS = {
+    'package.json': 'package-json',
+    'engines.node': 'engines',
+    EditorConfig: 'editorconfig',
+    'Node version pin': 'nvmrc',
+    TypeScript: 'tsconfig',
+    Biome: 'biome',
+    ESLint: 'eslint',
+    Prettier: 'prettier',
+    Vitest: 'vitest',
+    Commitlint: 'commitlint',
+    Husky: 'husky',
+    'lint-staged': 'husky',
+    'semantic-release': 'semantic-release',
+    knip: 'knip',
+    'GitHub Actions': 'github-actions',
+    Dependabot: 'dependabot',
+    CodeQL: 'codeql',
+};
+export function getFixTargetForCheck(checkName) {
+    return FIX_TARGETS[checkName] ?? null;
+}

package/dist/cli/commands/fix.js

@@ -0,0 +1,354 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import inquirer from 'inquirer';
+import { generateSemanticReleaseConfig } from '../generators/build.js';
+import { generateCommitlintConfig, generateHuskyConfig } from '../generators/git.js';
+import { generateGitHubActions } from '../generators/github-actions.js';
+import { generateESLintConfig, generatePrettierConfig } from '../generators/linting.js';
+import { ensureEnginesNode, generateEditorConfig, generateKnipConfig, generateNvmrc, } from '../generators/misc.js';
+import { generateCodeQLWorkflow, generateDependabotConfig } from '../generators/security.js';
+import { generateVitestConfig } from '../generators/testing.js';
+import { copyPreset } from '../utils/copy-preset.js';
+import { runDoctor } from './doctor.js';
+function inferProjectConfig(pkg) {
+    const deps = {
+        ...(pkg?.dependencies ?? {}),
+        ...(pkg?.devDependencies ?? {}),
+    };
+    let projectType = 'library';
+    if (deps.next)
+        projectType = 'nextjs-app';
+    else if (deps['react-dom'])
+        projectType = 'react-app';
+    return {
+        projectName: pkg?.name ?? 'project',
+        projectType,
+        typescript: { enabled: true, config: projectType === 'nextjs-app' ? 'next' : 'base' },
+        linting: {
+            tool: 'biome',
+            eslintConfig: projectType === 'nextjs-app' ? 'nextjs' : 'base',
+        },
+        formatting: { tool: 'biome' },
+        testing: { framework: 'vitest', environment: 'node' },
+        gitHooks: true,
+        commitLint: true,
+        semanticRelease: pkg?.private !== true,
+        securityAutomation: true,
+        bundler: 'tsup',
+    };
+}
+async function readPackageJson(dir) {
+    const filepath = path.join(dir, 'package.json');
+    if (!(await fs.pathExists(filepath)))
+        return null;
+    try {
+        return (await fs.readJson(filepath));
+    }
+    catch {
+        return null;
+    }
+}
+const FIXERS = [
+    {
+        target: 'biome',
+        description: 'Scaffold biome.json extending the @rtorcato/js-tooling preset',
+        appliesTo: ['Biome'],
+        outputs: ['biome.json'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('biome', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'tsconfig',
+        description: 'Scaffold tsconfig.json extending the @rtorcato/js-tooling preset',
+        appliesTo: ['TypeScript'],
+        outputs: ['tsconfig.json'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('tsconfig', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'eslint',
+        description: 'Scaffold eslint.config.mjs importing the @rtorcato/js-tooling preset',
+        appliesTo: ['ESLint'],
+        outputs: ['eslint.config.mjs'],
+        canFixDrift: true,
+        async run({ targetDir, pkg }) {
+            await generateESLintConfig(inferProjectConfig(pkg), targetDir);
+            return { filesWritten: ['eslint.config.mjs'] };
+        },
+    },
+    {
+        target: 'prettier',
+        description: 'Scaffold prettier.config.mjs re-exporting the preset',
+        appliesTo: ['Prettier'],
+        outputs: ['prettier.config.mjs'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            await generatePrettierConfig(targetDir);
+            return { filesWritten: ['prettier.config.mjs'] };
+        },
+    },
+    {
+        target: 'vitest',
+        description: 'Scaffold vitest.config.ts (preserves vitest.setup.ts if present)',
+        appliesTo: ['Vitest'],
+        outputs: ['vitest.config.ts'],
+        canFixDrift: true,
+        async run({ targetDir, pkg }) {
+            const setupPath = path.join(targetDir, 'vitest.setup.ts');
+            const hadSetup = await fs.pathExists(setupPath);
+            const savedSetup = hadSetup ? await fs.readFile(setupPath, 'utf-8') : null;
+            await generateVitestConfig(inferProjectConfig(pkg), targetDir);
+            if (hadSetup && savedSetup !== null) {
+                await fs.writeFile(setupPath, savedSetup);
+            }
+            return { filesWritten: ['vitest.config.ts'] };
+        },
+    },
+    {
+        target: 'commitlint',
+        description: 'Scaffold commitlint.config.mjs exporting the preset',
+        appliesTo: ['Commitlint'],
+        outputs: ['commitlint.config.mjs'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            await generateCommitlintConfig(targetDir);
+            return { filesWritten: ['commitlint.config.mjs'] };
+        },
+    },
+    {
+        target: 'husky',
+        description: 'Set up Husky + lint-staged (deep-merges existing lint-staged field)',
+        appliesTo: ['Husky', 'lint-staged'],
+        outputs: ['.husky/pre-commit', 'package.json (lint-staged field)'],
+        canFixDrift: true,
+        async run({ targetDir, pkg }) {
+            const pkgPath = path.join(targetDir, 'package.json');
+            const existingLintStaged = pkg?.['lint-staged'] ?? {};
+            await generateHuskyConfig(inferProjectConfig(pkg), targetDir);
+            const updated = (await fs.readJson(pkgPath));
+            const generated = updated['lint-staged'] ?? {};
+            updated['lint-staged'] = { ...generated, ...existingLintStaged };
+            await fs.writeJson(pkgPath, updated, { spaces: 2 });
+            return { filesWritten: ['.husky/pre-commit', 'package.json'] };
+        },
+    },
+    {
+        target: 'semantic-release',
+        description: 'Scaffold release.config.mjs (skipped on private packages)',
+        appliesTo: ['semantic-release'],
+        outputs: ['release.config.mjs'],
+        canFixDrift: true,
+        async run({ targetDir, pkg }) {
+            if (pkg?.private === true) {
+                console.log(chalk.gray('   skipping — package is private'));
+                return { filesWritten: [] };
+            }
+            await generateSemanticReleaseConfig(targetDir);
+            return { filesWritten: ['release.config.mjs'] };
+        },
+    },
+    {
+        target: 'github-actions',
+        description: 'Scaffold .github/workflows/ci.yml',
+        appliesTo: ['GitHub Actions'],
+        outputs: ['.github/workflows/ci.yml'],
+        canFixDrift: true,
+        async run({ targetDir, pkg }) {
+            await generateGitHubActions(inferProjectConfig(pkg), targetDir);
+            return { filesWritten: ['.github/workflows/ci.yml'] };
+        },
+    },
+    {
+        target: 'dependabot',
+        description: 'Scaffold .github/dependabot.yml (weekly npm + actions updates)',
+        appliesTo: ['Dependabot'],
+        outputs: ['.github/dependabot.yml'],
+        async run({ targetDir }) {
+            await generateDependabotConfig(targetDir);
+            return { filesWritten: ['.github/dependabot.yml'] };
+        },
+    },
+    {
+        target: 'codeql',
+        description: 'Scaffold .github/workflows/codeql.yml (security scanning)',
+        appliesTo: ['CodeQL'],
+        outputs: ['.github/workflows/codeql.yml'],
+        async run({ targetDir }) {
+            await generateCodeQLWorkflow(targetDir);
+            return { filesWritten: ['.github/workflows/codeql.yml'] };
+        },
+    },
+    {
+        target: 'editorconfig',
+        description: 'Scaffold .editorconfig (UTF-8, LF, tab indent)',
+        appliesTo: ['EditorConfig'],
+        outputs: ['.editorconfig'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            await generateEditorConfig(targetDir);
+            return { filesWritten: ['.editorconfig'] };
+        },
+    },
+    {
+        target: 'nvmrc',
+        description: 'Scaffold .nvmrc pinned to Node 22',
+        appliesTo: ['Node version pin'],
+        outputs: ['.nvmrc'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            await generateNvmrc(targetDir);
+            return { filesWritten: ['.nvmrc'] };
+        },
+    },
+    {
+        target: 'engines',
+        description: 'Add engines.node to package.json (never overwrites)',
+        appliesTo: ['engines.node'],
+        outputs: ['package.json (engines.node field)'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await ensureEnginesNode(targetDir);
+            return { filesWritten: result === 'added' ? ['package.json'] : [] };
+        },
+    },
+    {
+        target: 'knip',
+        description: 'Scaffold knip.json with default entry/project globs',
+        appliesTo: ['knip'],
+        outputs: ['knip.json'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            await generateKnipConfig(targetDir);
+            return { filesWritten: ['knip.json'] };
+        },
+    },
+    {
+        target: 'package-json',
+        description: 'Add @rtorcato/js-tooling to devDependencies',
+        appliesTo: ['package.json'],
+        outputs: ['package.json (devDependencies)'],
+        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 ?? {}),
+            };
+            devDeps['@rtorcato/js-tooling'] = 'latest';
+            updated.devDependencies = devDeps;
+            await fs.writeJson(pkgPath, updated, { spaces: 2 });
+            console.log(chalk.dim('   reminder: run `pnpm install` to install the new dep'));
+            return { filesWritten: ['package.json'] };
+        },
+    },
+];
+export function getFixers() {
+    return FIXERS;
+}
+function findFixer(target) {
+    const normalized = target.toLowerCase();
+    return FIXERS.find((f) => f.target.toLowerCase() === normalized);
+}
+function findFixerForCheck(checkName) {
+    return FIXERS.find((f) => f.appliesTo.includes(checkName));
+}
+function logTargets() {
+    console.log(chalk.gray('Available fix targets:'));
+    for (const f of FIXERS) {
+        console.log(`  ${chalk.green('●')} ${chalk.bold(f.target)}: ${chalk.gray(f.description)}`);
+    }
+}
+async function applyFixer(fixer, result, targetDir, pkg, dryRun) {
+    if (dryRun) {
+        console.log(chalk.cyan(`  [dry-run] would write: ${fixer.outputs.join(', ')}`));
+        return { applied: true, written: [] };
+    }
+    const { filesWritten } = await fixer.run({ targetDir, pkg, result });
+    if (filesWritten.length > 0) {
+        console.log(chalk.green(`  ✅ wrote ${filesWritten.join(', ')}`));
+    }
+    return { applied: true, written: filesWritten };
+}
+async function confirmApply(fixer, result, assumeYes) {
+    if (assumeYes)
+        return true;
+    const isDrift = result.status === 'drift';
+    const message = isDrift
+        ? `⚠️  ${fixer.description} — overwrite existing file? user customizations will be lost`
+        : `Apply ${fixer.description}?`;
+    const { confirm } = await inquirer.prompt([
+        { type: 'confirm', name: 'confirm', message, default: !isDrift },
+    ]);
+    return confirm === true;
+}
+export async function fixCommand(target, options = {}) {
+    const targetDir = path.resolve(options.directory ?? process.cwd());
+    const assumeYes = options.yes === true;
+    const dryRun = options.dryRun === true;
+    const pkg = await readPackageJson(targetDir);
+    const results = await runDoctor(targetDir);
+    if (target) {
+        const fixer = findFixer(target);
+        if (!fixer) {
+            console.error(chalk.red(`\n❌ Unknown fix target: ${target}\n`));
+            logTargets();
+            console.log();
+            process.exit(1);
+        }
+        const result = results.find((r) => fixer.appliesTo.includes(r.check)) ??
+            { check: fixer.appliesTo[0] ?? fixer.target, status: 'missing', detail: '' };
+        if (result.status === 'ok') {
+            console.log(chalk.green(`\n✅ ${result.check} is already configured\n`));
+            return;
+        }
+        console.log(chalk.cyan(`\n🔧 ${fixer.target} — ${chalk.bold(result.check)} is ${result.status}\n`));
+        const ok = await confirmApply(fixer, result, assumeYes);
+        if (!ok) {
+            console.log(chalk.gray('   skipped\n'));
+            return;
+        }
+        await applyFixer(fixer, result, targetDir, pkg, dryRun);
+        console.log();
+        return;
+    }
+    // No target — walk all non-ok results
+    const fixable = results.filter((r) => r.status !== 'ok');
+    if (fixable.length === 0) {
+        console.log(chalk.green('\n✅ All checks pass — nothing to fix\n'));
+        return;
+    }
+    console.log(chalk.cyan(`\n🔧 ${fixable.length} item(s) to address\n`));
+    let applied = 0;
+    let skipped = 0;
+    let unsupported = 0;
+    for (const result of fixable) {
+        const fixer = findFixerForCheck(result.check);
+        if (!fixer) {
+            console.log(chalk.gray(`  — ${result.check}: no fixer registered`));
+            unsupported++;
+            continue;
+        }
+        console.log(`  ${chalk.bold(result.check)} (${result.status}) → ${fixer.target}`);
+        const ok = await confirmApply(fixer, result, assumeYes);
+        if (!ok) {
+            console.log(chalk.gray('    skipped'));
+            skipped++;
+            continue;
+        }
+        await applyFixer(fixer, result, targetDir, pkg, dryRun);
+        applied++;
+    }
+    console.log();
+    console.log(`  Summary: ${chalk.green(`${applied} applied`)}, ${chalk.gray(`${skipped} skipped`)}, ${chalk.yellow(`${unsupported} unsupported`)}\n`);
+}

package/dist/cli/commands/setup.js

@@ -148,6 +148,12 @@ async function promptForConfig() {
             default: (answers) => answers.projectType === 'library',
             when: (answers) => answers.projectType === 'library',
         },
+        {
+            type: 'confirm',
+            name: 'securityAutomation',
+            message: '🛡️  Include security automation (Dependabot + CodeQL)?',
+            default: true,
+        },
         {
             type: 'list',
             name: 'bundler',
@@ -191,6 +197,7 @@ async function promptForConfig() {
         gitHooks: answers.gitHooks || false,
         commitLint: answers.commitLint || false,
         semanticRelease: answers.semanticRelease || false,
+        securityAutomation: answers.securityAutomation ?? false,
         bundler: answers.bundler || 'none',
     };
 }

package/dist/cli/generators/build.js

@@ -82,7 +82,7 @@ export default defineConfig({
 `;
     await fs.writeFile(viteConfigPath, viteConfig);
 }
-async function generateSemanticReleaseConfig(targetDir) {
+export async function generateSemanticReleaseConfig(targetDir) {
     const releaseConfigPath = path.join(targetDir, 'release.config.mjs');
     const releaseConfig = `export { default } from '@rtorcato/js-tooling/semantic-release/github'
 `;

package/dist/cli/generators/git.js

@@ -10,7 +10,7 @@ export async function generateGitConfigs(config, targetDir) {
     // Generate .gitignore
     await generateGitignore(config, targetDir);
 }
-async function generateHuskyConfig(config, targetDir) {
+export async function generateHuskyConfig(config, targetDir) {
     const huskyDir = path.join(targetDir, '.husky');
     await fs.ensureDir(huskyDir);
     // Pre-commit hook
@@ -52,7 +52,7 @@ npx --no -- commitlint --edit $1
     };
     await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
 }
-async function generateCommitlintConfig(targetDir) {
+export async function generateCommitlintConfig(targetDir) {
     const commitlintConfigPath = path.join(targetDir, 'commitlint.config.mjs');
     const commitlintConfig = `export { default } from '@rtorcato/js-tooling/commitlint/config'
 `;

package/dist/cli/generators/index.js

@@ -5,15 +5,20 @@ import { generateBuildConfigs } from './build.js';
 import { generateGitConfigs } from './git.js';
 import { generateGitHubActions } from './github-actions.js';
 import { generateLintingConfigs } from './linting.js';
+import { generateMiscBaseline } from './misc.js';
 import { generatePackageJson } from './package-json.js';
 import { generateReadme } from './readme.js';
+import { generateSecurityConfigs } from './security.js';
 import { generateTestingConfigs } from './testing.js';
 import { generateTSConfig } from './tsconfig.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 export async function generateConfigs(config, targetDir) {
-    // Generate package.json
+    // Generate package.json (must run before generateMiscBaseline,
+    // which sets engines.node on the resulting file)
     await generatePackageJson(config, targetDir);
+    // Universal baseline: .editorconfig, .nvmrc, engines.node, knip.json
+    await generateMiscBaseline(targetDir);
     // Generate TypeScript configuration
     if (config.typescript.enabled) {
         await generateTSConfig(config, targetDir);
@@ -32,6 +37,10 @@ export async function generateConfigs(config, targetDir) {
     }
     // Generate GitHub Actions workflow
     await generateGitHubActions(config, targetDir);
+    // Generate security automation (Dependabot + CodeQL)
+    if (config.securityAutomation) {
+        await generateSecurityConfigs(targetDir);
+    }
     // Generate build configurations
     if (config.bundler !== 'none') {
         await generateBuildConfigs(config, targetDir);

package/dist/cli/generators/linting.js

@@ -14,7 +14,7 @@ export async function generateLintingConfigs(config, targetDir) {
         await generatePrettierConfig(targetDir);
     }
 }
-async function generateBiomeConfig(targetDir) {
+export async function generateBiomeConfig(targetDir) {
     const biomeConfigPath = path.join(targetDir, 'biome.jsonc');
     const biomeConfig = {
         $schema: 'https://biomejs.dev/schemas/1.9.4/schema.json',
@@ -26,7 +26,7 @@ async function generateBiomeConfig(targetDir) {
     };
     await fs.writeJson(biomeConfigPath, biomeConfig, { spaces: 2 });
 }
-async function generateESLintConfig(config, targetDir) {
+export async function generateESLintConfig(config, targetDir) {
     const eslintConfigPath = path.join(targetDir, 'eslint.config.mjs');
     const configType = config.linting.eslintConfig || 'base';
     const eslintConfig = `import { default as config } from '@rtorcato/js-tooling/eslint/${configType}'
@@ -35,7 +35,7 @@ export default config
 `;
     await fs.writeFile(eslintConfigPath, eslintConfig);
 }
-async function generatePrettierConfig(targetDir) {
+export async function generatePrettierConfig(targetDir) {
     const prettierConfigPath = path.join(targetDir, 'prettier.config.mjs');
     const prettierConfig = `export { default } from '@rtorcato/js-tooling/prettier'
 `;

package/dist/cli/generators/misc.js

@@ -0,0 +1,52 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+const EDITORCONFIG_CONTENT = `root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = tab
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{json,yml,yaml}]
+indent_style = space
+indent_size = 2
+`;
+const NVMRC_CONTENT = '22\n';
+const KNIP_CONFIG = {
+    $schema: 'https://unpkg.com/knip@5/schema.json',
+    entry: ['src/index.ts'],
+    project: ['src/**/*.ts'],
+};
+export async function generateEditorConfig(targetDir) {
+    await fs.writeFile(path.join(targetDir, '.editorconfig'), EDITORCONFIG_CONTENT);
+}
+export async function generateNvmrc(targetDir) {
+    await fs.writeFile(path.join(targetDir, '.nvmrc'), NVMRC_CONTENT);
+}
+export async function ensureEnginesNode(targetDir, version = '>=22') {
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (!(await fs.pathExists(pkgPath)))
+        return 'no-package-json';
+    const pkg = (await fs.readJson(pkgPath));
+    const engines = pkg.engines ?? {};
+    if (engines.node)
+        return 'already-set';
+    pkg.engines = { ...engines, node: version };
+    await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+    return 'added';
+}
+export async function generateKnipConfig(targetDir) {
+    await fs.writeJson(path.join(targetDir, 'knip.json'), KNIP_CONFIG, { spaces: 2 });
+}
+export async function generateMiscBaseline(targetDir) {
+    await generateEditorConfig(targetDir);
+    await generateNvmrc(targetDir);
+    await ensureEnginesNode(targetDir);
+    await generateKnipConfig(targetDir);
+}

package/dist/cli/generators/security.js

@@ -0,0 +1,73 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+export async function generateDependabotConfig(targetDir) {
+    await fs.ensureDir(path.join(targetDir, '.github'));
+    const filepath = path.join(targetDir, '.github', 'dependabot.yml');
+    const content = `version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    versioning-strategy: "increase"
+    commit-message:
+      prefix: "chore(deps)"
+      include: "scope"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(ci)"
+`;
+    await fs.writeFile(filepath, content);
+}
+export async function generateCodeQLWorkflow(targetDir) {
+    await fs.ensureDir(path.join(targetDir, '.github', 'workflows'));
+    const filepath = path.join(targetDir, '.github', 'workflows', 'codeql.yml');
+    const content = `name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 6 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [javascript-typescript]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: \${{ matrix.language }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:\${{ matrix.language }}"
+`;
+    await fs.writeFile(filepath, content);
+}
+export async function generateSecurityConfigs(targetDir) {
+    await generateDependabotConfig(targetDir);
+    await generateCodeQLWorkflow(targetDir);
+}

package/dist/cli/generators/testing.js

@@ -11,7 +11,7 @@ export async function generateTestingConfigs(config, targetDir) {
         await generatePlaywrightConfig(targetDir);
     }
 }
-async function generateVitestConfig(config, targetDir) {
+export async function generateVitestConfig(config, targetDir) {
     const vitestConfigPath = path.join(targetDir, 'vitest.config.ts');
     const vitestConfig = `import { defineConfig } from 'vitest/config'
 

package/dist/cli/index.js

@@ -5,7 +5,9 @@ import { Command } from 'commander';
 import fs from 'fs-extra';
 import packageJson from '../../package.json' with { type: 'json' };
 import { doctorCommand } from './commands/doctor.js';
+import { fixCommand } from './commands/fix.js';
 import { setupProject } from './commands/setup.js';
+import { copyPreset, PRESETS } from './utils/copy-preset.js';
 async function isSelfRepo(dir) {
     try {
         const pkg = await fs.readJson(path.join(dir, 'package.json'));
@@ -31,40 +33,20 @@ program
     .command('copy <config>')
     .description('📋 Copy a specific configuration file to current directory')
     .action(async (config) => {
-    const availableConfigs = {
-        biome: {
-            source: 'tooling/biome/biome.json',
-            target: 'biome.json',
-            desc: 'Biome formatter and linter configuration',
-        },
-        tsconfig: {
-            source: 'tooling/typescript/tsconfig.base.json',
-            target: 'tsconfig.json',
-            desc: 'TypeScript base configuration',
-        },
-    };
-    if (!availableConfigs[config]) {
+    if (!(config in PRESETS)) {
         console.error(chalk.red(`\n❌ Unknown configuration: ${config}`));
         console.log(chalk.gray('Available configurations:'));
-        Object.entries(availableConfigs).forEach(([key, { desc }]) => {
+        for (const [key, { desc }] of Object.entries(PRESETS)) {
             console.log(`  ${chalk.green('●')} ${chalk.bold(key)}: ${chalk.gray(desc)}`);
-        });
+        }
         console.log();
         process.exit(1);
     }
-    const { source, target, desc } = availableConfigs[config];
     try {
-        const fs = (await import('fs-extra')).default;
-        const path = (await import('node:path')).default;
-        // Get the package installation path - CLI is in dist/cli/index.js, need to go up 3 levels
-        const cliFile = new URL(import.meta.url).pathname;
-        const packagePath = path.dirname(path.dirname(path.dirname(cliFile)));
-        const sourcePath = path.join(packagePath, source);
-        const targetPath = path.join(process.cwd(), target);
-        await fs.copy(sourcePath, targetPath);
-        console.log(chalk.green(`\n✅ Copied ${desc}`));
-        console.log(chalk.gray(`   From: ${source}`));
-        console.log(chalk.gray(`   To:   ${target}\n`));
+        const result = await copyPreset(config);
+        console.log(chalk.green(`\n✅ Copied ${result.desc}`));
+        console.log(chalk.gray(`   From: ${result.source}`));
+        console.log(chalk.gray(`   To:   ${result.target}\n`));
     }
     catch (error) {
         console.error(chalk.red(`\n❌ Error copying configuration: ${error}\n`));
@@ -107,9 +89,20 @@ program
     .option('-d, --directory <path>', 'Target directory to diagnose', process.cwd())
     .option('--json', 'Emit machine-readable JSON output')
     .action(doctorCommand);
+program
+    .command('fix [target]')
+    .description('🔧 Apply scaffolders for items doctor flagged')
+    .option('-d, --directory <path>', 'Target directory', process.cwd())
+    .option('--yes', 'Assume yes to all prompts (including drift overwrites)')
+    .option('--dry-run', 'Print what would change without writing files')
+    .action((target, options) => fixCommand(target, {
+    directory: options.directory,
+    yes: options.yes,
+    dryRun: options.dryRun,
+}));
 program.hook('preAction', async (_, actionCommand) => {
     const name = actionCommand.name();
-    if (name === 'setup' || name === 'doctor') {
+    if (name === 'setup' || name === 'doctor' || name === 'fix') {
         const dir = actionCommand.opts().directory ?? process.cwd();
         if (await isSelfRepo(dir)) {
             console.log(chalk.yellow('\n⚠️  This command cannot be run inside the @rtorcato/js-tooling repo itself.\n'));

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

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+export const PRESETS = {
+    biome: {
+        source: 'tooling/biome/biome.json',
+        target: 'biome.json',
+        desc: 'Biome formatter and linter configuration',
+    },
+    tsconfig: {
+        source: 'tooling/typescript/tsconfig.base.json',
+        target: 'tsconfig.json',
+        desc: 'TypeScript base configuration',
+    },
+};
+export function getPackageRoot() {
+    const cliFile = new URL(import.meta.url).pathname;
+    return path.dirname(path.dirname(path.dirname(path.dirname(cliFile))));
+}
+export async function copyPreset(name, targetDir = process.cwd()) {
+    const preset = PRESETS[name];
+    const packageRoot = getPackageRoot();
+    const sourcePath = path.join(packageRoot, preset.source);
+    const targetPath = path.join(targetDir, preset.target);
+    await fs.copy(sourcePath, targetPath);
+    return {
+        source: preset.source,
+        target: preset.target,
+        targetPath,
+        desc: preset.desc,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/js-tooling",
-	"version": "2.2.0",
+	"version": "2.4.0",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [