@rtorcato/repo-tooling 4.1.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: [

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

@@ -86,9 +86,16 @@ async function ensureWorkspace(targetDir) {
     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';
@@ -100,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
@@ -215,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
@@ -246,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};
 }
 `;
 }
@@ -279,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',
@@ -297,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',
@@ -354,34 +357,6 @@ 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'
-
-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,
-  },
-})
-`;
-}
 // 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.
@@ -392,21 +367,6 @@ 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
  * returns the relative paths actually written, so `fix docs-site` is safe to
@@ -440,8 +400,6 @@ export async function generateDocsSite(pkg, targetDir, options = {}) {
         [`${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/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/languages/js/fixers.js

@@ -546,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'],
@@ -559,6 +560,7 @@ export const FIXERS = [
     },
     {
         target: 'nvmrc',
+        selfSafe: true,
         description: 'Scaffold .nvmrc pinned to Node 22',
         appliesTo: ['Node version pin'],
         outputs: ['.nvmrc'],
@@ -892,6 +894,7 @@ export const FIXERS = [
     },
     {
         target: 'lockfile',
+        selfSafe: true,
         description: `Scaffold ${LOCKFILE_NAME} recording current tool choices`,
         appliesTo: ['lockfile'],
         outputs: [LOCKFILE_NAME],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "4.1.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": [