@rtorcato/repo-tooling 4.4.0 → 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

@@ -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/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/' };
@@ -377,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,6 +22,8 @@ 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',

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/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.4.0",
+	"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": [