@rtorcato/repo-tooling 4.3.1 → 4.5.0

package/AGENTS.md

@@ -92,7 +92,7 @@ npx @rtorcato/repo-tooling fix bun --yes --json         # Bun runtime/test confi
 
 `fix` defaults the confirm prompt to **No** for drift cases (existing file that doesn't extend our preset). The `--yes` flag is required to overwrite drift. Safe-merge fixers (`biome`, `engines`, `husky`, `package-json`) never overwrite — they add/merge — and use friendlier prompt wording. `fix --json` implies `--yes` (prompts would corrupt JSON output).
 
-Fixers marked `explicitOnly` are exempt from `fix` all *and* from `fix --yes` — they only run when named as the target. Today that is `release-environment` (changes what a merge does).
+Fixers marked `explicitOnly` are exempt from `fix` all *and* from `fix --yes` — they only run when named as the target. Today that is `release-environment` (changes what a merge does) and `npm-trusted-publisher` (registers an OIDC trusted publisher on npm via `npm trust github`; refuses when the package isn't on npm yet, local npm < 11.15.0, or not logged in).
 
 The same goes for every `optional-missing` finding: a bulk `fix` records it `skipped`, because optional tools are often mutually exclusive (Biome / ESLint / Prettier / Oxlint, semantic-release / Changesets / Release Please) and installing them all is never the intent (#630). Name the one you want — `fix editorconfig --yes`.
 

package/dist/base/checks.js

@@ -100,7 +100,7 @@ export async function checkCommunityHealth(dir) {
         hint: 'Run `npx @rtorcato/repo-tooling fix community-health` to scaffold them',
     };
 }
-const BRAND_HINT = 'Run `npx @rtorcato/repo-tooling fix brand` to scaffold brand/ (SVG sources + render.sh), then run `brand/render.sh`';
+const BRAND_HINT = 'Run `npx @rtorcato/repo-tooling fix brand` to scaffold brand/ (SVG sources + render.sh) and render the PNGs (needs librsvg)';
 /** The two banners the README consumes — the pair `brand/` exists to keep regenerable. */
 const BANNERS = ['banner', 'banner-mobile'];
 /**
@@ -380,6 +380,22 @@ export async function checkCodeQL(dir, languages) {
         hint: 'Run `npx @rtorcato/repo-tooling fix codeql` to scaffold CodeQL security scanning',
     };
 }
+/** The workflow file that uploads coverage via codecov-action, or null when none does. */
+export async function coverageUploadWorkflow(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    try {
+        const files = (await fs.readdir(workflowsDir)).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        for (const f of files) {
+            const content = await fs.readFile(path.join(workflowsDir, f), 'utf-8');
+            if (/codecov\/codecov-action/.test(content))
+                return f;
+        }
+    }
+    catch {
+        // no workflows dir
+    }
+    return null;
+}
 // A README that advertises a Codecov badge but a CI that never uploads coverage
 // leaves the badge permanently red. Only flags when the badge is actually present
 // (no badge → nothing to back, so it's not applicable).
@@ -393,24 +409,13 @@ export async function checkCoverageUpload(dir) {
             detail: 'no coverage badge in README (nothing to back)',
         };
     }
-    const workflowsDir = path.join(dir, '.github', 'workflows');
-    if (await fs.pathExists(workflowsDir)) {
-        try {
-            const files = (await fs.readdir(workflowsDir)).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
-            for (const f of files) {
-                const content = await fs.readFile(path.join(workflowsDir, f), 'utf-8');
-                if (/codecov\/codecov-action/.test(content)) {
-                    return {
-                        check: 'Coverage upload',
-                        status: 'ok',
-                        detail: `coverage badge backed by codecov-action in .github/workflows/${f}`,
-                    };
-                }
-            }
-        }
-        catch {
-            // fall through to drift
-        }
+    const workflow = await coverageUploadWorkflow(dir);
+    if (workflow) {
+        return {
+            check: 'Coverage upload',
+            status: 'ok',
+            detail: `coverage badge backed by codecov-action in .github/workflows/${workflow}`,
+        };
     }
     return {
         check: 'Coverage upload',

package/dist/base/fixers.js

@@ -15,7 +15,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import { installAgentRules, installAiSetup } from '../cli/generators/agent-rules.js';
-import { generateBrand } from '../cli/generators/brand.js';
+import { addReadmeBanner, generateBrand, renderBrand, resolveBrandMeta, } from '../cli/generators/brand.js';
 import { generateCommunityHealth } from '../cli/generators/community-health.js';
 import { generateCommitlintConfig } from '../cli/generators/git.js';
 import { generateCodeowners, generateEditorConfig } from '../cli/generators/misc.js';
@@ -164,12 +164,13 @@ export const BASE_FIXERS = [
     },
     {
         target: 'github-settings',
-        description: 'Apply branch protection + auto-merge + workflow permissions + code-scanning ruleset on GitHub via gh api (mutates the remote repo, not files)',
+        description: 'Apply branch protection + auto-merge + workflow permissions + Dependabot security updates + code-scanning ruleset on GitHub via gh api (mutates the remote repo, not files)',
         appliesTo: [
             'Branch protection',
             'Merge settings',
             'Workflow permissions',
             'Code-scanning gate',
+            'Security updates',
         ],
         outputs: ['GitHub repo settings (remote, via gh api)'],
         // safe-add is load-bearing: it exempts this fixer from the `--diff` shadow-run
@@ -249,24 +250,34 @@ 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',
+        description: 'Scaffold brand/ — favicon, banner, mobile-banner and social-card SVG sources + render.sh — render the PNGs and favicon.ico when rsvg-convert is on PATH, and add the README banner',
         appliesTo: ['Brand assets'],
         outputs: [
+            'brand/favicon.svg',
             'brand/banner.svg',
             'brand/banner-mobile.svg',
             'brand/social-card.svg',
             'brand/render.sh',
+            'brand/banner.png',
+            'brand/banner-mobile.png',
+            'brand/social-card.png',
+            'brand/favicon-512.png',
+            'brand/favicon.ico',
             'README.md',
         ],
-        // Every SVG is written only when absent and the README edit rewrites two
-        // image paths — hand-edited art is never clobbered.
+        // Every SVG is written only when absent, PNGs are re-rendered only when
+        // older than their source, and the README edit is a delimited block (or
+        // two image paths) — hand-edited art is never clobbered.
         riskLevel: 'safe-merge',
         canFixDrift: true,
         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`)'));
-            }
+            const tagline = lock?.rules?.brand?.tagline;
+            const filesWritten = await generateBrand(pkg, targetDir, tagline);
+            filesWritten.push(...((await renderBrand(targetDir)) ?? []));
+            const { name } = await resolveBrandMeta(pkg, targetDir, tagline);
+            const readme = await addReadmeBanner(targetDir, name);
+            if (readme && !filesWritten.includes(readme))
+                filesWritten.push(readme);
             return { filesWritten };
         },
     },

package/dist/base/github-settings.js

@@ -54,10 +54,12 @@ export const GITHUB_STANDARD = {
 const CODE_SCANNING_CHECK = 'Code-scanning gate';
 export const RELEASE_GATE_CHECK = 'Release gate';
 export const RELEASE_ENV_CHECK = 'Release environment';
+const SECURITY_UPDATES_CHECK = 'Security updates';
 const CHECK_NAMES = [
     'Branch protection',
     'Merge settings',
     'Workflow permissions',
+    SECURITY_UPDATES_CHECK,
     CODE_SCANNING_CHECK,
     RELEASE_GATE_CHECK,
     RELEASE_ENV_CHECK,
@@ -147,6 +149,7 @@ export async function checkGitHubSettings(dir, exec) {
         await checkBranchProtection(gh, info.nwo, info.branch),
         checkMergeSettings(info),
         await checkWorkflowPermissions(gh, info.nwo),
+        await checkSecurityUpdates(gh, info.nwo),
         await checkCodeScanningRuleset(gh, info.nwo, info.branch, dir),
         ...(await checkReleaseGate(gh, info.nwo, dir)),
     ];
@@ -277,6 +280,60 @@ async function checkWorkflowPermissions(exec, nwo) {
         };
     return { check, status: 'ok', detail: 'read-only default, no workflow PR approvals' };
 }
+/**
+ * Dependabot vulnerability alerts and automated security fixes (#692). A
+ * `dependabot.yml` only schedules version bumps; these two repo toggles are what
+ * surface and patch advisories, and both default off on a new repo. Neither
+ * endpoint has a body worth reading for alerts: 204 is on, 404 is off.
+ */
+async function readSecurityUpdates(exec, nwo) {
+    const enabled = async (endpoint) => {
+        const r = await exec(['api', `repos/${nwo}/${endpoint}`]);
+        if (!r.ok) {
+            if (/404|not found/i.test(r.stderr))
+                return false;
+            if (/403|forbidden/i.test(r.stderr))
+                return { skip: 'token lacks admin access' };
+            return { skip: `could not read ${endpoint}` };
+        }
+        if (endpoint === 'vulnerability-alerts')
+            return true;
+        try {
+            return JSON.parse(r.stdout).enabled === true;
+        }
+        catch {
+            return { skip: `could not parse ${endpoint} response` };
+        }
+    };
+    const alerts = await enabled('vulnerability-alerts');
+    if (typeof alerts !== 'boolean')
+        return alerts;
+    const fixes = await enabled('automated-security-fixes');
+    if (typeof fixes !== 'boolean')
+        return fixes;
+    return { alerts, fixes };
+}
+async function checkSecurityUpdates(exec, nwo) {
+    const check = SECURITY_UPDATES_CHECK;
+    const s = await readSecurityUpdates(exec, nwo);
+    if ('skip' in s)
+        return skip(check, s.skip);
+    const deltas = [];
+    if (!s.alerts)
+        deltas.push('vulnerability alerts disabled');
+    if (!s.fixes)
+        deltas.push('automated security fixes disabled');
+    // optional-missing, not drift: doctor promotes it when the lock records
+    // securityAutomation: true, and demotes it when the lock records false.
+    if (deltas.length)
+        return {
+            check,
+            status: 'optional-missing',
+            detail: deltas.join('; '),
+            hint: 'Run `npx @rtorcato/repo-tooling fix github-settings` to enable Dependabot alerts and security updates',
+        };
+    return { check, status: 'ok', detail: 'vulnerability alerts and automated security fixes on' };
+}
 /**
  * True when CodeQL/code-scanning is enabled for the repo. Covers both ways it
  * ships: an advanced-setup workflow on disk (what `fix codeql` scaffolds) or
@@ -764,6 +821,17 @@ export function buildGhApplyCommands(state) {
                 'can_approve_pull_request_reviews=false',
             ],
         });
+    // Alerts first: GitHub refuses security fixes on a repo with alerts off.
+    if (state.alerts)
+        commands.push({
+            label: 'vulnerability alerts',
+            args: ['api', '-X', 'PUT', `repos/${state.nwo}/vulnerability-alerts`],
+        });
+    if (state.securityFixes)
+        commands.push({
+            label: 'automated security fixes',
+            args: ['api', '-X', 'PUT', `repos/${state.nwo}/automated-security-fixes`],
+        });
     return commands;
 }
 /**
@@ -795,12 +863,15 @@ export async function applyGithubSettings(dir, exec) {
     // (no admin) reports `ok` → treated as "nothing to apply", never a failed PUT.
     const bp = await checkBranchProtection(gh, info.nwo, info.branch);
     const wp = await checkWorkflowPermissions(gh, info.nwo);
+    const sec = await readSecurityUpdates(gh, info.nwo);
     const commands = buildGhApplyCommands({
         nwo: info.nwo,
         branch: info.branch,
         merge: checkMergeSettings(info).status === 'drift',
         protection: bp.status === 'optional-missing' || bp.status === 'drift',
         workflow: wp.status === 'drift',
+        alerts: !('skip' in sec) && !sec.alerts,
+        securityFixes: !('skip' in sec) && !sec.fixes,
     });
     const applied = [];
     for (const cmd of commands) {

package/dist/cli/commands/doctor.js

@@ -4,6 +4,7 @@ import fs from 'fs-extra';
 import { renderGitHubWorkflow } from '../../base/ci.js';
 import { githubJobs, scriptsOf } from '../../languages/js/ci.js';
 import { inferProjectConfig } from '../../languages/js/fixers.js';
+import { checkNpmTrustedPublisher, checkPublishJob, findNpmPublishJob, NPM_OIDC_CHECK, } from '../../languages/js/npm-trust.js';
 import { PERL_GIT_HOOKS, runPerlChecks } from '../../languages/perl/checks.js';
 import { readPerlProject, renderPerlWorkflow } from '../../languages/perl/ci.js';
 import { PYTHON_GIT_HOOKS, runPythonChecks } from '../../languages/python/checks.js';
@@ -68,38 +69,19 @@ async function checkReleaseToken(dir) {
         };
     }
 }
-// Flags a release workflow still authenticating npm publish with a long-lived
-// NPM_TOKEN secret instead of OIDC trusted publishing (#201). npm is deprecating
-// 2FA-bypass tokens; OIDC needs no secret and adds provenance for free. Only
-// relevant for public packages that actually publish to npm.
+// OIDC trusted publishing (#201, #687): the publishing job must not use an
+// NPM_TOKEN secret, must carry `id-token: write`, and must run npm ≥ 11.5.1.
+// Only relevant for public packages that actually publish to npm.
 async function checkNpmOidcPublish(dir, pkg) {
-    const check = 'npm OIDC publish';
+    const check = NPM_OIDC_CHECK;
     if (!pkg || pkg.private === true) {
         return { check, status: 'optional-missing', detail: 'private package — no npm publish' };
     }
-    const workflowsDir = path.join(dir, '.github', 'workflows');
-    if (!(await fs.pathExists(workflowsDir))) {
-        return { check, status: 'optional-missing', detail: 'no .github/workflows/' };
-    }
     try {
-        const files = await fs.readdir(workflowsDir);
-        for (const f of files) {
-            if (!(f.endsWith('.yml') || f.endsWith('.yaml')))
-                continue;
-            const content = await fs.readFile(path.join(workflowsDir, f), 'utf-8');
-            if (!/semantic-release/.test(content))
-                continue;
-            if (/secrets\.NPM_TOKEN/.test(content)) {
-                return {
-                    check,
-                    status: 'drift',
-                    detail: `${f} authenticates npm publish with NPM_TOKEN`,
-                    hint: 'Migrate to OIDC trusted publishing: add a Trusted Publisher for each published package on npmjs.com (Settings → Trusted Publisher), then run `fix github-actions` to drop NPM_TOKEN (the release job keeps `id-token: write`). npm is deprecating 2FA-bypass tokens.',
-                };
-            }
-            return { check, status: 'ok', detail: `${f} publishes via OIDC (no NPM_TOKEN)` };
-        }
-        return { check, status: 'optional-missing', detail: 'no semantic-release workflow found' };
+        const job = await findNpmPublishJob(dir);
+        if (!job)
+            return { check, status: 'optional-missing', detail: 'no semantic-release workflow found' };
+        return checkPublishJob(job);
     }
     catch {
         return { check, status: 'optional-missing', detail: 'unable to read .github/workflows/' };
@@ -140,14 +122,26 @@ function checkLockfile(lock) {
         detail: `.repo-tooling.json v${lock.version} (record written by ${lock.record.writtenBy})`,
     };
 }
+// Checks whose absence `securityAutomation: true` turns from an optional gap
+// into drift (#692): the lock says the repo chose them, so silence is a lie.
+const REQUIRED_BY_SECURITY_AUTOMATION = new Set(['Dependabot', 'Security updates']);
 // Lockfile-driven demotion: if the lock records an intentional opt-out for a
 // check that's currently optional-missing, demote it to ok with a clear detail.
+// The converse holds for a recorded opt-in (#692): promote it to drift.
 function demoteDeclined(results, lock) {
     if (!lock)
         return results;
     return results.map((r) => {
         if (r.status !== 'optional-missing')
             return r;
+        if (lock.record.config.securityAutomation === true &&
+            REQUIRED_BY_SECURITY_AUTOMATION.has(r.check)) {
+            return {
+                ...r,
+                status: 'drift',
+                detail: `${r.detail}, but .repo-tooling.json records securityAutomation: true`,
+            };
+        }
         if (!declinedInLock(lock, r.check))
             return r;
         return {
@@ -365,6 +359,7 @@ export async function runDoctor(dir) {
     results.push(await checkSizeLimit(targetDir, pkg));
     results.push(await checkReleaseToken(targetDir));
     results.push(await checkNpmOidcPublish(targetDir, pkg));
+    results.push(await checkNpmTrustedPublisher(targetDir, pkg));
     results.push(await checkTypedoc(targetDir, pkg));
     results.push(await checkAreTheTypesWrong(targetDir, pkg));
     results.push(await checkPublint(targetDir, pkg));

package/dist/cli/commands/fix-targets.js

@@ -22,12 +22,15 @@ export const FIX_TARGETS = {
     'Tree-shake check': 'treeshake-check',
     'GitHub Actions': 'github-actions',
     'Coverage upload': 'github-actions',
+    'npm OIDC publish': 'github-actions',
+    'npm trusted publisher': 'npm-trusted-publisher',
     Dependabot: 'dependabot',
     CodeQL: 'codeql',
     'Branch protection': 'github-settings',
     'Merge settings': 'github-settings',
     'Workflow permissions': 'github-settings',
     'Code-scanning gate': 'github-settings',
+    'Security updates': 'github-settings',
     Milestones: 'milestones',
     CODEOWNERS: 'codeowners',
     'GitLab CI': 'gitlab-ci',
@@ -159,6 +162,7 @@ export function declinedInLock(lock, checkName) {
         case 'Merge settings':
         case 'Workflow permissions':
         case 'Code-scanning gate':
+        case 'Security updates':
             return c.securityAutomation === false;
         case 'publint':
             return c.publint === false;

package/dist/cli/commands/setup.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import inquirer from 'inquirer';
+import { formatNpmPublishGuide, npmPublishGuide, } from '../../languages/js/npm-trust.js';
 import { LANGUAGES } from '../../languages/registry.js';
 import { generateConfigs } from '../generators/index.js';
 import { detectLanguage } from '../utils/detect-language.js';
@@ -157,7 +158,8 @@ export async function setupProject(options) {
             return;
         if (dryRun) {
             const files = computeFileList(config);
-            console.log(JSON.stringify({ directory: targetDir, config, files }, null, 2));
+            const npmPublish = npmPublishFor(config);
+            console.log(JSON.stringify({ directory: targetDir, config, files, ...(npmPublish && { npmPublish }) }, null, 2));
             return;
         }
         if (!interactive) {
@@ -561,6 +563,23 @@ async function promptForConfig(targetDir, seed) {
         bun: answers.bun ?? false,
     };
 }
+/**
+ * The npmjs.com trusted-publisher values for a scaffold whose release job
+ * publishes (#687). Owner/repo aren't known yet at setup time, so they stay
+ * placeholders; `fix npm-trusted-publisher` derives them once the repo exists.
+ * The generated job declares no environment until `fix release-environment`.
+ */
+export function npmPublishFor(config) {
+    if (config.language === 'swift' || config.projectType !== 'library' || !config.semanticRelease)
+        return null;
+    return npmPublishGuide({
+        name: config.projectName,
+        owner: '<owner>',
+        repo: '<repo>',
+        file: 'ci.yml',
+        environment: null,
+    });
+}
 function showNextSteps(config, _targetDir) {
     console.log(chalk.bold('\n📋 Next Steps:\n'));
     const steps = [];
@@ -589,6 +608,13 @@ function showNextSteps(config, _targetDir) {
     steps.forEach((step, index) => {
         console.log(`  ${index + 1}. ${step}`);
     });
+    // A brand-new package isn't on npm yet, so the bootstrap order always applies.
+    const npmPublish = npmPublishFor(config);
+    if (npmPublish) {
+        console.log(chalk.bold('\n📦 Publish to npm (OIDC trusted publishing — no NPM_TOKEN):\n'));
+        for (const line of formatNpmPublishGuide(npmPublish, true))
+            console.log(`  ${line}`);
+    }
     const skipped = collectSkippedFixSuggestions(config);
     if (skipped.length > 0) {
         console.log(chalk.bold('\n💡 Want to add something you skipped?\n'));

package/dist/cli/generators/badges.js

@@ -31,7 +31,7 @@ export function parseRepository(repository) {
  * 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 { name, owner, repo, branch = 'main', isPrivate = false, bundled = true, uploadsCoverage = true, } = inputs;
     const slug = owner && repo ? `${owner}/${repo}` : null;
     const badges = [];
     let specific = false;
@@ -43,9 +43,11 @@ export function buildBadgeRow(inputs) {
         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})`);
+    }
+    if (!isPrivate && name && bundled) {
         badges.push(`[![Bundle size](https://img.shields.io/bundlephobia/minzip/${name})](https://bundlephobia.com/package/${name})`);
     }
-    if (!isPrivate && slug) {
+    if (!isPrivate && slug && uploadsCoverage) {
         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)');

package/dist/cli/generators/brand.js

@@ -12,6 +12,7 @@
  * and falls back to a neutral grey. Nothing about any particular org is baked
  * in; the templates are meant to be hand-edited afterwards.
  */
+import { execFileSync, spawnSync } from 'node:child_process';
 import path from 'node:path';
 import fs from 'fs-extra';
 /** Grey, so an unbranded repo reads as unbranded rather than borrowing a colour. */
@@ -80,10 +81,11 @@ async function accentFromDocsTheme(targetDir) {
         return dark[1];
     return css.match(/--ifm-color-primary:\s*(#[0-9a-fA-F]{6})/)?.[1] ?? null;
 }
+/** Where a repo already keeps a favicon — the docs site's first. */
+const EXISTING_FAVICONS = [path.join('apps', 'docs', 'static', 'img', 'favicon.svg'), 'favicon.svg'];
 /** Failing that, the favicon's own ink — the other place a repo commits its colour. */
 async function accentFromFavicon(targetDir) {
-    const candidates = [path.join('apps', 'docs', 'static', 'img', 'favicon.svg'), 'favicon.svg'];
-    for (const rel of candidates) {
+    for (const rel of EXISTING_FAVICONS) {
         const file = path.join(targetDir, rel);
         if (!(await fs.pathExists(file)))
             continue;
@@ -123,17 +125,23 @@ export async function resolveBrandMeta(pkg, targetDir, tagline) {
     };
 }
 /**
- * The logo mark: a rounded square in the accent carrying the project's initial.
- * Authored on a 32 viewBox so it matches the favicon's geometry and can be
- * swapped for the real favicon glyph verbatim.
+ * The logo tile: a rounded square in the accent carrying the project's
+ * initial. It *is* `brand/favicon.svg`, and every canvas below draws that file
+ * rather than a copy of it, so swapping in a real glyph is a one-file edit (#678).
  */
-function mark(meta, translate, scale) {
+export function faviconSvg(meta) {
     const initial = esc((meta.name[0] ?? '?').toUpperCase());
-    return `	<!-- Logo mark: a 32 viewBox, so the real favicon glyph can be pasted in over it. -->
-	<g transform="translate(${translate}) scale(${scale})">
-		<rect width="32" height="32" rx="8" fill="${meta.accent}"/>
-		<text x="16" y="23" text-anchor="middle" font-family="Avenir Next" font-weight="800" font-size="19" fill="${INK}">${initial}</text>
-	</g>`;
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
+	<title>${esc(meta.name)}</title>
+	<rect width="32" height="32" rx="8" fill="${meta.accent}"/>
+	<text x="16" y="23" text-anchor="middle" font-family="Avenir Next" font-weight="800" font-size="19" fill="${INK}">${initial}</text>
+</svg>
+`;
+}
+/** The logo mark: `brand/favicon.svg`, drawn `size` px square. */
+function mark(x, y, size) {
+    return `	<!-- Logo mark: brand/favicon.svg — edit that file to change it on every canvas. -->
+	<image href="favicon.svg" x="${x}" y="${y}" width="${size}" height="${size}"/>`;
 }
 /** `repo-tooling` renders as a muted `repo-` and an accented `tooling`. */
 function wordmark(meta) {
@@ -188,7 +196,7 @@ function canvas(meta, w, h, glow) {
 /** 1280×320 README banner — left-aligned lockup, install pill on the right. */
 export function bannerSvg(meta) {
     return `${canvas(meta, 1280, 320, { cx: 0.16, cy: 0 })}
-${mark(meta, '60 88', 2.25)}
+${mark(60, 88, 72)}
 
 	<text x="156" y="150" font-family="Avenir Next" font-weight="800" font-size="62" letter-spacing="-1.5">${wordmark(meta)}</text>
 
@@ -200,7 +208,7 @@ ${installPanel(meta, { x: 845, y: 118, w: 378, h: 84, size: 20 })}
 /** 1280×786 mobile banner — the same content stacked so it stays legible on a phone. */
 export function bannerMobileSvg(meta) {
     return `${canvas(meta, 1280, 786, { cx: 0.12, cy: 0.05 })}
-${mark(meta, '565 104', 4.6875)}
+${mark(565, 104, 150)}
 
 	<text x="640" y="360" text-anchor="middle" font-family="Avenir Next" font-weight="800" font-size="76" letter-spacing="-1.8">${wordmark(meta)}</text>
 
@@ -212,7 +220,7 @@ ${installPanel(meta, { x: 427, y: 650, w: 426, h: 78, size: 24 })}
 /** 1280×640 Open Graph / GitHub social card. Keep content inside an ~8% safe inset. */
 export function socialCardSvg(meta) {
     return `${canvas(meta, 1280, 640, { cx: 0.1, cy: 0.05 })}
-${mark(meta, '590 120', 3.125)}
+${mark(590, 120, 100)}
 
 	<text x="640" y="300" text-anchor="middle" font-family="Avenir Next" font-weight="800" font-size="76" letter-spacing="-1.8">${wordmark(meta)}</text>
 
@@ -229,7 +237,7 @@ ${installPanel(meta, { x: 427, y: 470, w: 426, h: 78, size: 24 })}
 export const RENDER_SH = `#!/usr/bin/env bash
 # Render the committed brand PNGs from their SVG sources.
 # Sizes come from the brand-asset spec: 1280x320 banner, 1280x786 mobile,
-# 1280x640 social card, 512x512 PWA icon.
+# 1280x640 social card, 512x512 PWA icon. (\`fix brand\` also packs favicon.ico.)
 set -euo pipefail
 cd "$(dirname "$0")/.."
 
@@ -241,7 +249,9 @@ fi
 
 rsvg-convert -w 1280 -h 320 brand/banner.svg        -o brand/banner.png
 rsvg-convert -w 1280 -h 786 brand/banner-mobile.svg -o brand/banner-mobile.png
-echo "rendered: brand/banner.png brand/banner-mobile.png"
+rsvg-convert -w 1280 -h 640 brand/social-card.svg   -o brand/social-card.png
+rsvg-convert -w 512  -h 512 brand/favicon.svg       -o brand/favicon-512.png
+echo "rendered: brand/banner.png brand/banner-mobile.png brand/social-card.png brand/favicon-512.png"
 
 # The docs-site assets, rendered only when the site exists to hold them.
 img=apps/docs/static/img
@@ -279,15 +289,25 @@ export async function repointReadmeBanners(targetDir) {
     await fs.writeFile(file, next);
     return 'README.md';
 }
+/** A favicon the repo already commits beats the generated initial tile. */
+async function existingFavicon(targetDir) {
+    for (const rel of EXISTING_FAVICONS) {
+        const file = path.join(targetDir, rel);
+        if (await fs.pathExists(file))
+            return fs.readFile(file, 'utf-8');
+    }
+    return null;
+}
 /**
- * Scaffold `brand/`: three SVG sources + the render script, then repoint a
- * README still on the old root-level paths. Every file is written only when
- * absent, so `fix brand` is idempotent.
+ * Scaffold `brand/`: the favicon tile, three SVG sources that draw it, and the
+ * render script, then repoint a 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, tagline) {
     const meta = await resolveBrandMeta(pkg, targetDir, tagline);
     const written = [];
     const files = [
+        ['brand/favicon.svg', (await existingFavicon(targetDir)) ?? faviconSvg(meta)],
         ['brand/banner.svg', bannerSvg(meta)],
         ['brand/banner-mobile.svg', bannerMobileSvg(meta)],
         ['brand/social-card.svg', socialCardSvg(meta)],
@@ -307,3 +327,118 @@ export async function generateBrand(pkg, targetDir, tagline) {
         written.push(readme);
     return written;
 }
+/** Printed when `rsvg-convert` is not on PATH — the sources are still written. */
+export const RSVG_HINT = '   next: install librsvg to render the brand PNGs (`brew install librsvg`, apt: `apt-get install librsvg2-bin`), then re-run `fix brand` or `brand/render.sh`';
+/** `[source, output, width, height]` under `brand/` — the same set render.sh draws. */
+const RENDERS = [
+    ['banner.svg', 'banner.png', 1280, 320],
+    ['banner-mobile.svg', 'banner-mobile.png', 1280, 786],
+    ['social-card.svg', 'social-card.png', 1280, 640],
+    ['favicon.svg', 'favicon-512.png', 512, 512],
+    ['favicon.svg', 'favicon.ico', 32, 32],
+];
+/** Classic favicon sizes packed into favicon.ico. */
+const ICO_SIZES = [16, 32];
+/**
+ * An ICO container holding PNG frames — every browser since IE Vista reads
+ * PNG-in-ICO, so no bitmap conversion is needed.
+ */
+export function packIco(frames) {
+    const header = Buffer.alloc(6 + 16 * frames.length);
+    header.writeUInt16LE(1, 2); // type: icon
+    header.writeUInt16LE(frames.length, 4);
+    let offset = header.length;
+    frames.forEach(([size, png], i) => {
+        const e = 6 + 16 * i;
+        header.writeUInt8(size % 256, e); // 0 means 256
+        header.writeUInt8(size % 256, e + 1);
+        header.writeUInt16LE(1, e + 4); // colour planes
+        header.writeUInt16LE(32, e + 6); // bits per pixel
+        header.writeUInt32LE(png.length, e + 8);
+        header.writeUInt32LE(offset, e + 12);
+        offset += png.length;
+    });
+    return Buffer.concat([header, ...frames.map(([, png]) => png)]);
+}
+async function mtime(file) {
+    return (await fs.stat(file)).mtimeMs;
+}
+/**
+ * Render every `brand/` PNG (and favicon.ico) that is missing or older than its
+ * source — or than favicon.svg, which every canvas draws. Returns the files
+ * written, or null when `rsvg-convert` is not on PATH (after printing
+ * {@link RSVG_HINT}). Nothing stale means nothing to do and no PATH lookup.
+ */
+export async function renderBrand(targetDir) {
+    const brand = path.join(targetDir, 'brand');
+    const favicon = path.join(brand, 'favicon.svg');
+    const stale = [];
+    for (const job of RENDERS) {
+        const [src, out] = job;
+        const srcFile = path.join(brand, src);
+        const outFile = path.join(brand, out);
+        if (!(await fs.pathExists(srcFile)))
+            continue;
+        const newest = Math.max(await mtime(srcFile), (await fs.pathExists(favicon)) ? await mtime(favicon) : 0);
+        if (!(await fs.pathExists(outFile)) || (await mtime(outFile)) < newest)
+            stale.push(job);
+    }
+    if (stale.length === 0)
+        return [];
+    if (spawnSync('rsvg-convert', ['--version']).error) {
+        // stderr, not stdout: `fix --json` owns stdout (#357).
+        console.error(RSVG_HINT);
+        return null;
+    }
+    // cwd = brand/ so each canvas's `href="favicon.svg"` resolves beside it.
+    const rsvg = (src, w, h) => execFileSync('rsvg-convert', ['-w', String(w), '-h', String(h), src], { cwd: brand });
+    const written = [];
+    for (const [src, out, w, h] of stale) {
+        const png = out.endsWith('.ico')
+            ? packIco(ICO_SIZES.map((s) => [s, rsvg(src, s, s)]))
+            : rsvg(src, w, h);
+        await fs.writeFile(path.join(brand, out), png);
+        written.push(`brand/${out}`);
+    }
+    return written;
+}
+export const BANNER_START = '<!-- js-tooling:banner:start -->';
+export const BANNER_END = '<!-- js-tooling:banner:end -->';
+/** The README `<picture>` banner, mobile variant under 640px, as a delimited block. */
+export function buildBannerBlock(name) {
+    return `${BANNER_START}
+<picture>
+  <source media="(max-width: 640px)" srcset="./brand/banner-mobile.png">
+  <img src="./brand/banner.png" alt="${esc(name)} banner" width="1600">
+</picture>
+${BANNER_END}`;
+}
+/**
+ * Put the banner block at the top of a README. Refreshes an existing block in
+ * place; leaves alone a README that already shows a banner outside one (a
+ * hand-written `<picture>`); otherwise prepends. Idempotent.
+ */
+export function upsertBanner(readme, block) {
+    const start = readme.indexOf(BANNER_START);
+    const end = readme.indexOf(BANNER_END);
+    if (start !== -1 && end > start) {
+        return readme.slice(0, start) + block + readme.slice(end + BANNER_END.length);
+    }
+    if (/banner(?:-mobile)?\.png/.test(readme))
+        return readme;
+    return `${block}\n\n${readme}`;
+}
+/** Add the banner block to README.md once `brand/banner.png` exists to show. */
+export async function addReadmeBanner(targetDir, name) {
+    const file = path.join(targetDir, 'README.md');
+    if (!(await fs.pathExists(file)))
+        return null;
+    if (!(await fs.pathExists(path.join(targetDir, 'brand', 'banner.png'))))
+        return null;
+    const readme = await fs.readFile(file, 'utf-8');
+    const next = upsertBanner(readme, buildBannerBlock(name));
+    if (next === readme)
+        return null;
+    await fs.writeFile(file, next);
+    return 'README.md';
+}

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

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import selfPackageJson from '../../../package.json' with { type: 'json' };
+import { coverageUploadWorkflow } from '../../base/checks.js';
+import { jsBadgeAudience } from '../../languages/js/checks.js';
 import { copyPreset, PRESETS } from '../utils/copy-preset.js';
 import { buildBadgeRow, parseRepository } from './badges.js';
 import { DOCS_SITE_BUILDS, mergeAllowBuilds } from './pnpm-workspace.js';
@@ -385,11 +387,15 @@ export async function generateDocsSite(pkg, targetDir, options = {}) {
     // The docs homepage carries the same badge set as the README (#169), derived
     // from package.json + repo; visibility-aware (private repos drop npm/coverage).
     // Plain row (no upsert delimiters) to stay MDX-safe in the generated intro.
+    // Bundlephobia only for a published library, Codecov only when CI uploads
+    // coverage — the same rules doctor's badge/coverage checks use (#675).
     const badges = buildBadgeRow({
         name: pkg?.name,
         owner: meta.owner ?? undefined,
         repo: meta.repo ?? undefined,
         isPrivate: pkg?.private === true,
+        bundled: jsBadgeAudience(pkg) === 'public',
+        uploadsCoverage: (await coverageUploadWorkflow(targetDir)) !== null,
     });
     // Opt-in TypeDoc API section (#229): only wire it when enabled AND the
     // package actually exposes source modules to document.

package/dist/languages/js/ci.js

@@ -212,6 +212,12 @@ ${attw}${publint}
           git config --global user.name "github-actions[bot]"
           git config --global user.email "github-actions[bot]@users.noreply.github.com"
 
+      # OIDC trusted publishing needs npm >= 11.5.1; Node 22 bundles npm 10, whose
+      # \`npm publish\` fails with ENEEDAUTH. Pinned to a range, not \`latest\`, so a
+      # future npm major can't change publishing unannounced.
+      - name: 📦 Upgrade npm for OIDC trusted publishing
+        run: npm install -g npm@^11.5.1
+
       - name: 🚀 Run semantic-release
         # Publishes to npm via OIDC trusted publishing — no NPM_TOKEN. Requires
         # the \`id-token: write\` permission above + a trusted publisher configured

package/dist/languages/js/fixers.js

@@ -10,6 +10,7 @@ import { GH_WORKFLOWS, generateGhWorkflow } from '../../cli/generators/github-wo
 import { BIOME_CONFIG, generateBiomeConfig, generateESLintConfig, generatePrettierConfig, } from '../../cli/generators/linting.js';
 import { alignNodeVersion, ensureEnginesNode, ensurePackageManager, generateKnipConfig, generateNvmrc, generateSizeLimitConfig, generateVscodeExtensions, } from '../../cli/generators/misc.js';
 import { scriptsOf } from './ci.js';
+import { NPM_OIDC_CHECK, NPM_TRUST_FIXER } from './npm-trust.js';
 import { usesPnpm } from './checks.js';
 import { SIZE_LIMIT_SCRIPTS, SIZE_LIMIT_VERSION, composeVerifyScriptFromPkg, ensureScripts, } from '../../cli/generators/package-json.js';
 /** Kept in step with the biome branch of getScripts() in package-json.ts. */
@@ -438,7 +439,7 @@ export const FIXERS = [
     {
         target: 'github-actions',
         description: 'Scaffold .github/workflows/ci.yml (+ codecov.yml when tests run)',
-        appliesTo: ['GitHub Actions', 'Coverage upload', 'npm OIDC publish'],
+        appliesTo: ['GitHub Actions', 'Coverage upload', NPM_OIDC_CHECK],
         outputs: [CI_WORKFLOW, 'codecov.yml', 'package.json (packageManager field)'],
         canFixDrift: true,
         async run({ targetDir, pkg, result }) {
@@ -462,6 +463,7 @@ export const FIXERS = [
             return { filesWritten };
         },
     },
+    NPM_TRUST_FIXER,
     {
         target: 'gitlab-ci',
         description: 'Scaffold .gitlab-ci.yml (lint/typecheck/test/build mirrored from GitHub Actions)',

package/dist/languages/js/npm-trust.js

@@ -0,0 +1,351 @@
+/**
+ * npm OIDC trusted publishing (#687): what the publishing job needs, whether the
+ * registry has a trusted publisher wired to it, and the fixer that registers one.
+ *
+ * Everything that talks to npm goes through `NpmExec`, the same resolve-never-
+ * reject seam as `GhExec`, so tests never touch the registry and a network or
+ * auth failure degrades to "couldn't check" rather than a failed doctor run.
+ */
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import inquirer from 'inquirer';
+import { FixerAbort } from '../../base/fixers.js';
+import { jobEnvironment, workflowJobs } from '../../base/github-settings.js';
+import { parseRepository } from '../../cli/generators/badges.js';
+const NPM_TIMEOUT_MS = 15_000;
+/** Real `npm` runner — never rejects. Args are derived, never free text, and execFile runs no shell. */
+export const realNpmExec = (args) => new Promise((resolve) => {
+    execFile('npm', args, { timeout: NPM_TIMEOUT_MS }, (err, stdout, stderr) => {
+        const code = err ? (typeof err.code === 'number' ? err.code : null) : 0;
+        resolve({ ok: !err, stdout: String(stdout), stderr: String(stderr), code });
+    });
+});
+export const NPM_OIDC_CHECK = 'npm OIDC publish';
+export const NPM_TRUST_CHECK = 'npm trusted publisher';
+export const NPM_TRUST_FIX = 'npm-trusted-publisher';
+/** OIDC publish needs npm ≥ 11.5.1 — Node 22 bundles npm 10. */
+export const NPM_OIDC_MIN = '11.5.1';
+/** `npm trust` landed in npm 11.15.0. */
+export const NPM_TRUST_MIN = '11.15.0';
+export const NPM_UPGRADE_CMD = `npm install -g npm@^${NPM_OIDC_MIN}`;
+const NPM_UPGRADE = /\bnpm\s+(?:install|i)\s+(?:-g|--global)\s+npm@/;
+const PUBLISHES = /semantic-release|\bnpm\s+publish\b/;
+/** a ≥ b for dotted numeric versions (prerelease tags ignored). */
+export function versionAtLeast(a, b) {
+    const pa = a.trim().split(/[.-]/).map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (Number.isNaN(x))
+            return false;
+        if (x !== y)
+            return x > y;
+    }
+    return true;
+}
+const uncommented = (s) => s
+    .split('\n')
+    .filter((l) => !l.trimStart().startsWith('#'))
+    .join('\n');
+/** The first workflow job that publishes to npm, or null. Throws when the directory can't be read. */
+export async function findNpmPublishJob(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir)))
+        return null;
+    for (const file of (await fs.readdir(workflowsDir)).sort()) {
+        if (!/\.ya?ml$/.test(file))
+            continue;
+        const content = await fs.readFile(path.join(workflowsDir, file), 'utf-8');
+        if (!PUBLISHES.test(uncommented(content)))
+            continue;
+        const jobs = [...workflowJobs(content).values()].map(uncommented);
+        const body = jobs.find((b) => PUBLISHES.test(b)) ?? uncommented(content);
+        return { file, body, content, environment: jobEnvironment(body) };
+    }
+    return null;
+}
+/**
+ * What the publishing job itself needs for OIDC: no NPM_TOKEN, `id-token: write`,
+ * and an npm new enough to use the token.
+ */
+export function checkPublishJob(job) {
+    const check = NPM_OIDC_CHECK;
+    const f = job.file;
+    if (/secrets\.NPM_TOKEN/.test(job.content)) {
+        return {
+            check,
+            status: 'drift',
+            detail: `${f} authenticates npm publish with NPM_TOKEN`,
+            hint: 'Migrate to OIDC trusted publishing: add a Trusted Publisher for each published package on npmjs.com (Settings → Trusted Publisher), then run `fix github-actions` to drop NPM_TOKEN (the release job keeps `id-token: write`). npm is deprecating 2FA-bypass tokens.',
+        };
+    }
+    // The grant may sit on the job or at workflow level (everything before `jobs:`).
+    const workflowLevel = uncommented(job.content.split(/^jobs:/m)[0] ?? '');
+    if (!/id-token:\s*write/.test(job.body) && !/id-token:\s*write/.test(workflowLevel)) {
+        return {
+            check,
+            status: 'drift',
+            detail: `${f}: the publishing job lacks \`id-token: write\` — npm can't mint an OIDC token`,
+            hint: 'Add `permissions: { id-token: write }` to the publishing job (or run `fix github-actions`)',
+        };
+    }
+    if (!NPM_UPGRADE.test(job.body)) {
+        return {
+            check,
+            status: 'drift',
+            detail: `${f}: the publishing job runs the npm bundled with Node — OIDC publish needs npm ≥ ${NPM_OIDC_MIN} and fails with ENEEDAUTH below it`,
+            hint: `add \`${NPM_UPGRADE_CMD}\` before semantic-release`,
+        };
+    }
+    return { check, status: 'ok', detail: `${f} publishes via OIDC (no NPM_TOKEN)` };
+}
+export function npmPublishGuide(opts) {
+    const env = opts.environment ? ` --env ${opts.environment}` : '';
+    return {
+        package: opts.name,
+        where: 'npmjs.com → package → Settings → Trusted Publisher → GitHub Actions',
+        organizationOrUser: opts.owner,
+        repository: opts.repo,
+        workflowFilename: opts.file,
+        environment: opts.environment,
+        command: `npm trust github ${opts.name} --file ${opts.file} --repo ${opts.owner}/${opts.repo}${env} --allow-publish`,
+        bootstrap: [
+            "Publish one version BELOW semantic-release's next one by hand: `npm publish --access public --provenance=false --otp=<code>`",
+            `Register the trusted publisher: \`npx @rtorcato/repo-tooling fix ${NPM_TRUST_FIX}\` (or on npmjs.com)`,
+            'Let CI take over — every later release publishes via OIDC',
+        ],
+    };
+}
+/** The guide as text lines, for Next Steps and doctor hints. Never mentions an NPM_TOKEN secret. */
+export function formatNpmPublishGuide(g, unpublished) {
+    const lines = [
+        `On ${g.where}:`,
+        `  Organization or user: ${g.organizationOrUser}`,
+        `  Repository: ${g.repository}`,
+        `  Workflow filename: ${g.workflowFilename}`,
+    ];
+    if (g.environment)
+        lines.push(`  Environment: ${g.environment}`);
+    lines.push(`Or from a logged-in npm ≥ ${NPM_TRUST_MIN}: ${g.command}`);
+    if (unpublished) {
+        lines.push(`${g.package} isn't on npm yet — npm only accepts a trusted publisher for an existing package:`);
+        for (const [i, s] of g.bootstrap.entries())
+            lines.push(`  ${i + 1}. ${s}`);
+    }
+    return lines;
+}
+/** A trusted-publisher entry's string leaves, lowercased — npm's JSON shape is matched loosely. */
+function stringsOf(v, out = []) {
+    if (typeof v === 'string')
+        out.push(v.toLowerCase());
+    else if (Array.isArray(v))
+        for (const x of v)
+            stringsOf(x, out);
+    else if (v && typeof v === 'object')
+        for (const x of Object.values(v))
+            stringsOf(x, out);
+    return out;
+}
+/** `npm trust list --json` → its entries, whether npm wraps them or not. */
+function trustEntries(json) {
+    if (Array.isArray(json))
+        return json;
+    if (json && typeof json === 'object') {
+        const arr = Object.values(json).find(Array.isArray);
+        if (arr)
+            return arr;
+        return Object.keys(json).length > 0 ? [json] : [];
+    }
+    return [];
+}
+/**
+ * Compare `npm trust list` entries against the publishing job. Returns null on a
+ * match, else why nothing matches.
+ * ponytail: matches on string leaves rather than a fixed schema — npm's JSON
+ * shape isn't pinned in its docs; tighten once it is.
+ */
+export function trustMismatch(entries, want) {
+    if (entries.length === 0)
+        return 'no trusted publisher is registered';
+    const nwo = want.nwo.toLowerCase();
+    const file = want.file.toLowerCase();
+    const env = want.environment?.toLowerCase() ?? null;
+    const leaves = entries.map((e) => stringsOf(e));
+    const forRepo = leaves.filter((s) => s.some((x) => x === nwo || x.endsWith(`/${nwo}`)));
+    if (forRepo.length === 0)
+        return `no trusted publisher for ${want.nwo}`;
+    const forFile = forRepo.filter((s) => s.some((x) => x === file || x.endsWith(`/${file}`) || x.includes(`/${file}@`)));
+    if (forFile.length === 0)
+        return `the trusted publisher for ${want.nwo} names a different workflow (want ${want.file})`;
+    if (env && !forFile.some((s) => s.includes(env))) {
+        return `the trusted publisher for ${want.nwo} has no \`${want.environment}\` environment, but the job declares one`;
+    }
+    return null;
+}
+const NPM_NAME = /^(@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/;
+const ENV_NAME = /^[\w.-]+$/;
+/** What the check and the fixer both need, or why it can't be had. Network only past the offline gates. */
+async function trustContext(dir, pkg, npm, opts) {
+    if (!pkg || pkg.private === true)
+        return { skip: 'private package — no npm publish' };
+    const name = typeof pkg.name === 'string' ? pkg.name : null;
+    if (!name)
+        return { skip: 'package.json has no name' };
+    // Untrusted (audited repo's package.json): reject anything npm could parse as a flag.
+    if (!NPM_NAME.test(name))
+        return { skip: 'package.json `name` is not a valid npm package name' };
+    let job;
+    try {
+        job = await findNpmPublishJob(dir);
+    }
+    catch {
+        return { skip: 'unable to read .github/workflows/' };
+    }
+    if (!job)
+        return { skip: 'no workflow publishes to npm' };
+    if (job.environment && !ENV_NAME.test(job.environment)) {
+        return { skip: 'the publish job declares an environment with unsupported characters' };
+    }
+    const repo = parseRepository(pkg.repository);
+    if (!repo)
+        return { skip: 'package.json `repository` names no GitHub repo' };
+    const nwo = `${repo.owner}/${repo.repo}`;
+    const guide = npmPublishGuide({ name, ...repo, file: job.file, environment: job.environment });
+    const view = await npm(['view', '--', name, 'version']);
+    if (!view.ok) {
+        if (/E404|404 Not Found/i.test(view.stderr)) {
+            return { skip: `${name} is not on npm yet`, unpublished: true, guide };
+        }
+        return { skip: 'could not reach the npm registry', guide };
+    }
+    if (opts.needLogin && process.env.CI)
+        return { skip: 'running in CI — no npm login', guide };
+    const ver = await npm(['--version']);
+    if (!ver.ok || !versionAtLeast(ver.stdout, NPM_TRUST_MIN)) {
+        return {
+            skip: `local npm ${ver.stdout.trim() || '?'} is older than ${NPM_TRUST_MIN} (\`npm install -g npm@^${NPM_TRUST_MIN}\`)`,
+            guide,
+        };
+    }
+    const who = await npm(['whoami']);
+    if (!who.ok)
+        return { skip: 'not logged in to npm (`npm login`)', guide };
+    return { guide, nwo, job };
+}
+/**
+ * Is a trusted publisher registered on npm, matching the publishing job? Every
+ * "couldn't check" is `optional-missing` with the manual steps — never a failure.
+ */
+export async function checkNpmTrustedPublisher(dir, pkg, npm = realNpmExec) {
+    const check = NPM_TRUST_CHECK;
+    const ctx = await trustContext(dir, pkg, npm, { needLogin: true });
+    if ('skip' in ctx) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: ctx.skip,
+            ...(ctx.guide && {
+                hint: formatNpmPublishGuide(ctx.guide, ctx.unpublished === true).join('\n'),
+            }),
+        };
+    }
+    const list = await npm(['trust', 'list', '--json', '--', ctx.guide.package]);
+    let entries = null;
+    if (list.ok) {
+        try {
+            entries = trustEntries(JSON.parse(list.stdout || '[]'));
+        }
+        catch {
+            entries = null;
+        }
+    }
+    if (!entries) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: 'could not read `npm trust list`',
+            hint: formatNpmPublishGuide(ctx.guide, false).join('\n'),
+        };
+    }
+    const why = trustMismatch(entries, {
+        nwo: ctx.nwo,
+        file: ctx.job.file,
+        environment: ctx.job.environment,
+    });
+    if (why) {
+        return {
+            check,
+            status: 'drift',
+            detail: `${ctx.guide.package}: ${why}`,
+            hint: `Run \`npx @rtorcato/repo-tooling fix ${NPM_TRUST_FIX}\`, or: ${ctx.guide.command}`,
+        };
+    }
+    return {
+        check,
+        status: 'ok',
+        detail: `${ctx.guide.package} trusts ${ctx.nwo} ${ctx.job.file}${ctx.job.environment ? ` (${ctx.job.environment})` : ''}`,
+    };
+}
+/**
+ * Register the trusted publisher with `npm trust github`, flags derived from the
+ * publishing job. Dry-runs first and asks before the real call.
+ */
+export async function applyNpmTrustedPublisher(dir, pkg, assumeYes, npm = realNpmExec) {
+    const ctx = await trustContext(dir, pkg, npm, { needLogin: true });
+    if ('skip' in ctx) {
+        const hint = ctx.unpublished && ctx.guide ? ctx.guide.bootstrap.join(' → ') : undefined;
+        throw new FixerAbort('npm-trust-unavailable', ctx.skip, hint);
+    }
+    const args = [
+        'trust',
+        'github',
+        '--file',
+        ctx.job.file,
+        '--repo',
+        ctx.nwo,
+        ...(ctx.job.environment ? ['--env', ctx.job.environment] : []),
+        '--allow-publish',
+    ];
+    // `--` last so the name can never be read as a flag.
+    const tail = ['--', ctx.guide.package];
+    const dry = await npm([...args, '--dry-run', ...tail]);
+    if (!dry.ok) {
+        throw new FixerAbort('npm-trust-failed', `npm trust --dry-run failed: ${dry.stderr.trim()}`);
+    }
+    console.error(chalk.gray(dry.stdout.trim()));
+    if (!assumeYes) {
+        if (!process.stdin.isTTY)
+            return [];
+        const { confirm } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'confirm',
+                message: 'Register this trusted publisher on npm?',
+                default: false,
+            },
+        ]);
+        if (confirm !== true)
+            return [];
+    }
+    const real = await npm([...args, '--yes', ...tail]);
+    if (!real.ok)
+        throw new FixerAbort('npm-trust-failed', `npm trust failed: ${real.stderr.trim()}`);
+    return [`npm trusted publisher for ${ctx.guide.package} (remote, via npm trust)`];
+}
+export const NPM_TRUST_FIXER = {
+    target: NPM_TRUST_FIX,
+    description: 'Register the npm trusted publisher (OIDC) for this package with `npm trust github`, derived from the publishing job (#687)',
+    appliesTo: [NPM_TRUST_CHECK],
+    outputs: ['npm trusted publisher (remote, via npm trust)'],
+    // safe-add keeps `--diff` from shadow-running it (that would call npm for real);
+    // explicitOnly because it changes registry state, like release-environment.
+    riskLevel: 'safe-add',
+    explicitOnly: true,
+    canFixDrift: true,
+    async run({ targetDir, pkg, assumeYes }) {
+        return { filesWritten: await applyNpmTrustedPublisher(targetDir, pkg, assumeYes) };
+    },
+};

package/package.json

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