@rtorcato/repo-tooling 2.59.0

package/dist/cli/generators/index.js

@@ -0,0 +1,123 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { generateSwiftProject } from '../../languages/swift/scaffold.js';
+import { installAiSetup } from './agent-rules.js';
+import { bundlerNeedsEsbuild, ensureBuildApprovals, generateBuildConfigs } from './build.js';
+import { ensurePnpmSettings } from './pnpm-workspace.js';
+import { generateGitConfigs } from './git.js';
+import { generateGitHubActions } from './github-actions.js';
+import { generateLintingConfigs } from './linting.js';
+import { generateKnipConfig, generateMiscBaseline, generateVscodeExtensions } 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 { generateTreeshakeCheck, inferSubpathsFromExports } from './treeshake.js';
+import { generateTSConfig } from './tsconfig.js';
+import { generateTailwind } from './tailwind.js';
+import { generateTurborepo } from './turborepo.js';
+import { generateNx } from './nx.js';
+import { generateBun } from './bun.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export async function generateConfigs(config, targetDir) {
+    // Swift takes its own path (#288) rather than opting out of each step below.
+    // Everything from here down is rooted in package.json — the file a Swift repo
+    // is defined by not having.
+    if (config.language === 'swift') {
+        return generateSwiftProject(config, targetDir);
+    }
+    // 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);
+    // Recommend the editor extensions matching the enabled tools
+    await generateVscodeExtensions(config, targetDir);
+    // Generate TypeScript configuration
+    if (config.typescript.enabled) {
+        await generateTSConfig(config, targetDir);
+    }
+    // Generate linting configurations
+    if (config.linting.tool !== 'none') {
+        await generateLintingConfigs(config, targetDir);
+    }
+    // Generate testing configurations
+    if (config.testing.framework !== 'none') {
+        await generateTestingConfigs(config, targetDir);
+    }
+    // Generate git configurations
+    if (config.gitHooks || config.commitLint) {
+        await generateGitConfigs(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);
+    }
+    // Tree-shake verification check (libraries only, when opted-in)
+    if (config.treeshakeCheck && config.projectType === 'library') {
+        const pkgPath = path.join(targetDir, 'package.json');
+        const pkg = (await fs.readJson(pkgPath));
+        const { allCandidates, defaultAllowed } = inferSubpathsFromExports(pkg);
+        if (defaultAllowed && allCandidates.length >= 2) {
+            await generateTreeshakeCheck(targetDir, {
+                workspaceName: config.projectName,
+                allowedSubpath: defaultAllowed,
+                forbiddenSubpaths: allCandidates.filter((s) => s !== defaultAllowed),
+            });
+            // treeshake-check writes pnpm-workspace.yaml; regenerate knip so it
+            // picks up the workspaces form (the baseline pass above ran before the
+            // workspace file existed and emitted the flat single-package form).
+            await generateKnipConfig(targetDir);
+        }
+    }
+    // Approve esbuild's build script for pnpm 11 via pnpm-workspace.yaml. Runs
+    // after the treeshake-check path so its richer workspace file (if written)
+    // is never clobbered.
+    await ensureBuildApprovals(config, targetDir);
+    // Family-wide pnpm settings (#314). Runs last of the workspace writers so it
+    // merges into whatever they wrote rather than racing them for the file.
+    await ensurePnpmSettings(targetDir, bundlerNeedsEsbuild(config));
+    // Turborepo task pipeline (pnpm-workspace monorepos, when opted-in)
+    if (config.turborepo) {
+        await generateTurborepo(targetDir);
+    }
+    // Nx task orchestrator (alternative to Turborepo, when opted-in)
+    if (config.nx) {
+        await generateNx(targetDir);
+    }
+    // Tailwind CSS v4 (frontend projects, when opted-in)
+    if (config.tailwind) {
+        await generateTailwind(targetDir);
+    }
+    // Bun runtime (#225): bunfig.toml (the Bun-typed tsconfig is already emitted
+    // by generateTSConfig above when config.bun, so generateBun only adds bunfig).
+    if (config.bun) {
+        await generateBun(targetDir);
+    }
+    // AI agent files (AGENTS.md, CLAUDE.md, Cursor/Copilot, Claude skill, MCP example)
+    if (config.aiSetup) {
+        await installAiSetup(targetDir);
+    }
+    // Generate README
+    await generateReadme(config, targetDir);
+    // Copy ts-reset if TypeScript is enabled
+    if (config.typescript.enabled) {
+        await copyTSReset(targetDir);
+    }
+}
+async function copyTSReset(targetDir) {
+    const toolingRoot = path.resolve(__dirname, '../../../tooling');
+    const resetPath = path.join(toolingRoot, 'typescript', 'reset.d.ts');
+    const targetPath = path.join(targetDir, 'reset.d.ts');
+    if (await fs.pathExists(resetPath)) {
+        await fs.copy(resetPath, targetPath);
+    }
+}

