@rtorcato/repo-tooling 3.2.4 → 3.2.5

package/dist/base/checks.js

@@ -0,0 +1,410 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { BADGE_START, hasPublicOnlyBadges } from '../cli/generators/badges.js';
+export async function checkFile(dir, spec) {
+    for (const candidate of spec.candidates) {
+        const filepath = path.join(dir, candidate);
+        if (!(await fs.pathExists(filepath)))
+            continue;
+        const contents = await fs.readFile(filepath, 'utf-8');
+        if (spec.matcher.test(contents)) {
+            return {
+                check: spec.check,
+                status: 'ok',
+                detail: `${candidate} ${spec.expected}`,
+            };
+        }
+        return {
+            check: spec.check,
+            status: 'drift',
+            detail: `${candidate} found but does not ${spec.expected}`,
+            hint: spec.hint,
+        };
+    }
+    return {
+        check: spec.check,
+        status: spec.optional ? 'optional-missing' : 'missing',
+        detail: `no ${spec.candidates.join(' / ')} found`,
+        hint: spec.hint,
+    };
+}
+export async function checkEditorConfig(dir) {
+    const exists = await fs.pathExists(path.join(dir, '.editorconfig'));
+    return {
+        check: 'EditorConfig',
+        status: exists ? 'ok' : 'optional-missing',
+        detail: exists ? '.editorconfig found' : 'no .editorconfig',
+        hint: exists ? undefined : 'Add an .editorconfig for cross-editor formatting consistency',
+    };
+}
+export async function checkCodeowners(dir) {
+    for (const candidate of ['CODEOWNERS', '.github/CODEOWNERS', 'docs/CODEOWNERS']) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            return {
+                check: 'CODEOWNERS',
+                status: 'ok',
+                detail: `${candidate} found`,
+            };
+        }
+    }
+    return {
+        check: 'CODEOWNERS',
+        status: 'optional-missing',
+        detail: 'no CODEOWNERS file',
+        hint: 'Run `npx @rtorcato/repo-tooling fix codeowners` to scaffold .github/CODEOWNERS',
+    };
+}
+export async function checkCommunityHealth(dir) {
+    const anchors = ['CONTRIBUTING.md', 'SECURITY.md'];
+    const present = await Promise.all(anchors.map((f) => fs.pathExists(path.join(dir, f))));
+    if (present.every(Boolean)) {
+        return {
+            check: 'Community health',
+            status: 'ok',
+            detail: 'CONTRIBUTING.md and SECURITY.md found',
+        };
+    }
+    return {
+        check: 'Community health',
+        status: 'optional-missing',
+        detail: 'missing community-health files (CONTRIBUTING/SECURITY/templates)',
+        hint: 'Run `npx @rtorcato/repo-tooling fix community-health` to scaffold them',
+    };
+}
+export async function checkGitHubActions(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir))) {
+        return {
+            check: 'GitHub Actions',
+            status: 'optional-missing',
+            detail: 'no .github/workflows/',
+            hint: 'Run `npx @rtorcato/repo-tooling setup` to scaffold a CI workflow',
+        };
+    }
+    try {
+        const files = await fs.readdir(workflowsDir);
+        const workflows = files.filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        if (workflows.length === 0) {
+            return {
+                check: 'GitHub Actions',
+                status: 'optional-missing',
+                detail: '.github/workflows/ is empty',
+                hint: 'Add a workflow file (e.g. ci.yml) under .github/workflows/',
+            };
+        }
+        return {
+            check: 'GitHub Actions',
+            status: 'ok',
+            detail: `${workflows.length} workflow${workflows.length === 1 ? '' : 's'} in .github/workflows/`,
+        };
+    }
+    catch {
+        return {
+            check: 'GitHub Actions',
+            status: 'optional-missing',
+            detail: 'unable to read .github/workflows/',
+        };
+    }
+}
+export async function checkDependabot(dir) {
+    for (const candidate of ['.github/dependabot.yml', '.github/dependabot.yaml']) {
+        const candidatePath = path.join(dir, candidate);
+        if (await fs.pathExists(candidatePath)) {
+            // The canonical standard (apps/docs/docs/guides/dependabot-strategy.md) is
+            // the safe-tier + major-tier grouping plus the auto-merge workflow that
+            // depends on it. Flag any config that predates it so `fix dependabot` can
+            // bring the pair up to standard.
+            const content = await fs.readFile(candidatePath, 'utf8');
+            const deltas = [];
+            for (const group of ['production-minor', 'dev-minor', 'major-updates']) {
+                if (!new RegExp(`^\\s*${group}:`, 'm').test(content)) {
+                    deltas.push(`missing \`${group}\` group`);
+                }
+            }
+            const automergePath = path.join(dir, '.github', 'workflows', 'dependabot-automerge.yml');
+            if (!(await fs.pathExists(automergePath))) {
+                deltas.push('missing dependabot-automerge workflow');
+            }
+            if (deltas.length > 0) {
+                return {
+                    check: 'Dependabot',
+                    status: 'drift',
+                    detail: `${candidate} drifts from canonical (${deltas.join('; ')})`,
+                    hint: 'Run `npx @rtorcato/repo-tooling fix dependabot` to apply the canonical grouping + auto-merge workflow',
+                };
+            }
+            return {
+                check: 'Dependabot',
+                status: 'ok',
+                detail: `${candidate} + auto-merge workflow`,
+            };
+        }
+    }
+    for (const candidate of [
+        'renovate.json',
+        'renovate.json5',
+        '.github/renovate.json',
+        '.github/renovate.json5',
+        '.renovaterc',
+        '.renovaterc.json',
+    ]) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            return {
+                check: 'Dependabot',
+                status: 'ok',
+                detail: `${candidate} found (Renovate)`,
+            };
+        }
+    }
+    return {
+        check: 'Dependabot',
+        status: 'optional-missing',
+        detail: 'no Dependabot or Renovate config',
+        hint: 'Run `npx @rtorcato/repo-tooling fix dependabot` (or `fix renovate`) to scaffold weekly dep updates',
+    };
+}
+export async function checkCodeQL(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir))) {
+        return {
+            check: 'CodeQL',
+            status: 'optional-missing',
+            detail: 'no .github/workflows/',
+            hint: 'Run `npx @rtorcato/repo-tooling fix codeql` to scaffold CodeQL security scanning',
+        };
+    }
+    for (const candidate of ['codeql.yml', 'codeql.yaml']) {
+        if (await fs.pathExists(path.join(workflowsDir, candidate))) {
+            return {
+                check: 'CodeQL',
+                status: 'ok',
+                detail: `.github/workflows/${candidate} found`,
+            };
+        }
+    }
+    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 (/github\/codeql-action/.test(content)) {
+                return {
+                    check: 'CodeQL',
+                    status: 'ok',
+                    detail: `codeql-action referenced in ${f}`,
+                };
+            }
+        }
+    }
+    catch {
+        // fall through to optional-missing
+    }
+    return {
+        check: 'CodeQL',
+        status: 'optional-missing',
+        detail: 'no codeql workflow found',
+        hint: 'Run `npx @rtorcato/repo-tooling fix codeql` to scaffold CodeQL security scanning',
+    };
+}
+// 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).
+export async function checkCoverageUpload(dir) {
+    const readmePath = path.join(dir, 'README.md');
+    const readme = (await fs.pathExists(readmePath)) ? await fs.readFile(readmePath, 'utf8') : '';
+    if (!/codecov\.io/.test(readme)) {
+        return {
+            check: 'Coverage upload',
+            status: 'ok',
+            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
+        }
+    }
+    return {
+        check: 'Coverage upload',
+        status: 'drift',
+        detail: 'README has a Codecov badge but no CI step uploads coverage (badge stays red)',
+        hint: 'Run `npx @rtorcato/repo-tooling fix github-actions` to regenerate ci.yml with a Codecov upload step',
+    };
+}
+export async function checkAiSetup(dir) {
+    // Consider AI setup present if AGENTS.md carries the js-tooling block or the
+    // Claude skill is installed — the two primary markers `fix ai` writes.
+    const agentsPath = path.join(dir, 'AGENTS.md');
+    const hasAgentsBlock = (await fs.pathExists(agentsPath)) &&
+        (await fs.readFile(agentsPath, 'utf8')).includes('<!-- js-tooling:start -->');
+    const hasSkill = (await fs.pathExists(path.join(dir, '.claude', 'skills', 'repo-tooling.md'))) ||
+        // Pre-rename name — still counts as present until `fix` migrates it.
+        (await fs.pathExists(path.join(dir, '.claude', 'skills', 'js-tooling.md')));
+    if (hasAgentsBlock || hasSkill) {
+        return {
+            check: 'AI setup',
+            status: 'ok',
+            detail: hasAgentsBlock ? 'AGENTS.md has the js-tooling block' : '.claude skill installed',
+        };
+    }
+    return {
+        check: 'AI setup',
+        status: 'optional-missing',
+        detail: 'no AI agent files (AGENTS.md, CLAUDE.md, Cursor/Copilot rules, Claude skill)',
+        hint: 'Run `npx @rtorcato/repo-tooling fix ai` to scaffold agent rules for every AI tool',
+    };
+}
+/**
+ * Conventional Commits is a repo convention, not a JavaScript one — the config
+ * file is the same in any repo that has node available to run commitlint, so
+ * the spec lives here rather than in the JS module's FILE_CHECKS (#309).
+ */
+export const COMMITLINT_FILE_CHECK = {
+    check: 'Commitlint',
+    candidates: ['commitlint.config.js', 'commitlint.config.mjs', 'commitlint.config.cjs'],
+    expected: 'exports "@rtorcato/repo-tooling/commitlint/config"',
+    matcher: /@rtorcato\/(?:js|repo)-tooling\/commitlint\/config/,
+    optional: true,
+};
+/**
+ * True when a shell hook has an uncommented line matching `pattern`. A
+ * commented-out line (e.g. `# pnpm verify`) doesn't count — the command never
+ * runs, so it isn't real wiring.
+ */
+export function hookHasUncommented(contents, pattern) {
+    return contents.split('\n').some((line) => {
+        const trimmed = line.trim();
+        return trimmed.length > 0 && !trimmed.startsWith('#') && pattern.test(trimmed);
+    });
+}
+/** `swift test` → /\bswift\s+test\b/, so extra whitespace in a hook still matches. */
+function commandMatcher(command) {
+    const escaped = command.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
+    return new RegExp(`\\b${escaped}\\b`);
+}
+export async function checkGitHooks(dir, p) {
+    const check = 'Git hooks';
+    const hint = `Run \`npx @rtorcato/repo-tooling fix ${p.fixTarget}\` to enable git hooks`;
+    const hooksDir = await fs.pathExists(path.join(dir, p.dir));
+    // With no committed install signal, the hooks directory itself is the whole
+    // answer — there's no second half that can drift out of sync with it.
+    const installed = p.install === null ? hooksDir : p.install.present;
+    if (hooksDir && installed) {
+        return {
+            check,
+            status: 'ok',
+            detail: p.install ? `${p.dir}/ and ${p.install.label} configured` : `${p.dir}/ found`,
+        };
+    }
+    if (hooksDir || installed) {
+        return {
+            check,
+            status: 'drift',
+            detail: hooksDir
+                ? `${p.dir}/ exists but no ${p.install?.label}`
+                : `${p.install?.label} set but no ${p.dir}/ directory`,
+            hint: `${hint} (scaffolds both halves)`,
+        };
+    }
+    return { check, status: 'optional-missing', detail: 'git hooks not configured', hint };
+}
+/**
+ * The pre-push gate. Only asserts that the hook runs the language's verify
+ * command — whether that command itself is well-formed is the language module's
+ * business (JS keeps a `verify script` check for exactly that).
+ */
+export async function checkPrePushHook(dir, p) {
+    const check = 'Pre-push hook';
+    if (!(await fs.pathExists(path.join(dir, p.dir)))) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: 'git hooks not configured',
+            hint: `Run \`npx @rtorcato/repo-tooling fix ${p.fixTarget}\` to enable git hooks (includes pre-push)`,
+        };
+    }
+    const hookPath = path.join(dir, p.dir, 'pre-push');
+    if (!(await fs.pathExists(hookPath))) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: `no ${p.dir}/pre-push`,
+            hint: `Run \`npx @rtorcato/repo-tooling fix ${p.fixTarget}\` to scaffold a pre-push hook that runs \`${p.verifyCommand}\``,
+        };
+    }
+    const contents = await fs.readFile(hookPath, 'utf-8');
+    if (hookHasUncommented(contents, commandMatcher(p.verifyCommand))) {
+        return { check, status: 'ok', detail: `${p.dir}/pre-push runs \`${p.verifyCommand}\`` };
+    }
+    return {
+        check,
+        status: 'drift',
+        detail: `${p.dir}/pre-push exists but does not run \`${p.verifyCommand}\``,
+        hint: `Run \`npx @rtorcato/repo-tooling fix ${p.fixTarget}\` to align the hook with \`${p.verifyCommand}\``,
+    };
+}
+export async function checkReadmeBadges(dir, audience, 
+/** `fix` target that rebuilds the badge block, or null when the language has none. */
+fixTarget) {
+    const check = 'README badges';
+    const hint = fixTarget
+        ? `Run \`npx @rtorcato/repo-tooling fix ${fixTarget}\` to add CI/npm/coverage/license badges`
+        : 'Add CI and license badges to README.md';
+    const readmePath = path.join(dir, 'README.md');
+    const readme = (await fs.pathExists(readmePath)) ? await fs.readFile(readmePath, 'utf8') : '';
+    if (audience === 'private') {
+        // Only a problem if a private/app repo carries badges that would 404.
+        if (readme && hasPublicOnlyBadges(readme)) {
+            return {
+                check,
+                status: 'drift',
+                detail: 'README has npm/coverage badges but the package is private (they 404)',
+                hint: fixTarget
+                    ? `Run \`npx @rtorcato/repo-tooling fix ${fixTarget}\` to rebuild badges for a private repo`
+                    : 'Remove the npm/coverage badges — they 404 for a private package',
+            };
+        }
+        return { check, status: 'ok', detail: 'not applicable (private package)' };
+    }
+    if (audience === 'not-applicable') {
+        return { check, status: 'ok', detail: 'not applicable (no published exports)' };
+    }
+    const hasBadges = readme.includes(BADGE_START) ||
+        /img\.shields\.io|badge\.svg|badge\.fury\.io|codecov\.io/.test(readme);
+    if (hasBadges) {
+        return { check, status: 'ok', detail: 'README carries status badges' };
+    }
+    return { check, status: 'optional-missing', detail: 'no status badges in README', hint };
+}
+export async function checkGitLabCI(dir) {
+    for (const candidate of ['.gitlab-ci.yml', '.gitlab-ci.yaml']) {
+        if (await fs.pathExists(path.join(dir, candidate))) {
+            return {
+                check: 'GitLab CI',
+                status: 'ok',
+                detail: `${candidate} found`,
+            };
+        }
+    }
+    return {
+        check: 'GitLab CI',
+        status: 'optional-missing',
+        detail: 'no .gitlab-ci.yml',
+        hint: 'Run `npx @rtorcato/repo-tooling fix gitlab-ci` to scaffold a starter GitLab pipeline',
+    };
+}

