@rtorcato/repo-tooling 3.2.4 → 3.3.0

package/dist/base/github-settings.js

@@ -0,0 +1,461 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+const GH_TIMEOUT_MS = 10_000;
+/**
+ * Real `gh` runner — never rejects; a missing/failing gh resolves ok:false.
+ * `cwd` scopes gh's repo resolution to the target dir so `-d/--directory` is
+ * honored (gh otherwise resolves the remote from process.cwd()). Not annotated
+ * `: GhExec` so the optional cwd stays callable; still assignable where GhExec
+ * is expected.
+ */
+export const realGhExec = (args, stdin, cwd) => new Promise((resolve) => {
+    let settled = false;
+    const done = (r) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(r);
+    };
+    // gh args are internal/derived from gh itself (never user free-text), so
+    // shell:false + an args array keeps this injection-safe.
+    const child = spawn('gh', args, {
+        cwd,
+        stdio: [stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+        child.kill();
+        done({ ok: false, stdout: '', stderr: 'gh timed out', code: null });
+    }, GH_TIMEOUT_MS);
+    child.stdout?.on('data', (d) => {
+        stdout += d;
+    });
+    child.stderr?.on('data', (d) => {
+        stderr += d;
+    });
+    child.on('close', (code) => done({ ok: code === 0, stdout, stderr, code }));
+    child.on('error', (err) => done({ ok: false, stdout: '', stderr: String(err), code: null }));
+    if (stdin !== undefined && child.stdin) {
+        child.stdin.write(stdin);
+        child.stdin.end();
+    }
+});
+/** The standard doctor checks these settings against. */
+export const GITHUB_STANDARD = {
+    // Required status contexts on the default branch (strict off — see below).
+    requiredContexts: ['lint', 'typecheck', 'build', 'test'],
+};
+const CODE_SCANNING_CHECK = 'Code-scanning gate';
+const CHECK_NAMES = [
+    'Branch protection',
+    'Merge settings',
+    'Workflow permissions',
+    CODE_SCANNING_CHECK,
+];
+// Recommended CodeQL alert thresholds — GitHub's UI defaults. This is the
+// override surface: bump them here for a stricter/looser fleet-wide baseline.
+// ponytail: module constants, not per-repo config, until a repo actually needs to differ.
+const CODE_SCANNING_THRESHOLDS = {
+    security_alerts_threshold: 'high_or_higher',
+    alerts_threshold: 'errors',
+};
+const CODE_SCANNING_RULESET_NAME = 'code-scanning-main';
+/** The branch ruleset POSTed to require code-scanning results before merge (#269). */
+const CODE_SCANNING_RULESET_BODY = JSON.stringify({
+    name: CODE_SCANNING_RULESET_NAME,
+    target: 'branch',
+    enforcement: 'active',
+    // ~DEFAULT_BRANCH keeps this branch-name-agnostic across the fleet.
+    conditions: { ref_name: { include: ['~DEFAULT_BRANCH'], exclude: [] } },
+    rules: [
+        {
+            type: 'code_scanning',
+            parameters: {
+                code_scanning_tools: [{ tool: 'CodeQL', ...CODE_SCANNING_THRESHOLDS }],
+            },
+        },
+    ],
+});
+/** All three checks as an `ok` skip — keeps them out of next-steps and exit code. */
+function skipAll(reason) {
+    return CHECK_NAMES.map((check) => ({ check, status: 'ok', detail: `skipped — ${reason}` }));
+}
+function skip(check, reason) {
+    return { check, status: 'ok', detail: `skipped — ${reason}` };
+}
+/**
+ * One combined probe: proves gh is installed + authed + has a GitHub remote +
+ * online, and carries identity, default branch, and the merge settings. Reads
+ * the REST repo endpoint (gh resolves the `{owner}/{repo}` placeholder from the
+ * remote) rather than `gh repo view --json` because auto-merge (`allow_auto_merge`)
+ * is not a `gh repo view` field at all — requesting it fails the whole call.
+ */
+async function probeRepo(exec) {
+    const r = await exec(['api', 'repos/{owner}/{repo}']);
+    if (!r.ok)
+        return { skip: probeFailureReason(r) };
+    let d;
+    try {
+        d = JSON.parse(r.stdout);
+    }
+    catch {
+        return { skip: 'could not parse gh output' };
+    }
+    const nwo = typeof d.full_name === 'string' ? d.full_name : undefined;
+    if (!nwo)
+        return { skip: 'no GitHub remote' };
+    return {
+        info: {
+            nwo,
+            branch: typeof d.default_branch === 'string' ? d.default_branch : 'main',
+            autoMerge: d.allow_auto_merge === true,
+            squashMerge: d.allow_squash_merge === true,
+            deleteOnMerge: d.delete_branch_on_merge === true,
+            mergeVisible: ['allow_auto_merge', 'allow_squash_merge', 'delete_branch_on_merge'].every((k) => typeof d[k] === 'boolean'),
+        },
+    };
+}
+export async function checkGitHubSettings(dir, exec) {
+    // Cheap gate first: no .git → never spawn (keeps tmp-dir doctor runs offline).
+    if (!(await fs.pathExists(path.join(dir, '.git'))))
+        return skipAll('not a git repository');
+    // Bind gh's cwd to the target dir so its repo resolution honors `-d` (#218).
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const probe = await probeRepo(gh);
+    if ('skip' in probe)
+        return skipAll(probe.skip);
+    const { info } = probe;
+    return [
+        await checkBranchProtection(gh, info.nwo, info.branch),
+        checkMergeSettings(info),
+        await checkWorkflowPermissions(gh, info.nwo),
+        await checkCodeScanningRuleset(gh, info.nwo, info.branch, dir),
+    ];
+}
+function probeFailureReason(probe) {
+    if (probe.code === null)
+        return 'gh not installed';
+    if (/not logged|gh auth login|authentication/i.test(probe.stderr))
+        return 'gh not authenticated';
+    return 'not a GitHub repo or gh unavailable';
+}
+async function checkBranchProtection(exec, nwo, branch) {
+    const check = 'Branch protection';
+    const r = await exec(['api', `repos/${nwo}/branches/${branch}/protection`]);
+    if (!r.ok) {
+        if (/404|not found/i.test(r.stderr)) {
+            return {
+                check,
+                status: 'optional-missing',
+                detail: `${branch} is unprotected`,
+                hint: `Protect ${branch}: require checks ${GITHUB_STANDARD.requiredContexts.join(', ')}, no force-push/deletions`,
+            };
+        }
+        if (/403|forbidden/i.test(r.stderr))
+            return skip(check, 'token lacks admin access');
+        return skip(check, 'could not read branch protection');
+    }
+    let p;
+    try {
+        p = JSON.parse(r.stdout);
+    }
+    catch {
+        return skip(check, 'could not parse protection response');
+    }
+    const deltas = [];
+    const contexts = p.required_status_checks?.contexts ?? [];
+    // A matrix job reports each leg as `test (node 22)`, `test (node 24)`, etc.
+    // Treat any `<ctx> (...)` variant as satisfying the bare `<ctx>` requirement,
+    // so matrix CIs aren't falsely flagged as missing the check.
+    const isSatisfied = (c) => contexts.some((ctx) => ctx === c || ctx.startsWith(`${c} (`));
+    const missing = GITHUB_STANDARD.requiredContexts.filter((c) => !isSatisfied(c));
+    if (missing.length)
+        deltas.push(`missing required checks: ${missing.join(', ')}`);
+    if (p.required_status_checks?.strict === true)
+        deltas.push('strict status checks on (should be off)');
+    // enforce_admins must stay off so the App/RELEASE_TOKEN can bypass protection
+    // to push semantic-release's version commit (see Release-token doctor check).
+    if (p.enforce_admins?.enabled === true)
+        deltas.push('enforce_admins on (blocks release bypass)');
+    if (p.allow_force_pushes?.enabled === true)
+        deltas.push('force pushes allowed');
+    if (p.allow_deletions?.enabled === true)
+        deltas.push('branch deletions allowed');
+    // Required human review deadlocks solo Dependabot auto-merge.
+    if (p.required_pull_request_reviews)
+        deltas.push('required PR reviews on (deadlocks auto-merge)');
+    if (deltas.length)
+        return {
+            check,
+            status: 'drift',
+            detail: deltas.join('; '),
+            hint: `Align ${branch} protection with the standard`,
+        };
+    return { check, status: 'ok', detail: `${branch} protected per standard` };
+}
+function checkMergeSettings(info) {
+    const check = 'Merge settings';
+    // The token can't see the merge-setting fields (no admin:read) — skip rather
+    // than misreport the absent booleans as "disabled" (a false-positive drift).
+    if (!info.mergeVisible)
+        return skip(check, 'token lacks admin:read for merge settings');
+    const deltas = [];
+    if (!info.autoMerge)
+        deltas.push('auto-merge disabled');
+    if (!info.squashMerge)
+        deltas.push('squash-merge disabled');
+    if (!info.deleteOnMerge)
+        deltas.push('delete-branch-on-merge disabled');
+    if (deltas.length)
+        return {
+            check,
+            status: 'drift',
+            detail: deltas.join('; '),
+            hint: 'Enable auto-merge, squash-merge, and delete-branch-on-merge in repo settings',
+        };
+    return { check, status: 'ok', detail: 'auto-merge, squash-merge, delete-on-merge all on' };
+}
+async function checkWorkflowPermissions(exec, nwo) {
+    const check = 'Workflow permissions';
+    const r = await exec(['api', `repos/${nwo}/actions/permissions/workflow`]);
+    if (!r.ok) {
+        if (/403|forbidden/i.test(r.stderr))
+            return skip(check, 'token lacks admin access');
+        return skip(check, 'could not read workflow permissions');
+    }
+    let p;
+    try {
+        p = JSON.parse(r.stdout);
+    }
+    catch {
+        return skip(check, 'could not parse permissions response');
+    }
+    const deltas = [];
+    if (p.default_workflow_permissions !== 'read')
+        deltas.push(`default permissions '${p.default_workflow_permissions}' (should be read)`);
+    if (p.can_approve_pull_request_reviews === true)
+        deltas.push('workflows can approve PRs (should be off)');
+    if (deltas.length)
+        return {
+            check,
+            status: 'drift',
+            detail: deltas.join('; '),
+            hint: 'Set default workflow permissions to read-only and disable workflow PR approvals',
+        };
+    return { check, status: 'ok', detail: 'read-only default, no workflow PR approvals' };
+}
+/**
+ * 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
+ * GitHub's default setup (no file — ask the code-scanning API). Mirrors doctor's
+ * on-disk CodeQL check; kept inline to avoid a doctor↔settings import cycle.
+ */
+async function codeqlEnabled(gh, nwo, dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (await fs.pathExists(workflowsDir)) {
+        try {
+            for (const f of await fs.readdir(workflowsDir)) {
+                if (!/\.ya?ml$/.test(f))
+                    continue;
+                const content = await fs.readFile(path.join(workflowsDir, f), 'utf-8');
+                if (/github\/codeql-action/.test(content))
+                    return true;
+            }
+        }
+        catch {
+            // fall through to the API probe
+        }
+    }
+    // Default setup leaves no workflow file — the API is the only signal.
+    const r = await gh(['api', `repos/${nwo}/code-scanning/default-setup`]);
+    if (!r.ok)
+        return false;
+    try {
+        return JSON.parse(r.stdout).state === 'configured';
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a ruleset's ref_name conditions cover the default branch. */
+function rulesetTargetsBranch(conditions, branch) {
+    const include = conditions?.ref_name?.include ?? [];
+    return include.some((ref) => ref === '~DEFAULT_BRANCH' || ref === '~ALL' || ref === `refs/heads/${branch}`);
+}
+/**
+ * Does an active branch ruleset enforce a code_scanning rule on the default
+ * branch? The list endpoint omits rules/conditions, so active branch rulesets
+ * are fetched by id to inspect them. 'skip' on any read failure (self-skips like
+ * the other checks).
+ */
+async function hasCodeScanningRuleset(gh, nwo, branch) {
+    const list = await gh(['api', `repos/${nwo}/rulesets`]);
+    if (!list.ok)
+        return 'skip';
+    let rulesets;
+    try {
+        rulesets = JSON.parse(list.stdout);
+    }
+    catch {
+        return 'skip';
+    }
+    if (!Array.isArray(rulesets))
+        return 'skip';
+    const active = rulesets.filter((r) => r.target === 'branch' && r.enforcement === 'active' && typeof r.id === 'number');
+    for (const rs of active) {
+        const detail = await gh(['api', `repos/${nwo}/rulesets/${rs.id}`]);
+        if (!detail.ok)
+            continue;
+        let full;
+        try {
+            full = JSON.parse(detail.stdout);
+        }
+        catch {
+            continue;
+        }
+        const enforcesCodeScanning = (full.rules ?? []).some((r) => r.type === 'code_scanning');
+        if (enforcesCodeScanning && rulesetTargetsBranch(full.conditions, branch))
+            return 'yes';
+    }
+    return 'no';
+}
+/**
+ * The #269 gap: CodeQL results are advisory by default — a High alert still
+ * merges unless a branch ruleset requires the code-scanning check. Only
+ * meaningful where CodeQL is actually on, so it no-ops otherwise.
+ */
+async function checkCodeScanningRuleset(gh, nwo, branch, dir) {
+    const check = CODE_SCANNING_CHECK;
+    if (!(await codeqlEnabled(gh, nwo, dir))) {
+        return { check, status: 'ok', detail: 'CodeQL not enabled — no code-scanning gate needed' };
+    }
+    const found = await hasCodeScanningRuleset(gh, nwo, branch);
+    if (found === 'skip')
+        return skip(check, 'could not read rulesets');
+    if (found === 'yes') {
+        return { check, status: 'ok', detail: `active ruleset requires code-scanning on ${branch}` };
+    }
+    return {
+        check,
+        status: 'drift',
+        detail: `CodeQL is on but no active ruleset requires code-scanning on ${branch} (High alerts stay advisory)`,
+        hint: 'Run `npx @rtorcato/repo-tooling fix github-settings` to add a code_scanning branch ruleset that blocks merge on High+ CodeQL alerts',
+    };
+}
+/** The branch-protection body PUT to the API — mirrors the doctor standard. */
+const PROTECTION_BODY = JSON.stringify({
+    required_status_checks: { strict: false, contexts: GITHUB_STANDARD.requiredContexts },
+    // enforce_admins off so the App/RELEASE_TOKEN can bypass to push release commits.
+    enforce_admins: false,
+    // Required human review would deadlock solo Dependabot auto-merge.
+    required_pull_request_reviews: null,
+    restrictions: null,
+    allow_force_pushes: false,
+    allow_deletions: false,
+});
+/** Pure: the exact `gh api` invocations for whatever deviates ([] when compliant). */
+export function buildGhApplyCommands(state) {
+    const commands = [];
+    if (state.merge)
+        commands.push({
+            label: 'merge settings (auto-merge, squash, delete-on-merge)',
+            args: [
+                'api',
+                '-X',
+                'PATCH',
+                `repos/${state.nwo}`,
+                '-F',
+                'allow_auto_merge=true',
+                '-F',
+                'allow_squash_merge=true',
+                '-F',
+                'delete_branch_on_merge=true',
+            ],
+        });
+    if (state.protection)
+        commands.push({
+            label: `branch protection on ${state.branch}`,
+            args: [
+                'api',
+                '-X',
+                'PUT',
+                `repos/${state.nwo}/branches/${state.branch}/protection`,
+                '--input',
+                '-',
+            ],
+            stdin: PROTECTION_BODY,
+        });
+    if (state.workflow)
+        commands.push({
+            label: 'workflow permissions (read-only)',
+            args: [
+                'api',
+                '-X',
+                'PUT',
+                `repos/${state.nwo}/actions/permissions/workflow`,
+                '-f',
+                'default_workflow_permissions=read',
+                '-F',
+                'can_approve_pull_request_reviews=false',
+            ],
+        });
+    return commands;
+}
+/**
+ * Re-reads GitHub state and applies only the deltas via `gh api` (idempotent —
+ * a compliant repo is a no-op). Returns human labels for what changed, or `[]`
+ * on skip (no gh/auth/remote, or already compliant), logging the reason. Mirrors
+ * the "no package.json found — skipping" fixer pattern. Read-only unless a delta
+ * exists, so re-runs (walk-all hits it up to 3×) are safe.
+ */
+export async function applyGithubSettings(dir, exec) {
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        console.log(chalk.gray('   skipped — not a git repository'));
+        return [];
+    }
+    // Bind gh's cwd to the target dir so its repo resolution honors `-d` (#218).
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const probe = await probeRepo(gh);
+    if ('skip' in probe) {
+        console.log(chalk.gray(`   skipped — ${probe.skip}`));
+        return [];
+    }
+    const { info } = probe;
+    // Re-read via the same checks so the delta logic stays single-sourced. A 403
+    // (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 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',
+    });
+    const applied = [];
+    for (const cmd of commands) {
+        const r = await gh(cmd.args, cmd.stdin);
+        if (r.ok)
+            applied.push(cmd.label);
+        else
+            console.log(chalk.yellow(`   could not apply ${cmd.label}: ${r.stderr.trim() || 'gh error'}`));
+    }
+    // Code-scanning ruleset (#269): POST only when CodeQL is on and no active gate
+    // covers the default branch — the check re-read keeps this idempotent.
+    const cs = await checkCodeScanningRuleset(gh, info.nwo, info.branch, dir);
+    if (cs.status === 'drift') {
+        const label = `code-scanning ruleset on ${info.branch}`;
+        const r = await gh(['api', '-X', 'POST', `repos/${info.nwo}/rulesets`, '--input', '-'], CODE_SCANNING_RULESET_BODY);
+        if (r.ok)
+            applied.push(label);
+        else
+            console.log(chalk.yellow(`   could not apply ${label}: ${r.stderr.trim() || 'gh error'}`));
+    }
+    if (applied.length === 0)
+        console.log(chalk.gray('   already configured — nothing to apply'));
+    return applied;
+}

