@rtorcato/repo-tooling 2.59.0

package/AGENTS.md

@@ -0,0 +1,113 @@
+# AGENTS.md
+
+Orientation for coding agents working with `@rtorcato/repo-tooling`. Human-readable docs live at https://rtorcato.github.io/repo-tooling/.
+
+## What this is
+
+A one-package JavaScript / TypeScript tooling distribution. Ships every preset (TypeScript, Biome, ESLint, Prettier, Vitest, Jest, Commitlint, semantic-release, tsup, esbuild, Vite, Playwright) plus a CLI to scaffold and audit projects. Consumers get one install.
+
+**Swift** repos (detected via `Package.swift`) are covered end to end: `setup --preset swift-library` scaffolds a SwiftPM package, and `doctor`/`fix` run the language-agnostic checks plus SwiftLint / Periphery / `.gitignore` / `Package.swift`. Python and Perl are audit-only for now. See `src/languages/` — one directory per language module, `src/base/` for what's shared.
+
+## CLI surface (agent-friendly)
+
+Every command supports `--json` and a non-interactive mode. Combine with `--yes` for fully autonomous use.
+
+| Command | Non-interactive | JSON output | Use case |
+|---|---|---|---|
+| `setup --preset <name>` | ✅ | `--dry-run` only | Scaffold a new project. Presets: `library`, `web-app`, `node-api`, `nextjs-app`, `react-app`, `swift-library`. |
+| `setup --config <path>` | ✅ | `--dry-run` only | Scaffold with a full `ProjectConfig` JSON file. See `setup --config-schema`. |
+| `setup --config-schema` | ✅ | ✅ (JSON Schema) | Print the JSON Schema for `ProjectConfig`. Use to validate configs before scaffolding. |
+| `setup --dry-run` | ✅ | ✅ | Print resolved config + file list without writing. Pair with `--preset` or `--config`. |
+| `doctor --json` | ✅ | ✅ | Audit a project. Returns `{ directory, results: [{ check, status, detail, hint? }] }`. Status: `ok` / `drift` / `missing` / `optional-missing`. |
+| `fix --json --yes` | ✅ | ✅ | Walk every doctor finding, apply fixers. Returns `FixActionRecord[]` with `status: applied | dry-run | skipped | already-ok | unsupported`. |
+| `fix <target> --json --yes` | ✅ | ✅ | Apply one fixer. Targets from `list --json`. |
+| `fix --dry-run` | ✅ | ✅ | Print what each fixer would write without writing. Combine with `--json`. |
+| `list --json` | ✅ | ✅ | Enumerate the library's surface area. Each entry has `{ name, description, exports, fixTarget }`. |
+| `copy <name>` | ✅ | text only | Copy a single preset (`biome`, `tsconfig`) into the current directory. |
+
+## Recommended workflows
+
+### Scaffolding a new project from scratch
+
+```bash
+npx @rtorcato/repo-tooling setup --preset library -d ./my-lib --skip-install
+```
+
+For full control:
+
+```bash
+# 1. Get the schema
+npx @rtorcato/repo-tooling setup --config-schema > project-config.schema.json
+
+# 2. Write a config matching it
+cat > project.json <<EOF
+{
+  "projectName": "my-lib",
+  "projectType": "library",
+  "typescript": {"enabled": true, "config": "base"},
+  "linting": {"tool": "biome"},
+  "formatting": {"tool": "biome"},
+  "testing": {"framework": "vitest", "environment": "node"},
+  "gitHooks": true,
+  "commitLint": true,
+  "semanticRelease": true,
+  "securityAutomation": true,
+  "bundler": "tsup"
+}
+EOF
+
+# 3. Preview, then scaffold
+npx @rtorcato/repo-tooling setup --config project.json --dry-run
+npx @rtorcato/repo-tooling setup --config project.json -d ./my-lib --skip-install
+```
+
+### Auditing an existing project
+
+```bash
+# Get findings
+npx @rtorcato/repo-tooling doctor --json -d ./existing-repo > doctor.json
+
+# Apply every fixable finding (no prompts, no surprises)
+npx @rtorcato/repo-tooling fix --yes --json -d ./existing-repo > applied.json
+
+# Re-audit to confirm clean
+npx @rtorcato/repo-tooling doctor --json -d ./existing-repo
+```
+
+### Targeted fixes
+
+```bash
+# Apply one fixer from the list (run `list --json` for every target)
+npx @rtorcato/repo-tooling fix dependabot --yes --json
+npx @rtorcato/repo-tooling fix engines --yes --json
+npx @rtorcato/repo-tooling fix docs-site --yes --json   # scaffold a Docusaurus docs site under apps/docs
+npx @rtorcato/repo-tooling fix bun --yes --json         # Bun runtime/test config
+```
+
+## Drift policy (important)
+
+`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 (`engines`, `husky`, `package-json`) never overwrite — they add/merge — and use friendlier prompt wording. `fix --json` implies `--yes` (prompts would corrupt JSON output).
+
+## Source-of-truth files in the repo
+
+- `src/cli/commands/setup.ts` — `ProjectConfig` interface and the setup orchestrator
+- `src/cli/commands/setup-presets.ts` — preset definitions, JSON Schema, config validator, `computeFileList`
+- `src/cli/commands/doctor.ts` — all checks and the public `runDoctor(dir)` / `evaluateNodeVersion(version)` / `nextStepSuggestions(results)`
+- `src/cli/commands/fix.ts` — `Fixer` interface, fixer registry, `fixCommand`
+- `src/cli/commands/fix-targets.ts` — shared check → fix target map (used by both doctor's footer and fix's lookup)
+- `src/cli/generators/` — one file per concern (linting, testing, build, git, github-actions, security, misc)
+- `tooling/` — every shipped preset, mirrored 1:1 with `package.json` `exports`
+
+## Conventions in this repo
+
+- Conventional commits enforced via commitlint; header max 72 chars
+- Biome for lint + format (run via `pnpm exec biome check --config-path=tooling/biome/biome.json src scripts`)
+- Tests live alongside source in `tests/`; vitest with no separate config
+- semantic-release runs on push to `main`; `fix:` → patch, `feat:` → minor, `chore:` / `docs:` → no release
+
+## Pointers
+
+- Site index for LLMs: https://rtorcato.github.io/repo-tooling/llms.txt
+- Full CLI guide: https://rtorcato.github.io/repo-tooling/guides/cli/
+- For AI agents: https://rtorcato.github.io/repo-tooling/guides/for-ai-agents/
+- Source: https://github.com/rtorcato/repo-tooling

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Richard Torcato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+<picture>
+  <source media="(max-width: 640px)" srcset="./banner-mobile.png">
+  <img src="./banner.png" alt="repo-tooling banner" width="1600">
+</picture>
+
+<br>
+
+[![CI](https://github.com/rtorcato/repo-tooling/actions/workflows/ci.yml/badge.svg)](https://github.com/rtorcato/repo-tooling/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/@rtorcato%2Frepo-tooling.svg)](https://badge.fury.io/js/@rtorcato%2Frepo-tooling)
+[![npm downloads](https://img.shields.io/npm/dm/@rtorcato%2Frepo-tooling)](https://www.npmjs.com/package/@rtorcato/repo-tooling)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/@rtorcato/repo-tooling)](https://bundlephobia.com/package/@rtorcato/repo-tooling)
+[![Coverage](https://codecov.io/gh/rtorcato/repo-tooling/branch/main/graph/badge.svg)](https://codecov.io/gh/rtorcato/repo-tooling)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.
+
+
+Most tooling libraries give you one piece — just TypeScript configs, or just an ESLint preset. **repo-tooling** covers the entire lifecycle: TypeScript, Biome/ESLint, Vitest/Jest, Commitlint, Husky, Semantic Release, GitHub Actions CI, and supply-chain security (Dependabot + CodeQL) — all wired together. The interactive `setup` wizard scaffolds everything in one shot; `doctor` checks an existing project for drift; `fix` applies the missing pieces incrementally.
+
+**[Full documentation →](https://rtorcato.github.io/repo-tooling/)**
+
+> **Package manager: pnpm, by design.** Every generator scaffolds pnpm
+> workflows, workspace files, and scripts. repo-tooling targets pnpm only for
+> now — npm, yarn, and Bun aren't generated.
+
+## Start a new project
+
+Interactive wizard — answers every prompt, scaffolds the whole project:
+
+```bash
+npx @rtorcato/repo-tooling setup
+```
+
+Non-interactive — scaffold from a named preset in one shot (CI-friendly):
+
+```bash
+npx @rtorcato/repo-tooling setup --preset library -d ./my-lib --skip-install
+# presets: library | web-app | node-api | nextjs-app | react-app | swift-library
+```
+
+`swift-library` scaffolds a SwiftPM package (manifest, sources, tests, SwiftLint,
+Periphery, macOS CI) instead of an npm one — see the
+[Swift guide](https://rtorcato.github.io/repo-tooling/guides/swift).
+
+Just one config file? Use `copy`:
+
+```bash
+npx @rtorcato/repo-tooling copy biome        # → biome.json
+npx @rtorcato/repo-tooling copy tsconfig     # → tsconfig.json
+npx @rtorcato/repo-tooling copy changesets   # → .changeset/config.json
+npx @rtorcato/repo-tooling copy oxlint       # → .oxlintrc.json
+npx @rtorcato/repo-tooling copy claude-skill # → .claude/skills/repo-tooling.md
+```
+
+**Already have a project?** Don't rerun `setup` — use `doctor` + `fix`:
+
+```bash
+npx @rtorcato/repo-tooling doctor   # find what's missing or drifted
+npx @rtorcato/repo-tooling fix      # apply scaffolders, prompting per item
+```
+
+See the [Getting Started guide](https://rtorcato.github.io/repo-tooling/guides/getting-started/) for the full walkthrough.
+
+## Commands
+
+| Command | What it does | Example |
+| --- | --- | --- |
+| `setup` | Interactive wizard that scaffolds a whole new project (add `--preset` to run non-interactively). | `npx @rtorcato/repo-tooling setup` |
+| `list` | List every tooling configuration this package can scaffold (`--json` for machine output). | `npx @rtorcato/repo-tooling list` |
+| `copy <config>` | Copy a single config file into the current project. | `npx @rtorcato/repo-tooling copy biome` |
+| `doctor` | Diagnose an existing project for missing or drifted tooling. | `npx @rtorcato/repo-tooling doctor` |
+| `fix [target]` | Apply scaffolders for what `doctor` flagged (`--yes`, `--dry-run`, `--diff`). | `npx @rtorcato/repo-tooling fix` |
+
+Every command takes `-d, --directory <path>`; run any with `--help` for its full flags. Run `list` (or `list --json`) for the full set of `fix` targets — it's the source of truth. Notable ones include `fix docs-site` (scaffold a [Docusaurus docs site](https://rtorcato.github.io/repo-tooling/guides/docs-site/)) and `fix bun` (Bun runtime config).
+
+## The `.repo-tooling.json` lockfile
+
+An **optional** manifest that records the tooling choices you adopted. Nothing
+reads it at build/lint/test time — it exists only so `doctor` can tell an
+*intentional opt-out* from *drift*. repo-tooling works fine without it, which is
+why `doctor` reports a missing one as `not configured`, not an error.
+
+Generate or refresh it from what's currently on disk:
+
+```bash
+npx @rtorcato/repo-tooling fix lockfile
+```
+
+**It's the only config file you need.** Don't keep a separate hand-authored
+`.repo-tooling.config.json` next to it — the lockfile already embeds the full
+`ProjectConfig` under `config`, and `setup --config` accepts the lockfile
+directly, so you can re-run a non-interactive setup from it:
+
+```bash
+npx @rtorcato/repo-tooling setup --config .repo-tooling.json
+```
+
+Each `config.*` key mirrors a setup answer — see the
+[schema](https://rtorcato.github.io/repo-tooling/schemas/lockfile.json) for the
+full field reference. The keys `doctor` acts on:
+
+- `typescript.enabled` / `typescript.config` — `base` \| `react` \| `next` \| `node` \| `express`
+- `linting.tool` — `biome` \| `eslint` \| `both` \| `none`
+- `formatting.tool` — `biome` \| `prettier` \| `none`
+- `testing.framework` — `vitest` \| `jest` \| `playwright` \| `none`
+- `gitHooks`, `commitLint`, `semanticRelease` — booleans
+- `securityAutomation` — boolean (Dependabot + CodeQL)
+- `bundler` — `tsup` \| `esbuild` \| `vite` \| `none`
+- `aiSetup` — boolean (AGENTS.md, CLAUDE.md, Cursor/Copilot rules)
+
+**How opt-outs actually work.** When the lockfile records that you declined an
+*optional* tool (e.g. `securityAutomation: false`), `doctor` demotes that check
+from `not configured` to `ok — intentionally declined` instead of nagging you to
+add it. This applies only to optional checks — it does **not** silence *drift*:
+if a config you adopted diverges from the shared base (say your `tsconfig.json`
+extends a different preset), `doctor` still flags it, because drift is a mismatch
+in a tool you're using, not an opt-out. There's no field to suppress drift today.
+
+**Adoption vs. standalone.** `fix lockfile` infers adoption from what's on disk,
+so on a repo that deliberately runs standalone configs (no
+`@rtorcato/repo-tooling` dependency) it can record `typescript.config: "base"` and
+friends — asserting you extend the shared bases when you don't. If you're not
+adopting repo-tooling's configs, skip the lockfile; it won't stop the `extends`
+drift warnings.
+
+## AI agent rules
+
+The package ships rules that teach AI coding agents to drive the CLI
+(`doctor` / `fix` / `setup`) non-interactively. Install for your agent — all
+generated from one source, so guidance never drifts between them:
+
+```bash
+npx @rtorcato/repo-tooling fix claude-skill --yes           # → .claude/skills/repo-tooling.md
+npx @rtorcato/repo-tooling fix cursor-rules --yes           # → .cursor/rules/repo-tooling.mdc
+npx @rtorcato/repo-tooling fix copilot-instructions --yes   # → .github/copilot-instructions.md
+npx @rtorcato/repo-tooling fix agents-md --yes              # → AGENTS.md
+```
+
+`copilot-instructions` and `agents-md` upsert a delimited block, so your own
+content in those shared files is never clobbered. Re-running updates the block
+in place on upgrade.
+
+Prefer a symlink that auto-syncs the Claude skill on every upgrade?
+
+```bash
+mkdir -p .claude/skills
+ln -sf ../../node_modules/@rtorcato/repo-tooling/tooling/claude/repo-tooling.md \
+  .claude/skills/repo-tooling.md
+```
+
+### Use with Claude Code (plugin)
+
+This repo is also a self-hosted Claude Code marketplace. Install the plugin to
+get two skills — `repo-tooling` (adopt/audit the presets via the CLI) and
+`npm-publish` (the family's release rules) — in any session:
+
+```
+/plugin marketplace add rtorcato/repo-tooling
+/plugin install repo-tooling@repo-tooling
+```
+
+### Use with other AI tools (Cursor / Copilot / Codex)
+
+[`AGENTS.md`](AGENTS.md) at the repo root carries the same guidance in the
+cross-tool convention many agents read, and ships in the npm tarball so tools
+scanning `node_modules/@rtorcato/repo-tooling` can find it.
+
+## What's new
+
+See [CHANGELOG.md](CHANGELOG.md) for the full history.
+
+## Related packages
+
+- [@rtorcato/js-common](https://github.com/rtorcato/js-common) — General TypeScript/JS utilities (strings, dates, numbers, async, errors)
+- [@rtorcato/browser-common](https://github.com/rtorcato/browser-common) — Browser Web API wrappers (clipboard, observers, storage, etc.)
+
+## Roadmap
+
+Direction and progress are tracked entirely on GitHub — see the
+[milestones](https://github.com/rtorcato/repo-tooling/milestones) and
+[open issues](https://github.com/rtorcato/repo-tooling/issues).
+
+## Contributing
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+<!-- js-tooling:skills:start -->
+## Install the skills (`npx skills`)
+
+Any agent that supports the [`skills`](https://www.npmjs.com/package/skills) CLI can install this repo's skills straight from GitHub — no clone, no package install:
+
+```bash
+npx skills add https://github.com/rtorcato/repo-tooling --skill repo-tooling
+npx skills add https://github.com/rtorcato/repo-tooling --skill npm-publish
+```
+<!-- js-tooling:skills:end -->

package/dist/cli/commands/doctor.js

@@ -0,0 +1,336 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import { resolveLanguageModule } from '../../languages/registry.js';
+import { SWIFT_GIT_HOOKS, runSwiftChecks } from '../../languages/swift/checks.js';
+import { detectLanguage } from '../utils/detect-language.js';
+import { checkGitHubSettings } from '../../base/github-settings.js';
+import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
+import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
+import { checkAiSetup, checkCodeowners, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
+import { allDeps, checkAreTheTypesWrong, checkDocsSite, checkEnginesNode, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
+export { evaluateNodeVersion };
+const PACKAGE = '@rtorcato/repo-tooling';
+// Detects the broken-release-on-protected-main footgun: a workflow that runs
+// semantic-release but only hands it GITHUB_TOKEN, which can't push the version
+// commit + tag past branch protection. The fix is an admin PAT (RELEASE_TOKEN)
+// with a GITHUB_TOKEN fallback.
+async function checkReleaseToken(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir))) {
+        return { check: 'Release token', 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 (/RELEASE_TOKEN/.test(content)) {
+                return {
+                    check: 'Release token',
+                    status: 'ok',
+                    detail: `${f} uses RELEASE_TOKEN (with GITHUB_TOKEN fallback)`,
+                };
+            }
+            return {
+                check: 'Release token',
+                status: 'drift',
+                detail: `${f} runs semantic-release with bare GITHUB_TOKEN`,
+                hint: 'GITHUB_TOKEN cannot push to a protected main. Set the checkout `token:` and the semantic-release `GITHUB_TOKEN` env to `${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}` and add a RELEASE_TOKEN admin PAT secret',
+            };
+        }
+        return {
+            check: 'Release token',
+            status: 'optional-missing',
+            detail: 'no semantic-release workflow found',
+        };
+    }
+    catch {
+        return {
+            check: 'Release token',
+            status: 'optional-missing',
+            detail: 'unable to read .github/workflows/',
+        };
+    }
+}
+// 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.
+async function checkNpmOidcPublish(dir, pkg) {
+    const check = 'npm OIDC publish';
+    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' };
+    }
+    catch {
+        return { check, status: 'optional-missing', detail: 'unable to read .github/workflows/' };
+    }
+}
+function checkLockfile(lock) {
+    if (!lock) {
+        return {
+            check: 'lockfile',
+            status: 'optional-missing',
+            detail: 'no .repo-tooling.json — doctor cannot tell intentional opt-outs from drift',
+            hint: 'Run `npx @rtorcato/repo-tooling fix lockfile` to record current choices',
+        };
+    }
+    if (lock.version > LOCKFILE_VERSION) {
+        return {
+            check: 'lockfile',
+            status: 'drift',
+            detail: `.repo-tooling.json version ${lock.version} is newer than this CLI supports (v${LOCKFILE_VERSION})`,
+            hint: 'Upgrade @rtorcato/repo-tooling to a release that supports this lockfile version',
+        };
+    }
+    return {
+        check: 'lockfile',
+        status: 'ok',
+        detail: `.repo-tooling.json v${lock.version} (written by ${lock.writtenBy})`,
+    };
+}
+// Lockfile-driven demotion: if the lock records an intentional opt-out for a
+// check that's currently optional-missing, demote it to ok with a clear detail.
+function demoteDeclined(results, lock) {
+    if (!lock)
+        return results;
+    return results.map((r) => {
+        if (r.status !== 'optional-missing')
+            return r;
+        if (!declinedInLock(lock, r.check))
+            return r;
+        return {
+            check: r.check,
+            status: 'ok',
+            detail: 'intentionally declined (.repo-tooling.json)',
+        };
+    });
+}
+// The language-agnostic checks (src/base): repo hygiene, git hooks, CI,
+// security, and GitHub repo-settings that apply to any repo regardless of
+// language. Declared once and run for every project — a language module layers
+// its own checks on top rather than re-listing these.
+async function runBaseChecks(dir, lock, opts) {
+    const results = [];
+    results.push(checkLockfile(lock));
+    results.push(await checkEditorConfig(dir));
+    results.push(await checkFile(dir, COMMITLINT_FILE_CHECK));
+    if (opts.hooks) {
+        results.push(await checkGitHooks(dir, opts.hooks));
+        results.push(await checkPrePushHook(dir, opts.hooks));
+    }
+    results.push(await checkGitHubActions(dir));
+    results.push(await checkDependabot(dir));
+    results.push(await checkCodeQL(dir));
+    // GitHub repo-settings drift (branch protection, merge settings, workflow
+    // permissions). Read-only; self-skips as `ok` outside a live GitHub repo.
+    results.push(...(await checkGitHubSettings(dir)));
+    results.push(await checkGitLabCI(dir));
+    results.push(await checkCodeowners(dir));
+    results.push(await checkCommunityHealth(dir));
+    results.push(await checkAiSetup(dir));
+    results.push(await checkReadmeBadges(dir, opts.badges.audience, opts.badges.fixTarget));
+    results.push(await checkCoverageUpload(dir));
+    return results;
+}
+export async function runDoctor(dir) {
+    const targetDir = path.resolve(dir);
+    const lock = await readLockfile(targetDir);
+    // Per-module dispatch (#285): the base checks (repo hygiene, CI, security,
+    // GitHub settings) apply to any repo and run for every language. A supported
+    // module layers its own checks on top; an unsupported one (Swift/Perl/Python
+    // until their modules land) still gets the full base suite instead of the old
+    // wholesale skip. 'unknown' (bare dir mid-setup) resolves to JS so a fresh
+    // repo runs the full suite.
+    const language = await detectLanguage(targetDir);
+    const languageModule = resolveLanguageModule(language);
+    if (!languageModule.supported) {
+        const results = [
+            {
+                check: 'language',
+                status: 'ok',
+                detail: `detected ${languageModule.label} — running language-agnostic checks; ${languageModule.label}-specific checks land with its module (#139)`,
+            },
+            // hooks: null — nothing here encodes a Python/Perl hook convention yet,
+            // and guessing one would nag every repo with a fix target that doesn't
+            // exist. #289/#290 fill it in.
+            ...(await runBaseChecks(targetDir, lock, {
+                hooks: null,
+                badges: { audience: 'public', fixTarget: null },
+            })),
+        ];
+        return demoteDeclined(results, lock);
+    }
+    // Swift suite (#286): base checks plus the module's own. Swift repos have no
+    // package.json, so nothing JS-shaped runs.
+    if (languageModule.id === 'swift') {
+        const results = [
+            {
+                check: 'language',
+                status: 'ok',
+                detail: 'detected Swift (Package.swift)',
+            },
+            ...(await runBaseChecks(targetDir, lock, {
+                hooks: SWIFT_GIT_HOOKS,
+                // A SwiftPM package is distributed as public source over git tags, so
+                // 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 },
+            })),
+            ...(await runSwiftChecks(targetDir)),
+        ];
+        return demoteDeclined(results, lock);
+    }
+    // JS suite: the module's own checks, then the shared base ones. Only the
+    // JS-shaped checks are listed here — re-listing the base suite is what made
+    // any new base check silently skip JS repos (#309).
+    const pkg = await readPackageJson(targetDir);
+    const results = [];
+    results.push(evaluateNodeVersion(process.version));
+    results.push(checkPackageJson(pkg));
+    results.push(checkEnginesNode(pkg));
+    results.push(await checkVscodeExtensions(targetDir));
+    results.push(await checkNodeVersionPin(targetDir));
+    results.push(await checkNodeVersionConsistency(targetDir, pkg));
+    for (const spec of FILE_CHECKS) {
+        results.push(await checkFile(targetDir, spec));
+    }
+    results.push(await checkLintStaged(targetDir, pkg));
+    results.push(await checkVerifyScript(targetDir, pkg));
+    results.push(await checkSemanticRelease(targetDir, pkg));
+    results.push(await checkKnip(targetDir, pkg));
+    results.push(await checkSizeLimit(targetDir, pkg));
+    results.push(await checkReleaseToken(targetDir));
+    results.push(await checkNpmOidcPublish(targetDir, pkg));
+    results.push(await checkTypedoc(targetDir, pkg));
+    results.push(await checkAreTheTypesWrong(targetDir, pkg));
+    results.push(await checkPublint(targetDir, pkg));
+    results.push(await checkTreeshakeSetup(targetDir, pkg));
+    results.push(await checkPnpmWorkspace(targetDir, pkg));
+    // Turborepo is monorepo-only — only surface the check when a workspace exists.
+    if (await fs.pathExists(path.join(targetDir, 'pnpm-workspace.yaml'))) {
+        results.push(await checkTurborepo(targetDir));
+    }
+    // Docs site is opt-in — only surface the check when a Docusaurus site exists.
+    const docsAppDir = await findDocsAppDir(targetDir);
+    if (docsAppDir) {
+        results.push(await checkDocsSite(targetDir, docsAppDir));
+    }
+    // Tailwind is opt-in — only surface the check when the repo actually depends on it.
+    if ('tailwindcss' in allDeps(pkg)) {
+        results.push(await checkTailwind(targetDir, pkg));
+    }
+    results.push(...(await runBaseChecks(targetDir, lock, {
+        hooks: jsGitHooksProfile(pkg),
+        badges: { audience: jsBadgeAudience(pkg), fixTarget: 'badges' },
+    })));
+    return demoteDeclined(results, lock);
+}
+const STATUS_ICONS = {
+    ok: chalk.green('✅'),
+    drift: chalk.yellow('⚠️ '),
+    missing: chalk.red('❌'),
+    'optional-missing': chalk.gray('➖'),
+};
+function statusLabel(status) {
+    switch (status) {
+        case 'ok':
+            return chalk.green('ok');
+        case 'drift':
+            return chalk.yellow('drift');
+        case 'missing':
+            return chalk.red('missing');
+        case 'optional-missing':
+            return chalk.gray('not configured');
+    }
+}
+const MAX_NEXT_STEP_SUGGESTIONS = 8;
+export function nextStepSuggestions(results, language) {
+    const fixable = results.filter((r) => r.status === 'drift' || r.status === 'missing' || r.status === 'optional-missing');
+    const lines = [];
+    let overflow = 0;
+    for (const r of fixable) {
+        const target = getFixTargetForCheck(r.check, language);
+        if (!target)
+            continue;
+        if (lines.length >= MAX_NEXT_STEP_SUGGESTIONS) {
+            overflow++;
+            continue;
+        }
+        const verb = r.status === 'drift' ? 'align' : 'scaffold';
+        lines.push(`Run \`npx @rtorcato/repo-tooling fix ${target}\` to ${verb} ${r.check}`);
+    }
+    if (overflow > 0) {
+        lines.push(`...and ${overflow} more — run \`npx @rtorcato/repo-tooling fix\` to walk all findings`);
+    }
+    else if (lines.length > 0) {
+        lines.push('Run `npx @rtorcato/repo-tooling fix` to walk all findings interactively');
+    }
+    return lines;
+}
+export function summarize(results) {
+    return {
+        ok: results.filter((r) => r.status === 'ok').length,
+        drift: results.filter((r) => r.status === 'drift').length,
+        missing: results.filter((r) => r.status === 'missing').length,
+        optionalMissing: results.filter((r) => r.status === 'optional-missing').length,
+    };
+}
+export async function doctorCommand(options = {}) {
+    const dir = options.directory ?? process.cwd();
+    const results = await runDoctor(dir);
+    if (options.json) {
+        console.log(JSON.stringify({ directory: path.resolve(dir), results }, null, 2));
+    }
+    else {
+        console.log(chalk.cyan(`\n🩺 Diagnosing ${path.resolve(dir)} against ${PACKAGE} presets...\n`));
+        for (const r of results) {
+            console.log(`  ${STATUS_ICONS[r.status]} ${chalk.bold(r.check)} — ${statusLabel(r.status)}`);
+            console.log(`     ${chalk.gray(r.detail)}`);
+            if (r.hint && r.status !== 'ok') {
+                console.log(`     ${chalk.dim('hint:')} ${chalk.dim(r.hint)}`);
+            }
+        }
+        const summary = summarize(results);
+        console.log();
+        console.log(`  Summary: ${chalk.green(`${summary.ok} ok`)}, ${chalk.yellow(`${summary.drift} drift`)}, ${chalk.red(`${summary.missing} missing`)}, ${chalk.gray(`${summary.optionalMissing} not configured`)}\n`);
+        const suggestions = nextStepSuggestions(results, await detectLanguage(dir));
+        if (suggestions.length > 0) {
+            console.log(chalk.bold('  Next steps:'));
+            for (const s of suggestions) {
+                console.log(`    ${chalk.gray('-')} ${s}`);
+            }
+            console.log();
+        }
+    }
+    const summary = summarize(results);
+    const exitCode = summary.drift > 0 || summary.missing > 0 ? 1 : 0;
+    process.exitCode = exitCode;
+}