package/dist/base/ci.js

@@ -0,0 +1,133 @@
+/**
+ * Language-agnostic CI skeletons (#283).
+ *
+ * The *shell* of a pipeline — triggers, concurrency, the skip gate, job
+ * scaffolding, stage derivation — is identical whether the repo is JS, Swift,
+ * Perl or Python. Only the steps inside each job differ. This module owns the
+ * shell; language modules (`src/languages/<id>/ci.ts`) supply the steps.
+ *
+ * Steps arrive pre-rendered rather than as a YAML AST: the generators' whole
+ * job is emitting text, and a tree we'd immediately flatten buys nothing but a
+ * serializer to maintain.
+ */
+/** Every job is gated on the skip-CI check; extra conditions are ANDed on. */
+const SKIP_GUARD = "needs.check-skip.outputs.should-skip != 'true'";
+/** Header through `jobs:` — triggers and concurrency are language-independent. */
+const WORKFLOW_HEADER = `name: 🚀 CI/CD Pipeline
+
+on:
+  push:
+    branches: [main, release, develop]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+`;
+/**
+ * Honours `[ci skip]` / `[skip ci]` in the head commit message. Pure shell
+ * plumbing — no toolchain involved, so every language shares it verbatim.
+ */
+const CHECK_SKIP_JOB = `  check-skip:
+    runs-on: ubuntu-latest
+    outputs:
+      should-skip: \${{ steps.skip-check.outputs.should-skip }}
+    steps:
+      - name: Check for skip CI
+        id: skip-check
+        run: |
+          if [[ "\${{ github.event.head_commit.message }}" =~ \\[(ci skip|skip ci)\\] ]]; then
+            echo "should-skip=true" >> $GITHUB_OUTPUT
+          else
+            echo "should-skip=false" >> $GITHUB_OUTPUT
+          fi`;
+function renderJob(job) {
+    // A lone dependency stays a scalar (`needs: check-skip`) — that's the form
+    // the hand-written workflows used, and Actions treats both identically.
+    const needs = [...(job.needs ?? []), 'check-skip'];
+    const needsYaml = needs.length === 1 ? needs[0] : `[${needs.join(', ')}]`;
+    const condition = job.if ? `${SKIP_GUARD} && ${job.if}` : SKIP_GUARD;
+    return `  ${job.id}:
+    runs-on: ${job.runsOn ?? 'ubuntu-latest'}
+    needs: ${needsYaml}
+    if: ${condition}
+${job.extra ? `${job.extra}\n` : ''}    steps:
+${job.steps}`;
+}
+/** Wrap language-supplied jobs in the shared workflow shell. */
+export function renderGitHubWorkflow(jobs) {
+    return `${WORKFLOW_HEADER}${[CHECK_SKIP_JOB, ...jobs.map(renderJob)].join('\n\n')}\n`;
+}
+/**
+ * The CodeQL workflow. Only the matrix languages vary, so the whole file lives
+ * here and each language module contributes its `codeqlLanguages`.
+ */
+export function renderCodeQLWorkflow(languages) {
+    return `name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 6 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [${languages.join(', ')}]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: \${{ matrix.language }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:\${{ matrix.language }}"
+`;
+}
+/**
+ * Wrap language-supplied jobs in the shared `.gitlab-ci.yml` shell. Stages are
+ * derived from the jobs in first-appearance order, so a language module never
+ * has to keep a stage list in sync with the jobs it emits.
+ */
+export function renderGitLabCI({ image, preamble, jobs }) {
+    const stages = [...new Set(jobs.map((job) => job.stage))];
+    // A pipeline with no jobs still needs a valid `stages:` key.
+    if (stages.length === 0)
+        stages.push('test');
+    const blocks = jobs.map((job) => `${job.id}:
+  stage: ${job.stage}
+  script:
+${job.script.map((line) => `    - ${line}`).join('\n')}${job.extra ? `\n${job.extra}` : ''}`);
+    return `# .gitlab-ci.yml — generated by @rtorcato/repo-tooling
+# Customize stages and jobs to fit your pipeline.
+
+image: ${image}
+
+stages:
+${stages.map((s) => `  - ${s}`).join('\n')}
+
+${[preamble, ...blocks].join('\n\n')}
+`;
+}