package/dist/base/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/commands/doctor.js

@@ -1,8 +1,12 @@
 import path from 'node:path';
 import chalk from 'chalk';
 import fs from 'fs-extra';
+import { renderGitHubWorkflow } from '../../base/ci.js';
+import { githubJobs } from '../../languages/js/ci.js';
+import { inferProjectConfig } from '../../languages/js/fixers.js';
 import { resolveLanguageModule } from '../../languages/registry.js';
 import { SWIFT_GIT_HOOKS, runSwiftChecks } from '../../languages/swift/checks.js';
+import { readSwiftPackage, renderSwiftWorkflow } from '../../languages/swift/ci.js';
 import { detectLanguage } from '../utils/detect-language.js';
 import { checkGitHubSettings } from '../../base/github-settings.js';
 import { checkGitIdentity } from '../../base/git-identity.js';
@@ -148,7 +152,7 @@ async function runBaseChecks(dir, lock, opts) {
         results.push(await checkGitHooks(dir, opts.hooks));
         results.push(await checkPrePushHook(dir, opts.hooks));
     }
-    results.push(await checkGitHubActions(dir));
+    results.push(await checkGitHubActions(dir, opts.presetWorkflow));
     results.push(await checkDependabot(dir));
     results.push(await checkCodeQL(dir));
     // GitHub repo-settings drift (branch protection, merge settings, workflow