package/dist/cli/generators/linting.js

@@ -0,0 +1,54 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+export async function generateLintingConfigs(config, targetDir) {
+    // Generate Biome config
+    if (config.linting.tool === 'biome' || config.linting.tool === 'both') {
+        await generateBiomeConfig(targetDir);
+    }
+    // Generate ESLint config
+    if (config.linting.tool === 'eslint' || config.linting.tool === 'both') {
+        await generateESLintConfig(config, targetDir);
+    }
+    // Generate Prettier config if using ESLint
+    if (config.linting.tool === 'eslint') {
+        await generatePrettierConfig(targetDir);
+    }
+    // Generate Oxlint config (additive — runs alongside Biome/ESLint)
+    if (config.oxlint) {
+        await generateOxlintConfig(targetDir);
+    }
+}
+export async function generateOxlintConfig(targetDir) {
+    // Oxlint's `extends` resolution from npm packages isn't reliably supported,
+    // so we copy the full preset rather than write a thin pointer file (same
+    // pattern as biome.jsonc — the user owns the file once it's in their repo).
+    const { copyPreset } = await import('../utils/copy-preset.js');
+    await copyPreset('oxlint', targetDir);
+}
+export async function generateBiomeConfig(targetDir) {
+    const biomeConfigPath = path.join(targetDir, 'biome.jsonc');
+    // Biome 2.x schema + shape. The base preset (extends) already defines the
+    // file globs via `files.includes`; emitting the old 1.x `include`/`ignore`
+    // keys here forced consumers to run `biome migrate` before `biome check`
+    // would run at all.
+    const biomeConfig = {
+        $schema: 'https://biomejs.dev/schemas/2.5.0/schema.json',
+        extends: ['@rtorcato/repo-tooling/biome'],
+    };
+    await fs.writeJson(biomeConfigPath, biomeConfig, { spaces: 2 });
+}
+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/repo-tooling/eslint/${configType}'
+
+export default config
+`;
+    await fs.writeFile(eslintConfigPath, eslintConfig);
+}
+export async function generatePrettierConfig(targetDir) {
+    const prettierConfigPath = path.join(targetDir, 'prettier.config.mjs');
+    const prettierConfig = `export { default } from '@rtorcato/repo-tooling/prettier'
+`;
+    await fs.writeFile(prettierConfigPath, prettierConfig);
+}

package/dist/cli/generators/misc.js

@@ -0,0 +1,298 @@
+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 SIZE_LIMIT_CONFIG = [
+    {
+        name: 'package (default entry)',
+        path: 'dist/index.js',
+        limit: '10 kB',
+    },
+];
+// Exports-driven size-limit config for multi-subpath libraries: one budget per
+// exported subpath, computed from package.json at run time so newly added
+// modules are covered automatically. The static-array form silently drifts as
+// modules ship without a budget (#165). The root '.' barrel is skipped — it
+// re-exports everything and grows legitimately. Tighten individual modules via
+// OVERRIDES.
+const SIZE_LIMIT_CJS = `const pkg = require('./package.json')
+
+// Per-subpath budget overrides, e.g. { './clipboard': '500 B' }.
+const OVERRIDES = {}
+const DEFAULT_LIMIT = '10 kB'
+
+// Resolve the ESM entry file for an exports condition (string, or an object
+// with a string \`import\`, or a nested \`import.default\`).
+function importPath(cond) {
+  if (typeof cond === 'string') return cond
+  if (cond && typeof cond === 'object') {
+    if (typeof cond.import === 'string') return cond.import
+    if (cond.import && typeof cond.import === 'object') return cond.import.default
+  }
+  return undefined
+}
+
+module.exports = Object.entries(pkg.exports || {})
+  .filter(([sub]) => sub !== '.' && sub !== './package.json')
+  .map(([sub, cond]) => [sub, importPath(cond)])
+  .filter(([, file]) => typeof file === 'string')
+  .map(([sub, file]) => ({
+    name: \`\${pkg.name}\${sub.slice(1)}\`,
+    path: file.replace(/^\\.\\//, ''),
+    limit: OVERRIDES[sub] || DEFAULT_LIMIT,
+  }))
+`;
+const CODEOWNERS_CONTENT = `# .github/CODEOWNERS
+# Each line is a file pattern followed by one or more owners.
+# Owners can be GitHub usernames (@user) or team names (@org/team).
+# Order matters — the last matching pattern wins.
+# See https://docs.github.com/articles/about-code-owners/
+#
+# Examples:
+#   *              @your-username
+#   /src/api/      @backend-team
+#   /docs/         @docs-team @your-username
+#   *.md           @docs-team
+
+* @TODO-owner
+`;
+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);
+}
+/**
+ * The VS Code extension IDs recommended for the tools this config enables.
+ * EditorConfig is always included — the baseline always writes .editorconfig.
+ */
+export function recommendedExtensions(config) {
+    const ids = new Set(['EditorConfig.EditorConfig']);
+    const lint = config.linting.tool;
+    if (lint === 'biome' || lint === 'both' || config.formatting.tool === 'biome') {
+        ids.add('biomejs.biome');
+    }
+    if (lint === 'eslint' || lint === 'both')
+        ids.add('dbaeumer.vscode-eslint');
+    if (config.formatting.tool === 'prettier')
+        ids.add('esbenp.prettier-vscode');
+    if (config.oxlint)
+        ids.add('oxc.oxc-vscode');
+    if (config.testing.framework === 'vitest')
+        ids.add('vitest.explorer');
+    if (config.testing.framework === 'playwright')
+        ids.add('ms-playwright.playwright');
+    return [...ids];
+}
+/**
+ * Emit .vscode/extensions.json recommending the editor extensions that match the
+ * enabled tools. Merge-friendly: preserves any recommendations already present
+ * and never clobbers a hand-authored file it can't parse as JSON (e.g. JSONC
+ * with comments) — returns null in that case. Returns the written path otherwise.
+ */
+export async function generateVscodeExtensions(config, targetDir) {
+    const filepath = path.join(targetDir, '.vscode', 'extensions.json');
+    let existing = [];
+    if (await fs.pathExists(filepath)) {
+        try {
+            const current = (await fs.readJson(filepath));
+            if (Array.isArray(current.recommendations)) {
+                existing = current.recommendations.filter((r) => typeof r === 'string');
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    const merged = [...new Set([...existing, ...recommendedExtensions(config)])];
+    await fs.ensureDir(path.dirname(filepath));
+    await fs.writeJson(filepath, { recommendations: merged }, { spaces: 2 });
+    return '.vscode/extensions.json';
+}
+const DEFAULT_NODE_MAJOR = 22;
+/**
+ * Resolve the authoritative Node major: an existing .nvmrc/.node-version wins,
+ * else the `engines.node` floor, else the default. Used to seed .nvmrc when a
+ * repo has no pin yet before pointing workflows at it.
+ */
+async function resolveNodeMajor(targetDir) {
+    for (const candidate of ['.nvmrc', '.node-version']) {
+        const p = path.join(targetDir, candidate);
+        if (await fs.pathExists(p)) {
+            const m = (await fs.readFile(p, 'utf-8')).trim().match(/\d+/);
+            if (m)
+                return Number.parseInt(m[0], 10);
+        }
+    }
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (await fs.pathExists(pkgPath)) {
+        const pkg = (await fs.readJson(pkgPath));
+        const node = pkg.engines?.node;
+        const m = node?.match(/\d+/);
+        if (m)
+            return Number.parseInt(m[0], 10);
+    }
+    return DEFAULT_NODE_MAJOR;
+}
+// A hardcoded scalar `node-version: <major>` line (leading digit after an
+// optional quote). Deliberately does NOT match matrix arrays (`[22, 24]`),
+// `${{ }}` expressions, or bare `node-version:` input keys — those are left as-is.
+const NODE_VERSION_LINE = /^([ \t]*)node-version:[ \t]*['"]?\d[\w.-]*['"]?[ \t]*$/gm;
+/**
+ * Make .nvmrc the single Node source of truth: ensure it exists (pinned to the
+ * resolved major) and rewrite hardcoded scalar `node-version:` lines in CI
+ * workflows to `node-version-file: .nvmrc`. Returns the files changed.
+ */
+export async function alignNodeVersion(targetDir) {
+    const written = [];
+    const nvmrcPath = path.join(targetDir, '.nvmrc');
+    if (!(await fs.pathExists(nvmrcPath))) {
+        const major = await resolveNodeMajor(targetDir);
+        await fs.writeFile(nvmrcPath, `${major}\n`);
+        written.push('.nvmrc');
+    }
+    const workflowsDir = path.join(targetDir, '.github', 'workflows');
+    if (await fs.pathExists(workflowsDir)) {
+        const files = (await fs.readdir(workflowsDir)).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        for (const file of files) {
+            const p = path.join(workflowsDir, file);
+            const contents = await fs.readFile(p, 'utf-8');
+            const next = contents.replace(NODE_VERSION_LINE, '$1node-version-file: .nvmrc');
+            if (next !== contents) {
+                await fs.writeFile(p, next);
+                written.push(`.github/workflows/${file}`);
+            }
+        }
+    }
+    return written;
+}
+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';
+}
+/**
+ * Build a knip config whose `entry` matches the project's build model, read
+ * from package.json `exports`:
+ *   - >1 public subpath export  → per-file/multi-entry lib (e.g. react-common,
+ *     whose build makes every src module its own entry). Every file is a public
+ *     entry, so `entry` covers all of src — flagging none as "unused files"
+ *     while still catching unused exports and dependencies.
+ *   - single root barrel / no exports → narrow `src/index` entry so knip can
+ *     trace and flag genuinely unreachable modules.
+ * `.tsx` is included so React libraries aren't silently skipped.
+ */
+/**
+ * Extract package globs from a pnpm-workspace.yaml `packages:` list without a
+ * YAML dependency. Matches `- 'apps/*'` / `- "apps/*"` / `- apps/*` entries
+ * under the `packages:` key, stopping at the next top-level key.
+ */
+function parseWorkspacePackages(yaml) {
+    const globs = [];
+    let inPackages = false;
+    for (const line of yaml.split('\n')) {
+        if (/^packages:\s*$/.test(line)) {
+            inPackages = true;
+            continue;
+        }
+        if (!inPackages)
+            continue;
+        const item = line.match(/^\s*-\s*['"]?([^'"#]+?)['"]?\s*$/);
+        if (item?.[1]) {
+            globs.push(item[1].trim());
+            continue;
+        }
+        if (/^\S/.test(line))
+            break; // a new top-level key ends the list
+    }
+    return globs;
+}
+export async function buildKnipConfig(targetDir) {
+    const pkgPath = path.join(targetDir, 'package.json');
+    let multiEntry = false;
+    if (await fs.pathExists(pkgPath)) {
+        const pkg = (await fs.readJson(pkgPath));
+        if (pkg.exports && typeof pkg.exports === 'object') {
+            const subpaths = Object.keys(pkg.exports).filter((k) => k.startsWith('.') && k !== './package.json');
+            multiEntry = subpaths.length > 1;
+        }
+    }
+    const $schema = 'https://unpkg.com/knip@6/schema.json';
+    const entry = multiEntry ? ['src/**/*.{ts,tsx}'] : ['src/index.{ts,tsx}'];
+    const project = ['src/**/*.{ts,tsx}'];
+    // In a pnpm workspace, the flat entry/project form makes `knip` mis-analyze
+    // the sub-packages (it treats the whole repo as one package). Emit the
+    // `workspaces` form instead: the root keeps the build-model globs, and each
+    // declared package glob gets `{}` so knip auto-detects its entries.
+    const wsPath = path.join(targetDir, 'pnpm-workspace.yaml');
+    if (await fs.pathExists(wsPath)) {
+        const workspaces = { '.': { entry, project } };
+        for (const glob of parseWorkspacePackages(await fs.readFile(wsPath, 'utf-8'))) {
+            workspaces[glob] = {};
+        }
+        return { $schema, workspaces };
+    }
+    return { $schema, entry, project };
+}
+export async function generateKnipConfig(targetDir) {
+    const config = await buildKnipConfig(targetDir);
+    await fs.writeJson(path.join(targetDir, 'knip.json'), config, { spaces: 2 });
+}
+/**
+ * Scaffold a size-limit budget. Multi-subpath libraries (≥1 subpath export
+ * beyond the root barrel) get an exports-driven `.size-limit.cjs` that emits one
+ * budget per subpath from package.json at run time — so new modules are covered
+ * automatically. Everything else gets a static `.size-limit.json` for the root
+ * bundle. Returns the written filename.
+ */
+export async function generateSizeLimitConfig(targetDir) {
+    const pkgPath = path.join(targetDir, 'package.json');
+    let subpathCount = 0;
+    if (await fs.pathExists(pkgPath)) {
+        const pkg = (await fs.readJson(pkgPath));
+        if (pkg.exports && typeof pkg.exports === 'object') {
+            subpathCount = Object.keys(pkg.exports).filter((k) => k.startsWith('./') && k !== './package.json').length;
+        }
+    }
+    if (subpathCount >= 1) {
+        await fs.writeFile(path.join(targetDir, '.size-limit.cjs'), SIZE_LIMIT_CJS);
+        return '.size-limit.cjs';
+    }
+    await fs.writeJson(path.join(targetDir, '.size-limit.json'), SIZE_LIMIT_CONFIG, { spaces: 2 });
+    return '.size-limit.json';
+}
+export async function generateCodeowners(targetDir) {
+    const filepath = path.join(targetDir, '.github', 'CODEOWNERS');
+    await fs.ensureDir(path.dirname(filepath));
+    await fs.writeFile(filepath, CODEOWNERS_CONTENT);
+    return '.github/CODEOWNERS';
+}
+export async function generateMiscBaseline(targetDir) {
+    await generateEditorConfig(targetDir);
+    await generateNvmrc(targetDir);
+    await ensureEnginesNode(targetDir);
+    await generateKnipConfig(targetDir);
+}

package/dist/cli/generators/nx.js

@@ -0,0 +1,16 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * Scaffold a starter nx.json for a pnpm-workspace monorepo (the Turborepo
+ * alternative). Copies the shipped preset — a minimal `targetDefaults` pipeline;
+ * plugin generators are deferred. Never clobbers a hand-tuned nx.json (there is
+ * no doctor "ok" short-circuit for the targeted `fix nx` path). Returns the
+ * relative path written, or [] when nx.json already exists.
+ */
+export async function generateNx(targetDir) {
+    if (await fs.pathExists(path.join(targetDir, 'nx.json')))
+        return [];
+    const { copyPreset } = await import('../utils/copy-preset.js');
+    const result = await copyPreset('nx', targetDir);
+    return [result.target];
+}