package/dist/base/fixers.js

@@ -0,0 +1,207 @@
+/**
+ * The fixer contract plus the language-agnostic fixers (#286, #303).
+ *
+ * These are the fixers for the checks in ./checks.ts — repo hygiene, security
+ * automation, community health, AI agent files, GitHub repo settings. Nothing
+ * here reads a package.json or emits a toolchain-specific step, so every
+ * language module gets them for free; `fix` concatenates them with the module's
+ * own set.
+ *
+ * Not here: `github-actions` / `gitlab-ci` / `lockfile`. Their *content* is
+ * language-shaped (CI steps, recorded tool choices), so each module ships its
+ * own — see src/base/ci.ts for the shell they share.
+ */
+import { installAgentRules, installAiSetup } from '../cli/generators/agent-rules.js';
+import { generateCommunityHealth } from '../cli/generators/community-health.js';
+import { generateCommitlintConfig } from '../cli/generators/git.js';
+import { generateCodeowners, generateEditorConfig } from '../cli/generators/misc.js';
+import { generateCodeQLWorkflow, generateDependabotConfig, generateRenovateConfig, } from '../cli/generators/security.js';
+import { copyPreset } from '../cli/utils/copy-preset.js';
+import { detectLanguage } from '../cli/utils/detect-language.js';
+import { resolveLanguageModule } from '../languages/registry.js';
+import { applyGithubSettings } from './github-settings.js';
+/** The repo's language module, resolved from its marker files. */
+async function moduleFor(targetDir) {
+    return resolveLanguageModule(await detectLanguage(targetDir));
+}
+export const BASE_FIXERS = [
+    {
+        target: 'editorconfig',
+        description: 'Scaffold .editorconfig (UTF-8, LF, tab indent)',
+        appliesTo: ['EditorConfig'],
+        outputs: ['.editorconfig'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            await generateEditorConfig(targetDir);
+            return { filesWritten: ['.editorconfig'] };
+        },
+    },
+    {
+        target: 'commitlint',
+        description: 'Scaffold commitlint.config.mjs exporting the preset',
+        // Conventional Commits is a repo convention, not a JS one (#309) — the
+        // config is identical in any repo. Running commitlint still needs node on
+        // PATH, which is why the Swift hooks don't wire a commit-msg hook.
+        appliesTo: ['Commitlint'],
+        outputs: ['commitlint.config.mjs'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            await generateCommitlintConfig(targetDir);
+            return { filesWritten: ['commitlint.config.mjs'] };
+        },
+    },
+    {
+        target: 'dependabot',
+        description: 'Scaffold the canonical .github/dependabot.yml (monthly, grouped: production-minor/dev-minor/major-updates) + the dependabot-automerge workflow',
+        appliesTo: ['Dependabot'],
+        outputs: ['.github/dependabot.yml', '.github/workflows/dependabot-automerge.yml'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const { dependabotEcosystem } = await moduleFor(targetDir);
+            return { filesWritten: await generateDependabotConfig(targetDir, dependabotEcosystem) };
+        },
+    },
+    {
+        target: 'renovate',
+        description: 'Scaffold renovate.json (weekly schedule; alternative to Dependabot)',
+        appliesTo: ['Dependabot'],
+        outputs: ['renovate.json'],
+        riskLevel: 'safe-add',
+        async run({ targetDir }) {
+            await generateRenovateConfig(targetDir);
+            return { filesWritten: ['renovate.json'] };
+        },
+    },
+    {
+        target: 'codeql',
+        description: 'Scaffold .github/workflows/codeql.yml (security scanning)',
+        appliesTo: ['CodeQL'],
+        outputs: ['.github/workflows/codeql.yml'],
+        async run({ targetDir }) {
+            const { codeqlLanguages } = await moduleFor(targetDir);
+            return { filesWritten: await generateCodeQLWorkflow(targetDir, codeqlLanguages) };
+        },
+    },
+    {
+        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)',
+        appliesTo: [
+            'Branch protection',
+            'Merge settings',
+            'Workflow permissions',
+            'Code-scanning gate',
+        ],
+        outputs: ['GitHub repo settings (remote, via gh api)'],
+        // safe-add is load-bearing: it exempts this fixer from the `--diff` shadow-run
+        // (previewFixer copies to tmp and *executes* run(), which would fire real
+        // `gh api` PUTs during a mere preview).
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            return { filesWritten: await applyGithubSettings(targetDir) };
+        },
+    },
+    {
+        target: 'codeowners',
+        description: 'Scaffold .github/CODEOWNERS with commented examples',
+        appliesTo: ['CODEOWNERS'],
+        outputs: ['.github/CODEOWNERS'],
+        riskLevel: 'safe-add',
+        canFixDrift: false,
+        async run({ targetDir }) {
+            const written = await generateCodeowners(targetDir);
+            return { filesWritten: [written] };
+        },
+    },
+    {
+        target: 'community-health',
+        description: 'Scaffold CONTRIBUTING.md, SECURITY.md, PR + issue templates',
+        appliesTo: ['Community health'],
+        outputs: [
+            'CONTRIBUTING.md',
+            'SECURITY.md',
+            '.github/PULL_REQUEST_TEMPLATE.md',
+            '.github/ISSUE_TEMPLATE/bug_report.md',
+            '.github/ISSUE_TEMPLATE/feature_request.md',
+        ],
+        riskLevel: 'safe-add',
+        canFixDrift: false,
+        async run({ targetDir }) {
+            const filesWritten = await generateCommunityHealth(targetDir);
+            return { filesWritten };
+        },
+    },
+    {
+        target: 'ai',
+        description: 'Install all AI agent files at once (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill, MCP example)',
+        appliesTo: ['AI setup'],
+        outputs: [
+            'AGENTS.md',
+            'CLAUDE.md',
+            '.cursor/rules/repo-tooling.mdc',
+            '.github/copilot-instructions.md',
+            '.claude/skills/repo-tooling.md',
+            '.mcp.json.example',
+            // Only written when the repo ships its own skills/<name>/SKILL.md.
+            'README.md',
+        ],
+        // Every output is a delimited-block upsert or a `.example` file — existing
+        // user content is never clobbered.
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const filesWritten = await installAiSetup(targetDir);
+            return { filesWritten };
+        },
+    },
+    {
+        target: 'claude-skill',
+        description: 'Install the repo-tooling Claude Code skill into .claude/skills/',
+        appliesTo: ['Claude skill'],
+        outputs: ['.claude/skills/repo-tooling.md'],
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('claude-skill', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'cursor-rules',
+        description: 'Install the repo-tooling rules for Cursor (.cursor/rules/repo-tooling.mdc)',
+        appliesTo: ['Cursor rules'],
+        outputs: ['.cursor/rules/repo-tooling.mdc'],
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const written = await installAgentRules(targetDir, 'cursor');
+            return { filesWritten: [written] };
+        },
+    },
+    {
+        target: 'copilot-instructions',
+        description: 'Install the repo-tooling rules for GitHub Copilot (.github/copilot-instructions.md)',
+        appliesTo: ['Copilot instructions'],
+        outputs: ['.github/copilot-instructions.md'],
+        // Upserts a delimited block — never clobbers the consumer's own instructions.
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const written = await installAgentRules(targetDir, 'copilot');
+            return { filesWritten: [written] };
+        },
+    },
+    {
+        target: 'agents-md',
+        description: 'Install the repo-tooling rules into AGENTS.md (universal agent instructions)',
+        appliesTo: ['AGENTS.md rules'],
+        outputs: ['AGENTS.md'],
+        // Upserts a delimited block — never clobbers existing AGENTS.md content.
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const written = await installAgentRules(targetDir, 'agents-md');
+            return { filesWritten: [written] };
+        },
+    },
+];

