@rtorcato/repo-tooling 4.0.0 → 4.2.0

package/dist/base/fixers.js

@@ -75,6 +75,7 @@ export const BASE_FIXERS = [
     },
     {
         target: 'editorconfig',
+        selfSafe: true,
         description: 'Scaffold .editorconfig (UTF-8, LF, tab indent)',
         appliesTo: ['EditorConfig'],
         outputs: ['.editorconfig'],
@@ -145,6 +146,7 @@ export const BASE_FIXERS = [
     },
     {
         target: 'codeql',
+        selfSafe: true,
         description: 'Scaffold .github/workflows/codeql.yml (security scanning)',
         appliesTo: ['CodeQL'],
         outputs: ['.github/workflows/codeql.yml'],
@@ -214,6 +216,7 @@ export const BASE_FIXERS = [
     },
     {
         target: 'codeowners',
+        selfSafe: true,
         description: 'Scaffold .github/CODEOWNERS with commented examples',
         appliesTo: ['CODEOWNERS'],
         outputs: ['.github/CODEOWNERS'],
@@ -226,6 +229,7 @@ export const BASE_FIXERS = [
     },
     {
         target: 'community-health',
+        selfSafe: true,
         description: 'Scaffold CONTRIBUTING.md, SECURITY.md, PR + issue templates',
         appliesTo: ['Community health'],
         outputs: [
@@ -244,6 +248,7 @@ export const BASE_FIXERS = [
     },
     {
         target: 'brand',
+        selfSafe: true,
         description: 'Scaffold brand/ — banner, mobile-banner and social-card SVG sources + render.sh, and repoint a README still on root-level banner paths',
         appliesTo: ['Brand assets'],
         outputs: [
@@ -257,8 +262,8 @@ export const BASE_FIXERS = [
         // image paths — hand-edited art is never clobbered.
         riskLevel: 'safe-merge',
         canFixDrift: true,
-        async run({ targetDir, pkg }) {
-            const filesWritten = await generateBrand(pkg, targetDir);
+        async run({ targetDir, pkg, lock }) {
+            const filesWritten = await generateBrand(pkg, targetDir, lock?.rules?.brand?.tagline);
             if (filesWritten.some((f) => f.endsWith('.svg'))) {
                 console.error(chalk.dim('   next: run `brand/render.sh` to render the PNGs (needs librsvg — `brew install librsvg`)'));
             }

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

@@ -209,6 +209,7 @@ export const CONFIG_SCHEMA = {
         turborepo: { type: 'boolean' },
         nx: { type: 'boolean' },
         tailwind: { type: 'boolean' },
+        docsSite: { type: 'boolean' },
         bun: { type: 'boolean' },
     },
 };

package/dist/cli/generators/brand.js

@@ -6,8 +6,9 @@
  * PNG, so a banner can be recoloured, retitled or resized instead of being a
  * committed binary nobody can regenerate.
  *
- * Everything in the emitted SVGs is derived from the consuming repo — name and
- * tagline from its package.json, accent from its own docs theme or favicon —
+ * Everything in the emitted SVGs is derived from the consuming repo — name from
+ * its package.json, tagline from `rules.brand.tagline` in .repo-tooling.json or
+ * else the package.json description (#666), accent from its own docs theme or favicon —
  * and falls back to a neutral grey. Nothing about any particular org is baked
  * in; the templates are meant to be hand-edited afterwards.
  */
@@ -94,14 +95,29 @@ async function accentFromFavicon(targetDir) {
     }
     return null;
 }
-export async function resolveBrandMeta(pkg, targetDir) {
+/**
+ * The narrowest tagline budget any canvas uses (the mobile banner). A tagline
+ * that needs more than two lines of it crowds the layout and gets cut off.
+ */
+const TAGLINE_MAX_CHARS = 42;
+/** True when `tagline` fits in two lines on every canvas, without an ellipsis. */
+export function taglineFits(tagline) {
+    const words = tagline.split(/\s+/).filter(Boolean).join(' ');
+    return wrapText(tagline, TAGLINE_MAX_CHARS, 2).join(' ') === words;
+}
+/**
+ * `tagline` is `rules.brand.tagline` from .repo-tooling.json: a short line
+ * written for the banner. Without it the package.json description stands in,
+ * which is often a full sentence too long for the canvas (#666).
+ */
+export async function resolveBrandMeta(pkg, targetDir, tagline) {
     const pkgName = typeof pkg?.name === 'string' ? pkg.name : undefined;
     const name = pkgName?.split('/').pop() ?? path.basename(path.resolve(targetDir));
     const description = typeof pkg?.description === 'string' ? pkg.description : '';
     const accent = (await accentFromDocsTheme(targetDir)) ?? (await accentFromFavicon(targetDir)) ?? NEUTRAL_ACCENT;
     return {
         name,
-        tagline: description || 'Add a one-line tagline to package.json "description".',
+        tagline: tagline || description || 'Add a short tagline as rules.brand.tagline in .repo-tooling.json.',
         accent,
         install: pkgName && pkg?.private !== true ? pkgName : null,
     };
@@ -268,8 +284,8 @@ export async function repointReadmeBanners(targetDir) {
  * README still on the old root-level paths. Every file is written only when
  * absent, so `fix brand` is idempotent.
  */
-export async function generateBrand(pkg, targetDir) {
-    const meta = await resolveBrandMeta(pkg, targetDir);
+export async function generateBrand(pkg, targetDir, tagline) {
+    const meta = await resolveBrandMeta(pkg, targetDir, tagline);
     const written = [];
     const files = [
         ['brand/banner.svg', bannerSvg(meta)],
@@ -282,6 +298,10 @@ export async function generateBrand(pkg, targetDir) {
         if (w)
             written.push(w);
     }
+    // stderr, not stdout: `fix --json` owns stdout (#357).
+    if (written.some((f) => f.endsWith('.svg')) && !taglineFits(meta.tagline)) {
+        console.error('   warning: the tagline needs more than two lines and will be cut off on the mobile banner — set a shorter one as rules.brand.tagline in .repo-tooling.json');
+    }
     const readme = await repointReadmeBanners(targetDir);
     if (readme)
         written.push(readme);

package/dist/cli/generators/docs-site.js

@@ -3,6 +3,7 @@ import fs from 'fs-extra';
 import selfPackageJson from '../../../package.json' with { type: 'json' };
 import { copyPreset, PRESETS } from '../utils/copy-preset.js';
 import { buildBadgeRow, parseRepository } from './badges.js';
+import { DOCS_SITE_BUILDS, mergeAllowBuilds } from './pnpm-workspace.js';
 import { inferSubpathsFromExports } from './treeshake.js';
 /**
  * What a scaffolded docs site should depend on for *this* CLI — read from the
@@ -64,29 +65,37 @@ async function writeIfMissing(targetDir, rel, contents) {
     await fs.writeFile(file, contents);
     return rel;
 }
-/** Ensure `pnpm-workspace.yaml` lists `apps/*` (idempotent). */
+/**
+ * Ensure `pnpm-workspace.yaml` lists `apps/*` and approves the site's build
+ * scripts (idempotent).
+ */
 async function ensureWorkspace(targetDir) {
     const rel = 'pnpm-workspace.yaml';
     const file = path.join(targetDir, rel);
-    if (await fs.pathExists(file)) {
-        const body = await fs.readFile(file, 'utf8');
-        // Already a workspace covering apps/* (either `apps/*` or a broader glob).
-        if (/^\s*-\s*['"]?apps\/\*/m.test(body))
-            return null;
-        if (/^packages:/m.test(body)) {
-            const next = body.replace(/^packages:\n/m, "packages:\n  - 'apps/*'\n");
-            await fs.writeFile(file, next);
-            return rel;
-        }
-        await fs.writeFile(file, `packages:\n  - 'apps/*'\n\n${body}`);
-        return rel;
+    const body = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf8') : '';
+    let next = body;
+    // Already a workspace covering apps/* (either `apps/*` or a broader glob).
+    if (!/^\s*-\s*['"]?apps\/\*/m.test(body)) {
+        next = /^packages:/m.test(body)
+            ? body.replace(/^packages:\n/m, "packages:\n  - 'apps/*'\n")
+            : `packages:\n  - 'apps/*'\n${body ? `\n${body}` : ''}`;
     }
-    await fs.writeFile(file, "packages:\n  - 'apps/*'\n");
+    next = mergeAllowBuilds(next, DOCS_SITE_BUILDS);
+    if (next === body)
+        return null;
+    await fs.writeFile(file, next);
     return rel;
 }
-/** The GitHub Pages base path Docusaurus serves under, e.g. `/repo-tooling/`. */
-function siteBaseUrl(meta) {
-    return `/${meta.repo ?? meta.title}/`;
+/**
+ * A JS string literal in the Biome preset's quote style: single quotes, unless
+ * the value holds more single than double quotes — the same pick Biome makes.
+ */
+function jsString(value) {
+    const singles = value.split("'").length - 1;
+    const doubles = value.split('"').length - 1;
+    if (singles > doubles)
+        return JSON.stringify(value);
+    return `'${JSON.stringify(value).slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'")}'`;
 }
 function docusaurusConfig(meta, typedocModules) {
     const owner = meta.owner ?? 'your-org';
@@ -98,111 +107,111 @@ function docusaurusConfig(meta, typedocModules) {
         ? "import { getTypedocPlugins } from '@rtorcato/repo-tooling/docusaurus'\n"
         : '';
     const typedocPlugins = typedocModules.length
-        ? `    ...getTypedocPlugins(${JSON.stringify(typedocModules)}),\n`
+        ? `\t\t...getTypedocPlugins([${typedocModules.map(jsString).join(', ')}]),\n`
         : '';
     return `import type * as Preset from '@docusaurus/preset-classic'
 import type { Config } from '@docusaurus/types'
 import { themes as prismThemes } from 'prism-react-renderer'
 ${typedocImport}
 const config: Config = {
-  title: '${meta.title}',
-  tagline: ${JSON.stringify(meta.tagline)},
-  favicon: 'img/favicon.ico',
+\ttitle: '${meta.title}',
+\ttagline: ${jsString(meta.tagline)},
+\tfavicon: 'img/favicon.ico',
 
-  url: 'https://${owner}.github.io',
-  baseUrl: '/${repo}/',
+\turl: 'https://${owner}.github.io',
+\tbaseUrl: '/${repo}/',
 
-  organizationName: '${owner}',
-  projectName: '${repo}',
+\torganizationName: '${owner}',
+\tprojectName: '${repo}',
 
-  onBrokenLinks: 'warn',
+\tonBrokenLinks: 'warn',
 
-  markdown: {
-    format: 'detect',
-    hooks: {
-      onBrokenMarkdownLinks: 'warn',
-    },
-  },
+\tmarkdown: {
+\t\tformat: 'detect',
+\t\thooks: {
+\t\t\tonBrokenMarkdownLinks: 'warn',
+\t\t},
+\t},
 
-  i18n: {
-    defaultLocale: 'en',
-    locales: ['en'],
-  },
+\ti18n: {
+\t\tdefaultLocale: 'en',
+\t\tlocales: ['en'],
+\t},
 
-  presets: [
-    [
-      'classic',
-      {
-        docs: {
-          sidebarPath: './sidebars.ts',
-          routeBasePath: '/docs',
-          editUrl: '${ghUrl}/edit/main/apps/docs/',
-        },
-        blog: false,
-        theme: {
-          customCss: './src/css/custom.css',
-        },
-      } satisfies Preset.Options,
-    ],
-  ],
+\tpresets: [
+\t\t[
+\t\t\t'classic',
+\t\t\t{
+\t\t\t\tdocs: {
+\t\t\t\t\tsidebarPath: './sidebars.ts',
+\t\t\t\t\trouteBasePath: '/docs',
+\t\t\t\t\teditUrl: '${ghUrl}/edit/main/apps/docs/',
+\t\t\t\t},
+\t\t\t\tblog: false,
+\t\t\t\ttheme: {
+\t\t\t\t\tcustomCss: './src/css/custom.css',
+\t\t\t\t},
+\t\t\t} satisfies Preset.Options,
+\t\t],
+\t],
 
-  plugins: [
-${typedocPlugins}    [
-      '@easyops-cn/docusaurus-search-local',
-      {
-        hashed: true,
-        indexDocs: true,
-        indexBlog: false,
-        docsRouteBasePath: '/docs',
-        highlightSearchTermsOnTargetPage: true,
-        searchBarShortcutHint: false,
-      },
-    ],
-  ],
+\tplugins: [
+${typedocPlugins}\t\t[
+\t\t\t'@easyops-cn/docusaurus-search-local',
+\t\t\t{
+\t\t\t\thashed: true,
+\t\t\t\tindexDocs: true,
+\t\t\t\tindexBlog: false,
+\t\t\t\tdocsRouteBasePath: '/docs',
+\t\t\t\thighlightSearchTermsOnTargetPage: true,
+\t\t\t\tsearchBarShortcutHint: false,
+\t\t\t},
+\t\t],
+\t],
 
-  themeConfig: {
-    colorMode: {
-      defaultMode: 'dark',
-      respectPrefersColorScheme: true,
-    },
-    navbar: {
-      title: '${meta.title}',
-      items: [
-        { to: '/docs', position: 'left', label: 'Docs' },
-        {
-          href: '${ghUrl}',
-          label: 'GitHub',
-          position: 'right',
-        },
-      ],
-    },
-    footer: {
-      style: 'dark',
-      links: [
-        {
-          title: 'Docs',
-          items: [{ label: 'Getting Started', to: '/docs' }],
-        },
-        {
-          title: 'More',
-          items: [
-            { label: 'GitHub', href: '${ghUrl}' },
-            { label: 'Issues', href: '${ghUrl}/issues' },
-          ],
-        },
-      ],
-      copyright: \`Copyright © \${new Date().getFullYear()} ${meta.title}. Built with Docusaurus.\`,
-    },
-    // \`theme\` is the LIGHT-mode Prism theme and \`darkTheme\` the dark one. Both
-    // were vsDark here, which is why the shared stylesheet had to pin fenced
-    // blocks dark in light mode too (#324). Keep this pairing and the CSS in
-    // step — vsDark tokens on a light surface are unreadable.
-    prism: {
-      theme: prismThemes.vsLight,
-      darkTheme: prismThemes.vsDark,
-      additionalLanguages: ['bash', 'json', 'typescript'],
-    },
-  } satisfies Preset.ThemeConfig,
+\tthemeConfig: {
+\t\tcolorMode: {
+\t\t\tdefaultMode: 'dark',
+\t\t\trespectPrefersColorScheme: true,
+\t\t},
+\t\tnavbar: {
+\t\t\ttitle: '${meta.title}',
+\t\t\titems: [
+\t\t\t\t{ to: '/docs', position: 'left', label: 'Docs' },
+\t\t\t\t{
+\t\t\t\t\thref: '${ghUrl}',
+\t\t\t\t\tlabel: 'GitHub',
+\t\t\t\t\tposition: 'right',
+\t\t\t\t},
+\t\t\t],
+\t\t},
+\t\tfooter: {
+\t\t\tstyle: 'dark',
+\t\t\tlinks: [
+\t\t\t\t{
+\t\t\t\t\ttitle: 'Docs',
+\t\t\t\t\titems: [{ label: 'Getting Started', to: '/docs' }],
+\t\t\t\t},
+\t\t\t\t{
+\t\t\t\t\ttitle: 'More',
+\t\t\t\t\titems: [
+\t\t\t\t\t\t{ label: 'GitHub', href: '${ghUrl}' },
+\t\t\t\t\t\t{ label: 'Issues', href: '${ghUrl}/issues' },
+\t\t\t\t\t],
+\t\t\t\t},
+\t\t\t],
+\t\t\tcopyright: \`Copyright © \${new Date().getFullYear()} ${meta.title}. Built with Docusaurus.\`,
+\t\t},
+\t\t// \`theme\` is the LIGHT-mode Prism theme and \`darkTheme\` the dark one. Both
+\t\t// were vsDark here, which is why the shared stylesheet had to pin fenced
+\t\t// blocks dark in light mode too (#324). Keep this pairing and the CSS in
+\t\t// step — vsDark tokens on a light surface are unreadable.
+\t\tprism: {
+\t\t\ttheme: prismThemes.vsLight,
+\t\t\tdarkTheme: prismThemes.vsDark,
+\t\t\tadditionalLanguages: ['bash', 'json', 'typescript'],
+\t\t},
+\t} satisfies Preset.ThemeConfig,
 }
 
 export default config
@@ -213,7 +222,7 @@ const SIDEBARS = `import type { SidebarsConfig } from '@docusaurus/plugin-conten
 // Autogenerated from the docs/ folder structure — add markdown files and they
 // appear here. Swap for an explicit list when you want to control ordering.
 const sidebars: SidebarsConfig = {
-  docs: [{ type: 'autogenerated', dirName: '.' }],
+\tdocs: [{ type: 'autogenerated', dirName: '.' }],
 }
 
 export default sidebars
@@ -244,13 +253,13 @@ function customCss(accent) {
 @import "./_jt-tokens.css";
 
 :root {
-  --ifm-color-primary: ${accent.light};
-  --jt-accent: ${accent.light};
+\t--ifm-color-primary: ${accent.light};
+\t--jt-accent: ${accent.light};
 }
 
 [data-theme="dark"] {
-  --ifm-color-primary: ${accent.dark};
-  --jt-accent: ${accent.dark};
+\t--ifm-color-primary: ${accent.dark};
+\t--jt-accent: ${accent.dark};
 }
 `;
 }
@@ -277,9 +286,6 @@ function docsPackageJson(meta, typedoc) {
             serve: 'docusaurus serve',
             clear: 'docusaurus clear',
             typecheck: 'tsc --noEmit',
-            // Opt-in smoke test — builds, serves, and checks the site renders. Heavy
-            // browser install, so it's a manual/CI-gated run, not part of `build`.
-            'test:e2e': 'playwright test',
         },
         dependencies: {
             '@docusaurus/core': '^3.10.2',
@@ -295,7 +301,6 @@ function docsPackageJson(meta, typedoc) {
             '@docusaurus/module-type-aliases': '^3.10.2',
             '@docusaurus/tsconfig': '^3.8.1',
             '@docusaurus/types': '^3.10.2',
-            '@playwright/test': '^1.49.0',
             '@rtorcato/repo-tooling': SELF_RANGE,
             '@types/react': '^19.0.0',
             typescript: '~5.6.3',
@@ -352,48 +357,15 @@ jobs:
       build-filter: '${meta.docsPkgName}'
 `;
 }
-/**
- * Playwright config for the docs smoke test. Reuses the shipped preset, then
- * builds + serves the site on :3000 and points the base URL at the site's
- * GitHub Pages base path so routes resolve exactly as in production. One
- * browser keeps the CI browser install light.
- */
-function playwrightConfig(meta) {
-    const url = `http://localhost:3000${siteBaseUrl(meta)}`;
-    return `import { defineConfig, devices } from '@playwright/test'
-import base from '@rtorcato/repo-tooling/playwright'
+// routeBasePath is '/docs', so the site root has no page of its own and the
+// navbar logo links to a 404 on every page (#664). Redirect it to the docs.
+// Tabs/no semicolons to match the Biome preset the consuming repo is linted with.
+const HOME_PAGE = `import { Redirect } from '@docusaurus/router'
+import useBaseUrl from '@docusaurus/useBaseUrl'
 
-export default defineConfig({
-  ...base,
-  testDir: './tests',
-  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
-  use: {
-    ...base.use,
-    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? '${url}',
-  },
-  webServer: {
-    command: 'pnpm run build && pnpm exec docusaurus serve --port 3000',
-    url: process.env.PLAYWRIGHT_BASE_URL ?? '${url}',
-    reuseExistingServer: !process.env.CI,
-    timeout: 180_000,
-  },
-})
-`;
+export default function Home() {
+\treturn <Redirect to={useBaseUrl('/docs')} />
 }
-const SMOKE_SPEC = `import { expect, test } from '@playwright/test'
-
-// Smoke test: assert the built site serves and its core UI renders. Deliberately
-// content-agnostic — it validates "the site builds and boots", not copy.
-test('homepage responds and renders the shell', async ({ page }) => {
-  const res = await page.goto('./')
-  expect(res?.ok()).toBeTruthy()
-  await expect(page.locator('.navbar')).toBeVisible()
-})
-
-test('the starter doc renders a heading', async ({ page }) => {
-  await page.goto('./')
-  await expect(page.locator('h1')).toBeVisible()
-})
 `;
 /**
  * Scaffold the Docusaurus docs site. Writes each file only when missing and
@@ -426,9 +398,8 @@ export async function generateDocsSite(pkg, targetDir, options = {}) {
         [`${DOCS_APP}/sidebars.ts`, SIDEBARS],
         [`${DOCS_APP}/tsconfig.json`, TSCONFIG],
         [`${DOCS_APP}/src/css/custom.css`, customCss(accent)],
+        [`${DOCS_APP}/src/pages/index.tsx`, HOME_PAGE],
         [`${DOCS_APP}/docs/intro.md`, introDoc(meta, badges)],
-        [`${DOCS_APP}/playwright.config.ts`, playwrightConfig(meta)],
-        [`${DOCS_APP}/tests/smoke.spec.ts`, SMOKE_SPEC],
         ['.github/workflows/docs.yml', docsWorkflow(meta)],
     ];
     // TypeDoc emits docs/api/<id> on build — keep the generated tree out of git.

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

@@ -156,6 +156,32 @@ function insertUnder(yaml, key, item) {
     lines.splice(at + 1, 0, item);
     return lines.join('\n');
 }
+/**
+ * The build-script decisions a Docusaurus site needs under pnpm 11 (#663): it
+ * pulls in all four, and an undecided one fails the install. core-js's
+ * postinstall is only a banner, so it is declined; esbuild and sharp compile.
+ */
+export const DOCS_SITE_BUILDS = {
+    'core-js': false,
+    'core-js-pure': false,
+    esbuild: true,
+    sharp: true,
+};
+/**
+ * Merge `builds` into the `allowBuilds:` map, adding only the packages that
+ * carry no decision yet — an existing value, whichever way it went, stays.
+ */
+export function mergeAllowBuilds(yaml, builds) {
+    const entries = Object.entries(builds)
+        .filter(([name]) => !approved(yaml, name))
+        .map(([name, allow]) => `  ${asKey(name)}: ${allow}`)
+        .join('\n');
+    if (!entries)
+        return yaml;
+    if (section(yaml, 'allowBuilds'))
+        return insertUnder(yaml, 'allowBuilds', entries);
+    return `${yaml.replace(/\n*$/, '\n')}\nallowBuilds:\n${entries}\n`;
+}
 /** Merge every missing managed setting into `yaml` and return the new contents. */
 export function upsertPnpmSettings(yaml, needsEsbuild, glob) {
     let next = yaml;

package/dist/cli/index.js

@@ -1,22 +1,12 @@
 #!/usr/bin/env node
-import path from 'node:path';
 import chalk from 'chalk';
 import { Command } from 'commander';
-import fs from 'fs-extra';
 import { doctorCommand } from './commands/doctor.js';
 import { fixCommand } from './commands/fix.js';
 import { setupProject } from './commands/setup.js';
+import { selfRepoRefusal } from './self-repo.js';
 import { copyPreset, PRESETS } from './utils/copy-preset.js';
 import { getToolVersion } from './utils/version.js';
-async function isSelfRepo(dir) {
-    try {
-        const pkg = await fs.readJson(path.join(dir, 'package.json'));
-        return pkg.name === '@rtorcato/repo-tooling';
-    }
-    catch {
-        return false;
-    }
-}
 const program = new Command();
 program
     .name('@rtorcato/repo-tooling')
@@ -351,29 +341,11 @@ program
     process.exitCode = 1;
 });
 program.hook('preAction', async (_, actionCommand) => {
-    const name = actionCommand.name();
-    if (name === 'setup' || name === 'doctor' || name === 'fix') {
-        // `fix --list` is read-only and safe to run anywhere, including this repo.
-        if (name === 'fix' && actionCommand.opts().list)
-            return;
-        // Dogfood escape hatch (#273): allow read-only `doctor` against this repo
-        // so CI can audit our own config the same way it does consumers'. Scoped
-        // to doctor — the mutating setup/fix stay blocked even with the flag set.
-        if (name === 'doctor' && process.env.REPO_TOOLING_ALLOW_SELF === '1')
-            return;
-        // One mutating exception (#531): `fix lockfile` writes only
-        // .repo-tooling.json — no scaffolding — so our own lockfile can be
-        // migrated by the fixer we ship instead of by hand.
-        if (name === 'fix' &&
-            actionCommand.args[0] === 'lockfile' &&
-            process.env.REPO_TOOLING_ALLOW_SELF === '1')
-            return;
-        const dir = actionCommand.opts().directory ?? process.cwd();
-        if (await isSelfRepo(dir)) {
-            console.log(chalk.yellow('\n⚠️  This command cannot be run inside the @rtorcato/repo-tooling repo itself.\n'));
-            console.log(chalk.gray('   setup and doctor are for consumer projects, not for the tooling repo.\n'));
-            process.exit(0);
-        }
+    const refusal = await selfRepoRefusal(actionCommand.name(), actionCommand.args[0], actionCommand.opts());
+    if (refusal) {
+        console.log(chalk.yellow('\n⚠️  This command cannot be run inside the @rtorcato/repo-tooling repo itself.\n'));
+        console.log(chalk.gray(`   ${refusal}\n`));
+        process.exit(0);
     }
 });
 // Handle unknown commands

package/dist/cli/self-repo.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { getFixers } from './commands/fix.js';
+export async function isSelfRepo(dir) {
+    try {
+        const pkg = await fs.readJson(path.join(dir, 'package.json'));
+        return pkg.name === '@rtorcato/repo-tooling';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Why `setup` / `doctor` / `fix` must not run in `dir`, or null when it may.
+ * Most fixers write configs that import `@rtorcato/repo-tooling/...`, which
+ * this repo can't depend on, so inside it everything is refused unless
+ * `REPO_TOOLING_ALLOW_SELF=1` is set. With the flag, read-only `doctor` (#273)
+ * and `fix <target>` for a `selfSafe` target (#673) get through. A bare `fix`
+ * stays refused even then: it walks every fixer, self-safe or not.
+ */
+export async function selfRepoRefusal(command, target, opts, env = process.env) {
+    if (command !== 'setup' && command !== 'doctor' && command !== 'fix')
+        return null;
+    // `fix --list` is read-only and safe to run anywhere, including this repo.
+    if (command === 'fix' && opts.list)
+        return null;
+    if (!(await isSelfRepo(opts.directory ?? process.cwd())))
+        return null;
+    const allowSelf = env.REPO_TOOLING_ALLOW_SELF === '1';
+    if (allowSelf && command === 'doctor')
+        return null;
+    if (allowSelf && command === 'fix') {
+        if (!target) {
+            const safe = getFixers()
+                .filter((f) => f.selfSafe)
+                .map((f) => f.target);
+            return `a bare \`fix\` runs every fixer, including ones whose output imports @rtorcato/repo-tooling — name a self-safe target instead: ${safe.join(', ')}.`;
+        }
+        const fixer = getFixers().find((f) => f.target.toLowerCase() === target.toLowerCase());
+        if (fixer?.selfSafe)
+            return null;
+        return fixer
+            ? `\`fix ${target}\` is not self-safe: its output imports or depends on @rtorcato/repo-tooling, which this repo cannot depend on.`
+            : `\`fix ${target}\` is not a known self-safe target.`;
+    }
+    return 'setup and doctor are for consumer projects, not for the tooling repo.';
+}

package/dist/cli/utils/lockfile.js

@@ -160,6 +160,17 @@ export function lockfileSchema() {
                         additionalProperties: { type: 'string', minLength: 1 },
                         description: 'Declared exceptions: doctor check name → the reason this repo deliberately deviates. The reason is mandatory and non-empty — doctor shows the check as `declared` with it (never hidden) and stops failing the run for it. An entry naming a check doctor does not run is itself reported as drift.',
                     },
+                    brand: {
+                        type: 'object',
+                        additionalProperties: false,
+                        description: 'Inputs to `fix brand`, which scaffolds the banner and social-card SVGs.',
+                        properties: {
+                            tagline: {
+                                type: 'string',
+                                description: 'Short line for the banners and social card, used in place of the package.json description. Keep it to two lines of about 42 characters; `fix brand` warns when it is longer.',
+                            },
+                        },
+                    },
                 },
             },
         },

package/dist/languages/js/ci.js

@@ -78,6 +78,13 @@ export function scriptsOf(pkg) {
 function hasScript(opts, script) {
     return !opts.scripts || script in opts.scripts;
 }
+/**
+ * A bundler, or a known `build` script — a plain-`tsc` repo records `bundler:
+ * 'none'` (#661) but still has a build to run.
+ */
+function buildsSomething(config, opts) {
+    return config.bundler !== 'none' || (opts.scripts !== undefined && 'build' in opts.scripts);
+}
 /** Emit a step only when the script it runs exists (or we can't know yet). */
 function stepFor(opts, script, step) {
     return hasScript(opts, script) ? step : null;
@@ -95,7 +102,7 @@ function jobSteps(steps) {
 export function githubJobs(config, opts = {}) {
     const hasTypeScript = config.typescript.enabled;
     const hasTests = config.testing.framework !== 'none';
-    const hasBuild = config.bundler !== 'none';
+    const hasBuild = buildsSomething(config, opts);
     const isLibrary = config.projectType === 'library';
     const hasCoverage = usesCoverage(config);
     const jobs = [DEPENDENCIES_JOB];
@@ -230,7 +237,7 @@ export function gitlabSpec(config, opts = {}) {
     const hasTypeScript = config.typescript.enabled;
     const hasTests = config.testing.framework !== 'none';
     const hasLint = config.linting.tool !== 'none';
-    const hasBuild = config.bundler !== 'none';
+    const hasBuild = buildsSomething(config, opts);
     const test = gitlabTest(config);
     const jobs = [
         ...(hasLint && hasScript(opts, lintScript(config))

package/dist/languages/js/fixers.js

@@ -79,8 +79,33 @@ import { LOCKFILE_NAME, writeLockfile } from '../../cli/utils/lockfile.js';
 // The fixer contract moved to src/base/fixers.ts when Swift became the second
 // module (#286) — import it from there.
 import { FixerAbort } from '../../base/fixers.js';
+// The bundlers ProjectConfig can record, in the order a repo carrying more than
+// one is attributed to (a vite app that also pulls in esbuild is a vite app).
+const BUNDLERS = ['tsup', 'vite', 'rolldown', 'rollup', 'esbuild'];
+const BUNDLER_CONFIGS = {
+    tsup: [
+        'tsup.config.ts',
+        'tsup.config.mts',
+        'tsup.config.js',
+        'tsup.config.mjs',
+        'tsup.config.json',
+    ],
+    vite: ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs'],
+    rolldown: ['rolldown.config.ts', 'rolldown.config.mjs', 'rolldown.config.js'],
+    rollup: ['rollup.config.ts', 'rollup.config.mjs', 'rollup.config.js'],
+    esbuild: ['build.mjs'],
+};
+/**
+ * The bundler the repo actually uses, from its deps or (given `dir`) its config
+ * file — `none` when there is neither. Never a preset default: a plain-`tsc`
+ * repo used to be recorded as tsup (#661).
+ */
+function detectBundler(deps, dir) {
+    return (BUNDLERS.find((b) => b in deps ||
+        (dir !== undefined && BUNDLER_CONFIGS[b].some((f) => fs.existsSync(path.join(dir, f))))) ?? 'none');
+}
 /** Exported so doctor can render the preset ci.yml it compares against (#349). */
-export function inferProjectConfig(pkg) {
+export function inferProjectConfig(pkg, dir) {
     const deps = {
         ...(pkg?.dependencies ?? {}),
         ...(pkg?.devDependencies ?? {}),
@@ -92,6 +117,7 @@ export function inferProjectConfig(pkg) {
         projectType = 'react-app';
     return {
         projectName: pkg?.name ?? 'project',
+        language: 'js',
         projectType,
         typescript: {
             enabled: true,
@@ -109,7 +135,7 @@ export function inferProjectConfig(pkg) {
         commitLint: true,
         semanticRelease: pkg?.private !== true,
         securityAutomation: true,
-        bundler: 'tsup',
+        bundler: detectBundler(deps, dir),
     };
 }
 export async function readPackageJson(dir) {
@@ -520,6 +546,7 @@ export const FIXERS = [
     },
     {
         target: 'vscode-extensions',
+        selfSafe: true,
         description: 'Recommend the VS Code extensions matching the enabled tools (.vscode/extensions.json)',
         appliesTo: ['VS Code extensions'],
         outputs: ['.vscode/extensions.json'],
@@ -533,6 +560,7 @@ export const FIXERS = [
     },
     {
         target: 'nvmrc',
+        selfSafe: true,
         description: 'Scaffold .nvmrc pinned to Node 22',
         appliesTo: ['Node version pin'],
         outputs: ['.nvmrc'],
@@ -866,6 +894,7 @@ export const FIXERS = [
     },
     {
         target: 'lockfile',
+        selfSafe: true,
         description: `Scaffold ${LOCKFILE_NAME} recording current tool choices`,
         appliesTo: ['lockfile'],
         outputs: [LOCKFILE_NAME],
@@ -879,7 +908,9 @@ export const FIXERS = [
                 console.error(chalk.yellow('   no package.json found — skipping'));
                 return { filesWritten: [] };
             }
-            const config = lock ? lock.record.config : inferProjectConfig(pkg);
+            const config = lock
+                ? lock.record.config
+                : inferProjectConfig(pkg, targetDir);
             // Recorded hashes win: they capture the pristine content at copy time,
             // which a byte-match against today's shipped asset can only approximate.
             const assets = { ...(await identifiablePresetHashes(targetDir)), ...lock?.record.assets };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "4.0.0",
+	"version": "4.2.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [