@rtorcato/repo-tooling 2.59.0

package/dist/cli/generators/badges.js

@@ -0,0 +1,88 @@
+// Shared badge-block builder. All URLs are derived from package.json (name +
+// repository) — no hardcoded owner/repo — so it works for any consumer.
+export const BADGE_START = '<!-- js-tooling:badges:start -->';
+export const BADGE_END = '<!-- js-tooling:badges:end -->';
+/**
+ * Parse a package.json `repository` field into `{ owner, repo }`.
+ * Handles the shorthand (`owner/repo`, `github:owner/repo`) and full git URLs
+ * (`git+https://github.com/owner/repo.git`, `git@github.com:owner/repo.git`).
+ * Returns null for non-GitHub or unparseable values.
+ */
+export function parseRepository(repository) {
+    const url = typeof repository === 'string'
+        ? repository
+        : repository && typeof repository === 'object'
+            ? repository.url
+            : undefined;
+    if (typeof url !== 'string' || url.length === 0)
+        return null;
+    // `owner/repo` or `github:owner/repo` shorthand (no scheme, no host).
+    if (!url.includes('://') && !url.includes('@')) {
+        const short = url.replace(/^github:/, '').match(/^([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);
+        if (short?.[1] && short[2])
+            return { owner: short[1], repo: short[2] };
+    }
+    const m = url.match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:$|[/#?])/);
+    return m?.[1] && m[2] ? { owner: m[1], repo: m[2] } : null;
+}
+/**
+ * Build the badge markdown row (no delimiter comments). Returns '' when only
+ * the always-on license badge would render — i.e. nothing package- or
+ * repo-specific is derivable, so a badge row isn't worth adding.
+ */
+export function buildBadgeRow(inputs) {
+    const { name, owner, repo, branch = 'main', isPrivate = false } = inputs;
+    const slug = owner && repo ? `${owner}/${repo}` : null;
+    const badges = [];
+    let specific = false;
+    if (slug) {
+        specific = true;
+        badges.push(`[![CI](https://github.com/${slug}/actions/workflows/ci.yml/badge.svg)](https://github.com/${slug}/actions/workflows/ci.yml)`);
+    }
+    if (!isPrivate && name) {
+        specific = true;
+        badges.push(`[![npm version](https://img.shields.io/npm/v/${name})](https://www.npmjs.com/package/${name})`);
+        badges.push(`[![npm downloads](https://img.shields.io/npm/dm/${name})](https://www.npmjs.com/package/${name})`);
+        badges.push(`[![Bundle size](https://img.shields.io/bundlephobia/minzip/${name})](https://bundlephobia.com/package/${name})`);
+    }
+    if (!isPrivate && slug) {
+        badges.push(`[![Coverage](https://codecov.io/gh/${slug}/branch/${branch}/graph/badge.svg)](https://codecov.io/gh/${slug})`);
+    }
+    badges.push('[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)');
+    return specific ? badges.join('\n') : '';
+}
+/** Build the full delimited badge block, or '' when there's nothing worth showing. */
+export function buildBadgeBlock(inputs) {
+    const row = buildBadgeRow(inputs);
+    return row ? `${BADGE_START}\n${row}\n${BADGE_END}` : '';
+}
+/** True when the text carries npm/bundlephobia/codecov badges (which 404 on private/unpublished). */
+export function hasPublicOnlyBadges(text) {
+    return /img\.shields\.io\/npm\/|bundlephobia|codecov\.io/.test(text);
+}
+/**
+ * Insert or refresh the badge block in a README. Replaces an existing delimited
+ * block in place; otherwise inserts right after the first H1 (or prepends when
+ * there is none). Passing an empty block strips any existing one. Idempotent.
+ */
+export function upsertBadges(readme, block) {
+    const start = readme.indexOf(BADGE_START);
+    const end = readme.indexOf(BADGE_END);
+    const hasBlock = start !== -1 && end !== -1 && end > start;
+    if (!block) {
+        if (!hasBlock)
+            return readme;
+        // Strip the block plus the blank line that follows it, if any.
+        const after = readme.slice(end + BADGE_END.length).replace(/^\n\n/, '\n');
+        return (readme.slice(0, start).replace(/\n\n$/, '\n') + after).replace(/^\n+/, '');
+    }
+    if (hasBlock) {
+        return readme.slice(0, start) + block + readme.slice(end + BADGE_END.length);
+    }
+    const lines = readme.split('\n');
+    const h1 = lines.findIndex((l) => /^#\s+/.test(l));
+    if (h1 === -1)
+        return `${block}\n\n${readme}`;
+    lines.splice(h1 + 1, 0, '', block);
+    return lines.join('\n');
+}

package/dist/cli/generators/build.js

@@ -0,0 +1,216 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+// tsup, esbuild, and vite all pull in esbuild, whose install-time build script
+// pnpm 11 refuses to run until it's approved — otherwise `pnpm install` fails
+// with ERR_PNPM_IGNORED_BUILDS.
+export function bundlerNeedsEsbuild(config) {
+    return config.bundler === 'tsup' || config.bundler === 'esbuild' || config.bundler === 'vite';
+}
+// pnpm 11 reads build-script approvals from the `allowBuilds` map (package →
+// boolean), NOT the older `onlyBuiltDependencies` list — verified against the
+// pinned pnpm@11.1.3, which ignores the list form and errors with
+// ERR_PNPM_IGNORED_BUILDS.
+const SINGLE_PACKAGE_BUILD_APPROVALS = `allowBuilds:
+  esbuild: true
+`;
+/**
+ * pnpm 11 no longer reads build-script approvals from package.json's `pnpm`
+ * field — they live in pnpm-workspace.yaml. For a single-package esbuild-backed
+ * build, write a minimal pnpm-workspace.yaml approving esbuild. Never clobbers
+ * an existing file (the treeshake-check path writes a richer one that already
+ * lists esbuild). Must run after that path so its file wins. Returns the
+ * relative path if written, else null.
+ */
+export async function ensureBuildApprovals(config, targetDir) {
+    if (!bundlerNeedsEsbuild(config))
+        return null;
+    const wsPath = path.join(targetDir, 'pnpm-workspace.yaml');
+    if (await fs.pathExists(wsPath))
+        return null;
+    await fs.writeFile(wsPath, SINGLE_PACKAGE_BUILD_APPROVALS);
+    return 'pnpm-workspace.yaml';
+}
+export async function generateBuildConfigs(config, targetDir) {
+    if (config.bundler === 'tsup') {
+        await generateTsupConfig(targetDir);
+    }
+    else if (config.bundler === 'esbuild') {
+        await generateEsbuildConfig(targetDir);
+    }
+    else if (config.bundler === 'rollup') {
+        await generateRollupConfig(targetDir);
+    }
+    else if (config.bundler === 'rolldown') {
+        await generateRolldownConfig(targetDir);
+    }
+    else if (config.bundler === 'vite') {
+        await generateViteConfig(config, targetDir);
+    }
+    // Generate semantic-release config for GitHub
+    if (config.semanticRelease) {
+        await generateSemanticReleaseConfig(targetDir);
+    }
+    // Generate Changesets config (alternative to semantic-release)
+    if (config.changesets) {
+        await generateChangesetsConfig(targetDir);
+    }
+    // Generate Release Please config (alternative to semantic-release)
+    if (config.releasePlease) {
+        await generateReleasePleaseConfig(targetDir);
+    }
+}
+async function generateTsupConfig(targetDir) {
+    const tsupConfigPath = path.join(targetDir, 'tsup.config.ts');
+    const tsupConfig = `import { getConfig } from '@rtorcato/repo-tooling/tsup'
+
+export default getConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  clean: true,
+  splitting: false,
+  sourcemap: true,
+}, process.env.NODE_ENV || 'development')
+`;
+    await fs.writeFile(tsupConfigPath, tsupConfig);
+}
+async function generateEsbuildConfig(targetDir) {
+    const esbuildConfigPath = path.join(targetDir, 'build.mjs');
+    const esbuildConfig = `import { build } from 'esbuild'
+import { nodeExternalsPlugin } from 'esbuild-node-externals'
+
+const isProduction = process.env.NODE_ENV === 'production'
+
+await build({
+  entryPoints: ['src/index.ts'],
+  bundle: true,
+  outdir: 'dist',
+  format: 'esm',
+  target: 'node18',
+  platform: 'node',
+  minify: isProduction,
+  sourcemap: !isProduction,
+  plugins: [nodeExternalsPlugin()],
+})
+
+console.log('Build completed!')
+`;
+    await fs.writeFile(esbuildConfigPath, esbuildConfig);
+}
+export async function generateRollupConfig(targetDir) {
+    const rollupConfigPath = path.join(targetDir, 'rollup.config.mjs');
+    const rollupConfig = `export { default } from '@rtorcato/repo-tooling/rollup'
+`;
+    await fs.writeFile(rollupConfigPath, rollupConfig);
+}
+export async function generateRolldownConfig(targetDir) {
+    const rolldownConfigPath = path.join(targetDir, 'rolldown.config.mjs');
+    const rolldownConfig = `export { default } from '@rtorcato/repo-tooling/rolldown'
+`;
+    await fs.writeFile(rolldownConfigPath, rolldownConfig);
+}
+export async function generateViteConfig(config, targetDir) {
+    const viteConfigPath = path.join(targetDir, 'vite.config.ts');
+    // React apps need the plugin; we layer it on top of the shipped preset.
+    const viteConfig = config.projectType === 'react-app'
+        ? `import preset from '@rtorcato/repo-tooling/vite'
+import react from '@vitejs/plugin-react'
+import { defineConfig, mergeConfig } from 'vite'
+
+export default mergeConfig(preset, defineConfig({ plugins: [react()] }))
+`
+        : `export { default } from '@rtorcato/repo-tooling/vite'
+`;
+    await fs.writeFile(viteConfigPath, viteConfig);
+}
+// Plugins the github/gitlab preset activates that semantic-release core does
+// NOT bundle (core bundles only commit-analyzer, release-notes-generator, npm,
+// github). Without these in the consumer's deps, `semantic-release` crashes
+// with "Cannot find module '@semantic-release/changelog'" on first run.
+const RELEASE_PLUGIN_DEPS = {
+    '@semantic-release/changelog': '^6.0.0',
+    '@semantic-release/git': '^10.0.0',
+};
+export async function generateSemanticReleaseConfig(targetDir) {
+    const releaseConfigPath = path.join(targetDir, 'release.config.mjs');
+    const releaseConfig = `export { default } from '@rtorcato/repo-tooling/semantic-release/github'
+`;
+    await fs.writeFile(releaseConfigPath, releaseConfig);
+    const written = ['release.config.mjs'];
+    // Ensure the preset's non-bundled plugins are installed; otherwise the
+    // scaffolded release.config.mjs references modules the consumer lacks.
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (await fs.pathExists(pkgPath)) {
+        const pkg = (await fs.readJson(pkgPath));
+        const devDeps = (pkg.devDependencies ?? {});
+        const deps = (pkg.dependencies ?? {});
+        let changed = false;
+        for (const [name, version] of Object.entries(RELEASE_PLUGIN_DEPS)) {
+            if (!devDeps[name] && !deps[name]) {
+                devDeps[name] = version;
+                changed = true;
+            }
+        }
+        if (changed) {
+            pkg.devDependencies = devDeps;
+            await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+            written.push('package.json');
+        }
+    }
+    return written;
+}
+export async function generateChangesetsConfig(targetDir) {
+    // Drop the canonical Changesets config into .changeset/config.json. The user
+    // owns this file once it's in their repo; subsequent `pnpm changeset` runs
+    // create per-change markdown files alongside it.
+    const { copyPreset } = await import('../utils/copy-preset.js');
+    await copyPreset('changesets', targetDir);
+}
+// The release-please workflow — googleapis/release-please-action opens/maintains
+// a release PR on every push to main and tags + creates the GitHub release when
+// it merges. RELEASE_TOKEN (falling back to GITHUB_TOKEN) lets the release PR's
+// checks run, mirroring the semantic-release setup.
+const RELEASE_PLEASE_WORKFLOW = `name: release-please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          token: \${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+`;
+/**
+ * Scaffolds Release Please: the config (from the shipped preset), a starting
+ * manifest, and the release workflow. The config is (re)written to realign with
+ * the preset, but the manifest (holds live versions) and the workflow (may be
+ * user-tuned) are only created when absent. Returns the relative paths touched.
+ */
+export async function generateReleasePleaseConfig(targetDir) {
+    const { copyPreset, getPackageRoot } = await import('../utils/copy-preset.js');
+    const written = [];
+    const cfg = await copyPreset('release-please', targetDir);
+    written.push(cfg.target);
+    const manifestDest = path.join(targetDir, '.release-please-manifest.json');
+    if (!(await fs.pathExists(manifestDest))) {
+        await fs.copy(path.join(getPackageRoot(), 'tooling/release-please/.release-please-manifest.json'), manifestDest);
+    }
+    written.push('.release-please-manifest.json');
+    const workflowPath = path.join(targetDir, '.github', 'workflows', 'release-please.yml');
+    if (!(await fs.pathExists(workflowPath))) {
+        await fs.ensureDir(path.dirname(workflowPath));
+        await fs.writeFile(workflowPath, RELEASE_PLEASE_WORKFLOW);
+    }
+    written.push('.github/workflows/release-please.yml');
+    return written;
+}

package/dist/cli/generators/bun.js

@@ -0,0 +1,25 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * Scaffold Bun toolchain files: a bunfig.toml and — only when no tsconfig.json
+ * exists yet — a tsconfig.json that extends the Bun-typed preset
+ * (`@rtorcato/repo-tooling/typescript/bun`, which adds `types: ['bun']`). Both are
+ * safe-add: an existing bunfig.toml or tsconfig.json is never clobbered (an
+ * existing project points its tsconfig at the bun preset by hand — see the docs).
+ * Returns the relative paths written.
+ */
+export async function generateBun(targetDir) {
+    const written = [];
+    const bunfigPath = path.join(targetDir, 'bunfig.toml');
+    if (!(await fs.pathExists(bunfigPath))) {
+        const { copyPreset } = await import('../utils/copy-preset.js');
+        const result = await copyPreset('bun', targetDir);
+        written.push(result.target);
+    }
+    const tsconfigPath = path.join(targetDir, 'tsconfig.json');
+    if (!(await fs.pathExists(tsconfigPath))) {
+        await fs.writeJson(tsconfigPath, { extends: '@rtorcato/repo-tooling/typescript/bun' }, { spaces: 2 });
+        written.push('tsconfig.json');
+    }
+    return written;
+}

package/dist/cli/generators/community-health.js

@@ -0,0 +1,145 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+const CONTRIBUTING = `# Contributing
+
+Thanks for your interest in contributing!
+
+## Local setup
+
+\`\`\`bash
+pnpm install
+pnpm build
+pnpm test
+\`\`\`
+
+## Commit messages
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/).
+Format: \`type(scope): summary\` — e.g. \`fix(api): handle empty payload\`.
+Common types: \`feat\`, \`fix\`, \`docs\`, \`refactor\`, \`test\`, \`chore\`.
+If commitizen is set up, run \`pnpm commit\` to be guided through it.
+
+## Pull requests
+
+- Keep PRs focused and small where possible.
+- Make sure \`pnpm test\` and \`pnpm check\` (lint) pass.
+- Add tests for new behaviour.
+- Describe what changed and why in the PR description.
+`;
+// Relative advisory link works from a repo-root SECURITY.md on GitHub, so the
+// template stays repo-agnostic (no hardcoded owner/name). Fill in the contact.
+const SECURITY = `# Security Policy
+
+## Supported versions
+
+Only the latest major version receives security fixes.
+
+## Reporting a vulnerability
+
+Do **not** open a public GitHub issue for security vulnerabilities.
+
+Instead, use [GitHub's private vulnerability reporting](../../security/advisories/new)
+or email **<security-contact@example.com>** with:
+
+- A description of the vulnerability
+- Steps to reproduce
+- Potential impact
+
+You'll receive a response within 5 business days.
+`;
+const PULL_REQUEST_TEMPLATE = `## Summary
+
+<!-- 1-3 bullet points describing what changed and why -->
+-
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor / cleanup
+- [ ] Documentation
+- [ ] CI / tooling
+
+## Test plan
+
+- [ ] Existing tests pass (\`pnpm test\`)
+- [ ] New tests added for new behaviour
+
+## Checklist
+
+- [ ] No debug logging left in production code
+- [ ] No breaking changes (or BREAKING CHANGE footer added to commit)
+- [ ] Lint passes (\`pnpm check\` / \`pnpm lint\`)
+`;
+const BUG_REPORT = `---
+name: Bug report
+about: Something isn't working as expected
+labels: bug
+---
+
+## Describe the bug
+
+<!-- A clear and concise description of what the bug is -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behaviour
+
+## Actual behaviour
+
+<!-- Paste any error output here -->
+
+\`\`\`
+\`\`\`
+
+## Environment
+
+- Package version:
+- Node version (\`node -v\`):
+- Package manager + version:
+- OS:
+`;
+const FEATURE_REQUEST = `---
+name: Feature request
+about: Suggest an idea or improvement
+labels: enhancement
+---
+
+## Problem
+
+<!-- What are you trying to do that you can't do today? -->
+
+## Proposed solution
+
+## Alternatives considered
+
+## Additional context
+`;
+const FILES = [
+    { rel: 'CONTRIBUTING.md', content: CONTRIBUTING },
+    { rel: 'SECURITY.md', content: SECURITY },
+    { rel: '.github/PULL_REQUEST_TEMPLATE.md', content: PULL_REQUEST_TEMPLATE },
+    { rel: '.github/ISSUE_TEMPLATE/bug_report.md', content: BUG_REPORT },
+    { rel: '.github/ISSUE_TEMPLATE/feature_request.md', content: FEATURE_REQUEST },
+];
+/**
+ * Scaffold GitHub community-health files. Safe-add: existing files are left
+ * untouched (the user owns them once written). Returns the list of files
+ * actually created.
+ */
+export async function generateCommunityHealth(targetDir) {
+    const written = [];
+    for (const { rel, content } of FILES) {
+        const filepath = path.join(targetDir, rel);
+        if (await fs.pathExists(filepath))
+            continue;
+        await fs.ensureDir(path.dirname(filepath));
+        await fs.writeFile(filepath, content);
+        written.push(rel);
+    }
+    return written;
+}