package/dist/base/git-identity.js

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * IANA-reserved domains that can never receive mail. This is what made #327
+ * unrecoverable: an address at one of these can never be verified as a
+ * secondary email, so the commits can never be re-linked without a history
+ * rewrite.
+ */
+const PLACEHOLDER_DOMAINS = ['example.com', 'example.org', 'example.net', 'invalid', 'test'];
+/**
+ * Suffixes of a machine-derived hostname. `.local` is mDNS (macOS default),
+ * `.matrix` is this user's LAN — both produced real commits in the #327 set.
+ */
+const HOSTNAME_SUFFIXES = ['.local', '.matrix', '.localhost', '.lan', '.home', '.internal'];
+/** Pure so the rules are testable without a git repo or a spawn. */
+export function classifyGitEmail(raw) {
+    const email = (raw ?? '').trim().toLowerCase();
+    if (email === '')
+        return 'unset';
+    // lastIndexOf: a quoted local part may legally contain '@'.
+    const at = email.lastIndexOf('@');
+    const domain = at === -1 ? '' : email.slice(at + 1);
+    // No '@' at all, or nothing either side of it — not an address.
+    if (domain === '' || at === 0)
+        return 'generated';
+    if (PLACEHOLDER_DOMAINS.some((d) => domain === d || domain.endsWith(`.${d}`))) {
+        return 'placeholder';
+    }
+    // A bare hostname has no dot at all (`richard@laptop`); the suffixes catch
+    // the ones that do (`richard@Richards-Mini.matrix`).
+    if (!domain.includes('.') || HOSTNAME_SUFFIXES.some((s) => domain.endsWith(s))) {
+        return 'generated';
+    }
+    return 'ok';
+}
+const DETAIL = {
+    unset: () => 'git user.email is not set — git will invent one from the hostname at commit time',
+    placeholder: (e) => `git user.email is a placeholder that can never receive mail: ${e}`,
+    generated: (e) => `git user.email looks machine-derived, not a real address: ${e}`,
+};
+const HINT = 'Commits made with this identity will not link to your forge account, and the address cannot be added as a verified secondary email to fix them retroactively (#327). Set a real one: `git config --global user.email you@yourdomain.com` — or per-repo, drop `--global`.';
+const CHECK = 'Git identity';
+const GIT_TIMEOUT_MS = 5_000;
+/** Never rejects; a missing or failing git resolves to null. */
+export const realGitExec = (args, cwd) => new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(v);
+    };
+    // Args are internal constants, never user free-text — shell:false keeps
+    // this injection-safe.
+    const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+    let stdout = '';
+    const timer = setTimeout(() => {
+        child.kill();
+        done(null);
+    }, GIT_TIMEOUT_MS);
+    child.stdout?.on('data', (d) => {
+        stdout += d;
+    });
+    child.on('close', (code) => done(code === 0 ? stdout.trim() : null));
+    child.on('error', () => done(null));
+});
+/**
+ * STATUS: a bad identity is never `drift` or `missing`, both of which exit 1.
+ * The identity belongs to whoever is running doctor, not to the repo — failing
+ * CI over the runner's git config would be noise the repo's author cannot fix
+ * by changing the repo. `optional-missing` reports it in gray and leaves the
+ * exit code alone.
+ */
+export async function checkGitIdentity(dir, exec) {
+    // Cheap gate: no .git → no commits to mis-attribute, and no spawn.
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        return { check: CHECK, status: 'ok', detail: 'not a git repository' };
+    }
+    // On a runner the identity is the bot's, so there is nothing to warn about
+    // and the warning would be permanent.
+    if (process.env.CI) {
+        return { check: CHECK, status: 'ok', detail: 'skipped on CI (identity is the runner’s)' };
+    }
+    const git = exec ?? ((args) => realGitExec(args, dir));
+    const email = await git(['config', '--get', 'user.email']);
+    const verdict = classifyGitEmail(email);
+    if (verdict === 'ok') {
+        return { check: CHECK, status: 'ok', detail: `git user.email is ${email}` };
+    }
+    return {
+        check: CHECK,
+        status: 'optional-missing',
+        detail: DETAIL[verdict](email ?? ''),
+        hint: HINT,
+    };
+}

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/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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.2.4",
+	"version": "3.2.5",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -46,6 +46,7 @@
 	"files": [
 		"dist/cli/**/*.js",
 		"dist/languages/**/*.js",
+		"dist/base/**/*.js",
 		"tooling/commitlint/commitlint.mjs",
 		"tooling/commitlint/commitlint.d.mts",
 		"tooling/esbuild/index.mjs",

package/tooling/github-actions/workflows/cloudflare-pages.yml

@@ -26,7 +26,7 @@ jobs:
           node-version-file: .nvmrc
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@v6
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile