@rtorcato/repo-tooling 2.59.0

package/dist/cli/generators/package-json.js

@@ -0,0 +1,317 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+// Exact pnpm version for the `packageManager` field — corepack requires a
+// pinned `pnpm@x.y.z` (not a range), and it's the single source of truth for
+// pnpm/action-setup, so the generated workflows drop their `version:` inputs.
+const PNPM_VERSION = '11.1.3';
+export async function generatePackageJson(config, targetDir) {
+    const packageJsonPath = path.join(targetDir, 'package.json');
+    let existingPackageJson = {};
+    if (await fs.pathExists(packageJsonPath)) {
+        existingPackageJson = await fs.readJson(packageJsonPath);
+    }
+    const includeTreeshake = Boolean(config.treeshakeCheck && config.projectType === 'library');
+    const packageJson = {
+        name: config.projectName,
+        version: '0.1.0',
+        description: '',
+        type: 'module',
+        packageManager: `pnpm@${PNPM_VERSION}`,
+        ...existingPackageJson,
+        scripts: {
+            ...getScripts(config, { includeTreeshake }),
+            ...existingPackageJson?.scripts,
+        },
+        dependencies: {
+            ...existingPackageJson?.dependencies,
+        },
+        devDependencies: {
+            '@rtorcato/repo-tooling': 'latest',
+            ...getDependencies(config),
+            ...existingPackageJson?.devDependencies,
+        },
+    };
+    // Add additional package.json fields based on project type.
+    // Exports must match tsup's output for a "type": "module" package with
+    // format: ['cjs','esm']: ESM → index.js, CJS → index.cjs, types →
+    // index.d.ts (ESM) / index.d.cts (CJS).
+    if (config.projectType === 'library') {
+        packageJson.main = './dist/index.cjs';
+        packageJson.module = './dist/index.js';
+        packageJson.types = './dist/index.d.ts';
+        packageJson.exports = {
+            '.': {
+                types: {
+                    import: './dist/index.d.ts',
+                    require: './dist/index.d.cts',
+                },
+                import: './dist/index.js',
+                require: './dist/index.cjs',
+            },
+        };
+        packageJson.files = ['dist'];
+        packageJson.publishConfig = {
+            access: 'public',
+        };
+    }
+    // Commitizen adapter path — makes `pnpm commit` launch the conventional
+    // changelog prompt. Merged so an existing `config` block is preserved.
+    if (config.commitLint) {
+        packageJson.config = {
+            ...(packageJson.config ?? {}),
+            commitizen: { path: './node_modules/cz-conventional-changelog' },
+        };
+    }
+    // Build-script approvals (esbuild etc.) are NOT written here: pnpm 11 ignores
+    // package.json's `pnpm` field and reads them from pnpm-workspace.yaml instead
+    // (see ensureBuildApprovals in build.ts).
+    await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
+}
+function getScripts(config, opts = {}) {
+    const scripts = {};
+    // TypeScript scripts
+    if (config.typescript.enabled) {
+        scripts['typecheck'] = 'tsc --noEmit';
+    }
+    // Linting scripts
+    if (config.linting.tool === 'biome' || config.linting.tool === 'both') {
+        scripts['lint'] = 'biome lint .';
+        scripts['format'] = 'biome format .';
+        scripts['check'] = 'biome check .';
+        scripts['check:fix'] = 'biome check --fix .';
+    }
+    else if (config.linting.tool === 'eslint') {
+        scripts['lint'] = 'eslint .';
+        scripts['lint:fix'] = 'eslint . --fix';
+        scripts['format'] = 'prettier --write .';
+    }
+    // Testing scripts
+    if (config.testing.framework === 'vitest') {
+        scripts['test'] = 'vitest';
+        scripts['test:watch'] = 'vitest --watch';
+        scripts['test:ui'] = 'vitest --ui';
+        scripts['coverage'] = 'vitest run --coverage';
+    }
+    else if (config.testing.framework === 'jest') {
+        scripts['test'] = 'jest';
+        scripts['test:watch'] = 'jest --watch';
+        scripts['coverage'] = 'jest --coverage';
+    }
+    else if (config.testing.framework === 'playwright') {
+        scripts['test:e2e'] = 'playwright test';
+        scripts['test:e2e:ui'] = 'playwright test --ui';
+    }
+    else if (config.testing.framework === 'cypress') {
+        scripts['test:e2e'] = 'cypress run';
+        scripts['test:e2e:ui'] = 'cypress open';
+    }
+    // Build scripts
+    if (config.bundler === 'tsup') {
+        scripts['build'] = 'tsup';
+        scripts['build:watch'] = 'tsup --watch';
+    }
+    else if (config.bundler === 'esbuild') {
+        scripts['build'] = 'node build.mjs';
+    }
+    else if (config.bundler === 'rollup') {
+        scripts['build'] = 'rollup -c';
+        scripts['build:watch'] = 'rollup -c --watch';
+    }
+    else if (config.bundler === 'rolldown') {
+        scripts['build'] = 'rolldown -c';
+        scripts['build:watch'] = 'rolldown -c --watch';
+    }
+    else if (config.bundler === 'vite') {
+        scripts['build'] = 'vite build';
+        scripts['dev'] = 'vite';
+        scripts['preview'] = 'vite preview';
+    }
+    // Commitizen assistant — `pnpm commit` guides a conventional commit that
+    // then passes the commitlint enforcement layer.
+    if (config.commitLint) {
+        scripts['commit'] = 'cz';
+    }
+    // knip is part of the universal baseline (knip.json is always generated).
+    scripts['knip'] = 'knip';
+    // publint validates the published package (exports, types, main) against dist.
+    if (config.publint) {
+        scripts['publint'] = 'publint --strict';
+    }
+    // are-the-types-wrong validates that a consumer's `import` actually resolves
+    // the shipped `.d.ts`. Only meaningful for publishable libraries. The default
+    // profile fits the dual (cjs+esm) exports the library scaffold emits.
+    if (config.projectType === 'library') {
+        scripts['attw'] = 'attw --pack';
+    }
+    // Git hooks
+    if (config.gitHooks) {
+        scripts['prepare'] = 'husky';
+    }
+    // Semantic release
+    if (config.semanticRelease) {
+        scripts['release'] = 'semantic-release';
+    }
+    if (opts.includeTreeshake) {
+        scripts['pretreeshake'] = scripts['build'] ? 'pnpm build' : 'echo "no build step"';
+        scripts['treeshake'] = 'pnpm --filter=*treeshake-check run check';
+    }
+    const verify = composeVerifyScript(config, opts);
+    if (verify) {
+        scripts['verify'] = verify;
+    }
+    return scripts;
+}
+export function composeVerifyScript(config, opts = {}) {
+    const cmds = [];
+    if (config.typescript.enabled)
+        cmds.push('pnpm typecheck');
+    if (config.linting.tool === 'biome' || config.linting.tool === 'both') {
+        cmds.push('pnpm check');
+    }
+    else if (config.linting.tool === 'eslint') {
+        cmds.push('pnpm lint');
+    }
+    if (config.testing.framework === 'vitest') {
+        cmds.push('pnpm exec vitest run');
+    }
+    else if (config.testing.framework === 'jest') {
+        cmds.push('pnpm test --ci');
+    }
+    else if (config.testing.framework === 'playwright' || config.testing.framework === 'cypress') {
+        cmds.push('pnpm test:e2e');
+    }
+    if (opts.includeTreeshake)
+        cmds.push('pnpm treeshake');
+    if (config.publint)
+        cmds.push('pnpm publint');
+    // attw is a publish-safety rider, not a core check — it never justifies a
+    // verify chain on its own, so append it only once we've decided to emit one.
+    if (cmds.length < 2)
+        return null;
+    if (config.projectType === 'library')
+        cmds.push('pnpm attw');
+    return cmds.join(' && ');
+}
+/**
+ * Derive the verify chain from a real package.json's scripts + deps.
+ * Used by `fix verify`, where we shouldn't assume tools beyond what the
+ * project actually has.
+ */
+export function composeVerifyScriptFromPkg(pkg, opts = {}) {
+    const scripts = pkg.scripts ?? {};
+    const deps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+    };
+    const cmds = [];
+    if (scripts.typecheck || deps.typescript)
+        cmds.push('pnpm typecheck');
+    if (scripts.check)
+        cmds.push('pnpm check');
+    else if (scripts.lint && !scripts.check)
+        cmds.push('pnpm lint');
+    if (deps.vitest)
+        cmds.push('pnpm exec vitest run');
+    else if (deps.jest)
+        cmds.push('pnpm test --ci');
+    else if (deps['@playwright/test'] || deps.cypress)
+        cmds.push('pnpm test:e2e');
+    if (opts.includeTreeshake)
+        cmds.push('pnpm treeshake');
+    if (deps.publint || scripts.publint)
+        cmds.push('pnpm publint');
+    return cmds.length >= 2 ? cmds.join(' && ') : null;
+}
+function getDependencies(config) {
+    // knip is part of the universal baseline (knip.json + `knip` script).
+    const deps = { knip: '^6.0.0' };
+    // TypeScript
+    if (config.typescript.enabled) {
+        deps['typescript'] = '^5.9.3';
+        deps['@types/node'] = '^26.0.1';
+    }
+    // Linting tools
+    if (config.linting.tool === 'biome' || config.linting.tool === 'both') {
+        deps['@biomejs/biome'] = '^2.5.1';
+    }
+    if (config.linting.tool === 'eslint' || config.linting.tool === 'both') {
+        deps['eslint'] = '^9.0.0';
+        deps['prettier'] = '^3.0.0';
+    }
+    // Testing frameworks
+    if (config.testing.framework === 'vitest') {
+        deps['vitest'] = '^4.1.9';
+        // Coverage provider so `pnpm coverage` (and the CI Codecov upload) works.
+        deps['@vitest/coverage-v8'] = '^4.1.9';
+        if (config.testing.environment === 'browser' || config.testing.environment === 'both') {
+            deps['@vitest/ui'] = '^4.1.9';
+            deps['jsdom'] = '^25.0.0';
+        }
+    }
+    else if (config.testing.framework === 'jest') {
+        deps['jest'] = '^29.0.0';
+        if (config.typescript.enabled) {
+            deps['ts-jest'] = '^29.0.0';
+        }
+    }
+    else if (config.testing.framework === 'playwright') {
+        deps['@playwright/test'] = '^1.60.0';
+    }
+    else if (config.testing.framework === 'cypress') {
+        deps['cypress'] = '^13.0.0';
+    }
+    // Build tools
+    if (config.bundler === 'tsup') {
+        deps['tsup'] = '^8.0.0';
+    }
+    else if (config.bundler === 'esbuild') {
+        deps['esbuild'] = '^0.25.0';
+    }
+    else if (config.bundler === 'rollup') {
+        deps['rollup'] = '^4.0.0';
+        deps['@rollup/plugin-typescript'] = '^12.0.0';
+        deps['tslib'] = '^2.0.0';
+    }
+    else if (config.bundler === 'rolldown') {
+        // Rolldown transpiles TypeScript natively — no plugin-typescript/tslib.
+        deps['rolldown'] = '^1.0.0';
+    }
+    else if (config.bundler === 'vite') {
+        deps['vite'] = '^6.0.0';
+    }
+    // Tailwind CSS v4 — CSS-first, wired via the PostCSS plugin.
+    if (config.tailwind) {
+        deps['tailwindcss'] = '^4.0.0';
+        deps['@tailwindcss/postcss'] = '^4.0.0';
+    }
+    // Publishing hygiene
+    if (config.publint) {
+        deps['publint'] = '^0.3.0';
+    }
+    // Git hooks
+    if (config.gitHooks) {
+        deps['husky'] = '^9.0.0';
+        deps['lint-staged'] = '^16.0.0';
+    }
+    // are-the-types-wrong — validate published type resolution for libraries.
+    if (config.projectType === 'library') {
+        deps['@arethetypeswrong/cli'] = '^0.18.2';
+    }
+    // Commit linting (enforcement) + commitizen (assistance)
+    if (config.commitLint) {
+        deps['@commitlint/cli'] = '^20.0.0';
+        deps['@commitlint/config-conventional'] = '^20.0.0';
+        deps['commitizen'] = '^4.3.1';
+        deps['cz-conventional-changelog'] = '^3.3.0';
+    }
+    // Semantic release. The shipped github preset activates the changelog and
+    // git plugins (and @semantic-release/github), so they must be installed too
+    // or `semantic-release` crashes with "Cannot find module".
+    if (config.semanticRelease) {
+        deps['semantic-release'] = '^25.0.0';
+        deps['@semantic-release/github'] = '^12.0.0';
+        deps['@semantic-release/changelog'] = '^6.0.0';
+        deps['@semantic-release/git'] = '^10.0.0';
+    }
+    return deps;
+}

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