@@ -186,6 +190,7 @@ export async function runDoctor(dir) {
             ...(await runBaseChecks(targetDir, lock, {
                 hooks: null,
                 badges: { audience: 'public', fixTarget: null },
+                presetWorkflow: null,
             })),
         ];
         return demoteDeclined(results, lock);
@@ -205,6 +210,7 @@ export async function runDoctor(dir) {
                 // badges always apply. No fixer: `fix badges` derives the block from
                 // package.json name/repository, which a Swift repo hasn't got.
                 badges: { audience: 'public', fixTarget: null },
+                presetWorkflow: renderSwiftWorkflow(await readSwiftPackage(targetDir)),
             })),
             ...(await runSwiftChecks(targetDir)),
         ];
@@ -254,6 +260,7 @@ export async function runDoctor(dir) {
     results.push(...(await runBaseChecks(targetDir, lock, {
         hooks: jsGitHooksProfile(pkg),
         badges: { audience: jsBadgeAudience(pkg), fixTarget: 'badges' },
+        presetWorkflow: renderGitHubWorkflow(githubJobs(inferProjectConfig(pkg))),
     })));
     return demoteDeclined(results, lock);
 }

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

@@ -57,6 +57,7 @@ const SWIFT_FIX_TARGETS = {
     SwiftLint: 'swiftlint',
     Periphery: 'periphery',
     'Swift .gitignore': 'swift-gitignore',
+    'Release automation': 'swift-release',
 };
 export function getFixTargetForCheck(checkName, language) {
     if (language === 'swift' && SWIFT_FIX_TARGETS[checkName]) {
@@ -97,6 +98,10 @@ export function declinedInLock(lock, checkName) {
                 c.linting?.tool === 'none' &&
                 c.testing?.framework === 'none');
         case 'semantic-release':
+        // The Swift shape of the same recorded choice (#310): `semanticRelease`
+        // is the config's release-automation flag, and on a SwiftPM repo that
+        // means a tag-triggered workflow rather than an npm publish.
+        case 'Release automation':
             return c.semanticRelease === false;
         case 'Dependabot':
         case 'CodeQL':
@@ -160,6 +165,7 @@ export function lockfilePatchForTarget(target, lock) {
         case 'swift-git-hooks':
             return c.gitHooks ? null : { gitHooks: true };
         case 'semantic-release':
+        case 'swift-release':
             return c.semanticRelease ? null : { semanticRelease: true };
         case 'dependabot':
         case 'renovate':

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

@@ -89,8 +89,10 @@ export function buildPresetConfig(name, projectName) {
                 // commitlint *is* an npm package and needs node on PATH to run, so
                 // the Swift hooks deliberately wire no commit-msg hook.
                 commitLint: false,
-                // semantic-release publishes to npm. SwiftPM consumes git tags.
-                semanticRelease: false,
+                // The release-automation flag, not the npm tool: semantic-release
+                // publishes to npm, and SwiftPM consumes git tags, so on this path it
+                // means a tag-triggered release workflow instead (#310).
+                semanticRelease: true,
                 securityAutomation: true,
                 bundler: 'none',
                 // Every badge URL is derived from package.json (name + repository),

package/dist/cli/generators/github-actions.js

@@ -16,7 +16,19 @@ const CODECOV_YML = `coverage:
         target: auto
         threshold: 1%
 `;
-export async function generateGitHubActions(config, targetDir) {
+/** Matches the fixer's declared output, so `fix` reports the same path it lists. */
+export const CI_WORKFLOW = '.github/workflows/ci.yml';
+/**
+ * @param overwrite Replace a ci.yml that no longer matches the preset. Off by
+ * default: this used to write unconditionally, so a consuming repo's customized
+ * workflow — an extra job, a Dependabot-bumped action pin — was reverted on
+ * every sync with no diff, no prompt and no backup (#349, the mechanism behind
+ * #340). Same self-enforced safe-add as github-workflows.ts, widened to "or is
+ * byte-identical anyway" so a no-op regeneration still reports honestly. Only a
+ * caller that has told the user this workflow itself is drifting passes true.
+ * @returns the files actually written, relative to targetDir.
+ */
+export async function generateGitHubActions(config, targetDir, { overwrite = false } = {}) {
     const workflowsDir = path.join(targetDir, '.github', 'workflows');
     await fs.ensureDir(workflowsDir);
     // This is the JS path specifically. Swift (#287) renders its own workflow
@@ -26,10 +38,18 @@ export async function generateGitHubActions(config, targetDir) {
     // paths meet at renderGitHubWorkflow() in src/base/ci.ts, which is the seam
     // that actually matters.
     const workflow = renderGitHubWorkflow(githubJobs(config));
-    await fs.writeFile(path.join(workflowsDir, 'ci.yml'), workflow);
+    const ciPath = path.join(workflowsDir, 'ci.yml');
+    const existing = (await fs.pathExists(ciPath)) ? await fs.readFile(ciPath, 'utf-8') : null;
+    const filesWritten = [];
+    if (overwrite || existing === null || existing === workflow) {
+        await fs.writeFile(ciPath, workflow);
+        filesWritten.push(CI_WORKFLOW);
+    }
     // codecov.yml is the CI's coverage-upload companion — emit it alongside ci.yml
     // whenever the workflow uploads coverage, so the codecov badge isn't red.
     if (usesCoverage(config)) {
         await fs.writeFile(path.join(targetDir, 'codecov.yml'), CODECOV_YML);
+        filesWritten.push('codecov.yml');
     }
+    return filesWritten;
 }

package/dist/languages/js/ci.js

@@ -102,7 +102,7 @@ export function githubJobs(config) {
             ? `
 
       - name: 📊 Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v7
         with:
           token: \${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: false`

package/dist/languages/js/fixers.js

@@ -4,7 +4,7 @@ import fs from 'fs-extra';
 import { buildBadgeBlock, parseRepository, upsertBadges } from '../../cli/generators/badges.js';
 import { generateReleasePleaseConfig, generateRolldownConfig, generateRollupConfig, generateSemanticReleaseConfig, } from '../../cli/generators/build.js';
 import { generateHuskyConfig, generatePrePushHook } from '../../cli/generators/git.js';
-import { generateGitHubActions } from '../../cli/generators/github-actions.js';
+import { CI_WORKFLOW, generateGitHubActions } from '../../cli/generators/github-actions.js';
 import { generateGitLabCI } from '../../cli/generators/gitlab-ci.js';
 import { GH_WORKFLOWS, generateGhWorkflow } from '../../cli/generators/github-workflows.js';
 import { generateESLintConfig, generatePrettierConfig } from '../../cli/generators/linting.js';
@@ -22,7 +22,8 @@ import { generateDocsSite } from '../../cli/generators/docs-site.js';
 import { generateTypedocConfig, generateTypedocWorkflow } from '../../cli/generators/typedoc.js';
 import { copyPreset } from '../../cli/utils/copy-preset.js';
 import { LOCKFILE_NAME, writeLockfile } from '../../cli/utils/lockfile.js';
-function inferProjectConfig(pkg) {
+/** Exported so doctor can render the preset ci.yml it compares against (#349). */
+export function inferProjectConfig(pkg) {
     const deps = {
         ...(pkg?.dependencies ?? {}),
         ...(pkg?.devDependencies ?? {}),
@@ -303,13 +304,19 @@ 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'],
-        outputs: ['.github/workflows/ci.yml', 'codecov.yml'],
+        outputs: [CI_WORKFLOW, 'codecov.yml'],
         canFixDrift: true,
-        async run({ targetDir, pkg }) {
-            await generateGitHubActions(inferProjectConfig(pkg), targetDir);
-            const filesWritten = ['.github/workflows/ci.yml'];
-            if (await fs.pathExists(path.join(targetDir, 'codecov.yml')))
-                filesWritten.push('codecov.yml');
+        async run({ targetDir, pkg, result }) {
+            // Only a `GitHub Actions` finding means the user was shown that the
+            // workflow itself is wrong (and got the destructive-overwrite prompt).
+            // A sibling finding — Coverage upload, npm OIDC publish — must not take a
+            // customized ci.yml down with it (#349).
+            const filesWritten = await generateGitHubActions(inferProjectConfig(pkg), targetDir, {
+                overwrite: result.check === 'GitHub Actions',
+            });
+            if (!filesWritten.includes(CI_WORKFLOW)) {
+                console.log(chalk.yellow(`   ${CI_WORKFLOW} differs from the preset — left as-is; run \`fix github-actions --diff\` to see the delta`));
+            }
             return { filesWritten };
         },
     },