@@ -0,0 +1,126 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * Since pnpm 10, repo-wide settings live in `pnpm-workspace.yaml` rather than
+ * `.npmrc` — for single-package repos too, not just workspaces. These are the
+ * family-wide settings that otherwise get hand-copied and drift (#314).
+ *
+ * Every write here is a merge: `pnpm-workspace.yaml` also carries the repo's own
+ * `packages:` globs and hand-vetted `allowBuilds` entries, so nothing is
+ * rewritten and no existing value is overridden.
+ */
+export const WORKSPACE_FILE = 'pnpm-workspace.yaml';
+/**
+ * pnpm's `minimumReleaseAge` cutoff holds back freshly published versions —
+ * good against a typosquat-hijack, but it also stalls every consumer of a
+ * same-day `@rtorcato/*` fix for 24h. One glob covers the whole family: pnpm
+ * matches these entries with `@pnpm/config.matcher`, so there's no package list
+ * to keep in sync with `@rtorcato/shared-docs`'s `FAMILY`.
+ */
+const FAMILY_GLOB = '@rtorcato/*';
+/** Bundlers that pull in esbuild, whose install script pnpm 11 refuses to run unapproved. */
+const ESBUILD_BUNDLERS = ['esbuild', 'tsup', 'vite'];
+/** True when the repo depends on a bundler that drags esbuild in. */
+export function dependsOnEsbuild(deps) {
+    return ESBUILD_BUNDLERS.some((name) => name in deps);
+}
+/**
+ * The lines of a top-level YAML block, e.g. everything indented under
+ * `allowBuilds:`. Returns null when the key isn't present at all. Hand-rolled
+ * because adding a YAML parser to a 5-dependency CLI to read three keys isn't
+ * worth it — and the same shape is already parsed this way in `misc.ts`.
+ */
+function section(yaml, key) {
+    const lines = yaml.split('\n');
+    const start = lines.findIndex((line) => line.startsWith(`${key}:`));
+    if (start === -1)
+        return null;
+    const body = [];
+    for (const line of lines.slice(start + 1)) {
+        if (/^\S/.test(line))
+            break; // a new top-level key ends the block
+        body.push(line);
+    }
+    return body;
+}
+const 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),
+        key: 'verifyDepsBeforeRun',
+        block: `# Don't re-verify node_modules on every script run — the check costs a
+# second per invocation and CI installs with --frozen-lockfile anyway.
+verifyDepsBeforeRun: false
+`,
+        item: '',
+    },
+    {
+        label: `minimumReleaseAgeExclude: ${FAMILY_GLOB}`,
+        applies: () => true,
+        satisfied: (yaml) => (section(yaml, 'minimumReleaseAgeExclude') ?? []).some(hasFamilyGlob),
+        key: 'minimumReleaseAgeExclude',
+        block: `# Exempt the @rtorcato family from pnpm's minimumReleaseAge cutoff, so a
+# same-day fix in a sibling package is installable today rather than tomorrow.
+minimumReleaseAgeExclude:
+  - '${FAMILY_GLOB}'
+`,
+        item: `  - '${FAMILY_GLOB}'`,
+    },
+    {
+        label: 'allowBuilds: esbuild',
+        applies: (needsEsbuild) => needsEsbuild,
+        satisfied: (yaml) => (section(yaml, 'allowBuilds') ?? []).some((l) => /^\s*esbuild:/.test(l)),
+        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
+`,
+        item: '  esbuild: true',
+    },
+];
+function hasFamilyGlob(line) {
+    return line.includes(FAMILY_GLOB);
+}
+/** Managed settings absent from `yaml`, named as doctor reports them. */
+export function missingPnpmSettings(yaml, needsEsbuild) {
+    return SETTINGS.filter((s) => s.applies(needsEsbuild) && !s.satisfied(yaml)).map((s) => s.label);
+}
+/** Insert `item` directly under an existing `key:` line, keeping the rest untouched. */
+function insertUnder(yaml, key, item) {
+    const lines = yaml.split('\n');
+    const at = lines.findIndex((line) => line.startsWith(`${key}:`));
+    lines.splice(at + 1, 0, item);
+    return lines.join('\n');
+}
+/** Merge every missing managed setting into `yaml` and return the new contents. */
+export function upsertPnpmSettings(yaml, needsEsbuild) {
+    let next = yaml;
+    for (const setting of SETTINGS) {
+        if (!setting.applies(needsEsbuild) || setting.satisfied(next))
+            continue;
+        if (setting.item && section(next, setting.key)) {
+            next = insertUnder(next, setting.key, setting.item);
+        }
+        else {
+            next = `${next.replace(/\n*$/, '\n')}\n${setting.block}`;
+        }
+    }
+    return next;
+}
+/**
+ * Merge the managed pnpm settings into `pnpm-workspace.yaml`, creating it when
+ * absent. Returns the relative path if anything changed, else null.
+ */
+export async function ensurePnpmSettings(targetDir, needsEsbuild) {
+    const file = path.join(targetDir, WORKSPACE_FILE);
+    const current = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf-8') : '';
+    const next = upsertPnpmSettings(current, needsEsbuild);
+    if (next === current)
+        return null;
+    await fs.writeFile(file, next.replace(/^\n+/, ''));
+    return WORKSPACE_FILE;
+}

package/dist/cli/generators/postcss.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * Scaffold a minimal PostCSS config for non-Tailwind CSS pipelines (autoprefixer
+ * over your browserslist). Tailwind v4 users get their PostCSS wiring from the
+ * Tailwind preset instead (`@tailwindcss/postcss`, which autoprefixes on its
+ * own), so this stays out of their way — safe-add never clobbers an existing
+ * postcss.config.mjs.
+ */
+export async function generatePostcss(targetDir) {
+    const dest = path.join(targetDir, 'postcss.config.mjs');
+    if (await fs.pathExists(dest))
+        return [];
+    await fs.writeFile(dest, POSTCSS_CONFIG);
+    return ['postcss.config.mjs'];
+}
+const POSTCSS_CONFIG = `export default {
+	plugins: {
+		// Adds vendor prefixes based on your browserslist (package.json or
+		// .browserslistrc). Add more PostCSS plugins here as needed.
+		autoprefixer: {},
+	},
+}
+`;