@rtorcato/repo-tooling 3.12.1 → 3.13.1

package/README.md

@@ -175,7 +175,7 @@ ln -sf ../../node_modules/@rtorcato/repo-tooling/tooling/claude/repo-tooling.md
 
 This repo is also a self-hosted Claude Code marketplace. Install the plugin to
 get three skills — `repo-tooling` (adopt/audit the presets via the CLI),
-`npm-publish` (the family's release rules) and `ai-issue-loop` (the label-driven
+`npm-publish` (never hand-cut a release) and `ai-issue-loop` (the label-driven
 issue → PR pipeline) — in any session:
 
 ```

package/dist/cli/commands/doctor.js

@@ -18,7 +18,7 @@ import { checkGitIdentity } from '../../base/git-identity.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
 import { checkAiSetup, checkBrand, checkCodeowners, checkClaudeSkills, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
-import { allDeps, checkAreTheTypesWrong, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
+import { allDeps, checkAreTheTypesWrong, checkBiome, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, 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
@@ -295,7 +295,10 @@ export async function runDoctor(dir) {
     results.push(await checkNodeVersionPin(targetDir));
     results.push(await checkNodeVersionConsistency(targetDir, pkg));
     for (const spec of FILE_CHECKS) {
-        results.push(await checkFile(targetDir, spec));
+        // Biome is the one spec that needs the directory as well as the file
+        // contents — it compares the `$schema` version against the installed
+        // CLI (#424). Dispatched here so it keeps its place in the output.
+        results.push(spec.check === 'Biome' ? await checkBiome(targetDir) : await checkFile(targetDir, spec));
     }
     results.push(await checkLintStaged(targetDir, pkg));
     results.push(await checkVerifyScript(targetDir, pkg));

package/dist/cli/generators/linting.js

@@ -48,6 +48,18 @@ async function readJsonOrNull(filepath) {
         return null;
     }
 }
+/**
+ * The `@biomejs/biome` actually installed under `targetDir`, or null when
+ * node_modules isn't populated. This is the binary that will parse the config
+ * and emit the schema-mismatch warning, so it is the only version worth
+ * comparing a written `$schema` against — a declared range like `^2.5.0` says
+ * nothing about which 2.x resolved (#424).
+ */
+export async function installedBiomeVersion(targetDir) {
+    const installed = await readJsonOrNull(path.join(targetDir, 'node_modules', '@biomejs', 'biome', 'package.json'));
+    const match = typeof installed?.version === 'string' ? /(\d+\.\d+\.\d+)/.exec(installed.version) : null;
+    return match?.[1] ?? null;
+}
 /**
  * The Biome version the scaffolded `$schema` URL should name (#363).
  *
@@ -59,20 +71,18 @@ async function readJsonOrNull(filepath) {
  * best statement of intent when node_modules isn't populated yet.
  */
 export async function resolveBiomeSchemaVersion(targetDir) {
-    const installed = await readJsonOrNull(path.join(targetDir, 'node_modules', '@biomejs', 'biome', 'package.json'));
+    const installed = await installedBiomeVersion(targetDir);
+    if (installed)
+        return installed;
     const pkg = await readJsonOrNull(path.join(targetDir, 'package.json'));
     const deps = {
         ...(pkg?.dependencies ?? {}),
         ...(pkg?.devDependencies ?? {}),
     };
-    // Both an exact version ("2.5.7") and a range ("^2.5.0") carry the x.y.z we
-    // need, so one pattern covers every source.
-    for (const candidate of [installed?.version, deps['@biomejs/biome']]) {
-        const match = typeof candidate === 'string' ? /(\d+\.\d+\.\d+)/.exec(candidate) : null;
-        if (match?.[1])
-            return match[1];
-    }
-    return BIOME_SCHEMA_FALLBACK;
+    // A range ("^2.5.0") carries the x.y.z we need just as an exact version does.
+    const declared = deps['@biomejs/biome'];
+    const match = typeof declared === 'string' ? /(\d+\.\d+\.\d+)/.exec(declared) : null;
+    return match?.[1] ?? BIOME_SCHEMA_FALLBACK;
 }
 /**
  * The thin pointer config — the same shape this repo dogfoods. `fix biome` used

package/dist/cli/utils/copy-preset.js

@@ -82,6 +82,11 @@ export const PRESETS = {
         desc: 'Claude Code skill for driving the repo-tooling CLI',
         legacyTarget: '.claude/skills/js-tooling.md',
     },
+    'claude-sync-agents': {
+        source: 'tooling/claude/sync-agents.mjs',
+        target: 'scripts/sync-agents.mjs',
+        desc: 'Canonical SKILL.md → AGENTS.md sync script (zero-config; --check mode for CI)',
+    },
     'mcp-example': {
         source: 'tooling/mcp/mcp.json.example',
         target: '.mcp.json.example',

package/dist/languages/js/checks.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
-import { hookHasUncommented } from '../../base/checks.js';
+import { checkFile, hookHasUncommented } from '../../base/checks.js';
+import { installedBiomeVersion } from '../../cli/generators/linting.js';
 import { CLAUDE_SETTINGS_FILE, readClaudeSettings, workspaceSymlinkDirs, worktreeSymlinkDirs, } from '../../cli/generators/agent-rules.js';
 import { WORKSPACE_FILE, dependsOnEsbuild, familyGlob, missingPnpmSettings, } from '../../cli/generators/pnpm-workspace.js';
 const PACKAGE = '@rtorcato/repo-tooling';
@@ -152,6 +153,54 @@ function matchesTsConfig(contents) {
         rootDir.includes('${configDir}') &&
         TS_PRESET_STRICTNESS.every((key) => compilerOptions[key] === true));
 }
+export const BIOME_FILE_CHECK = {
+    check: 'Biome',
+    candidates: ['biome.json', 'biome.jsonc'],
+    expected: `extends "${PACKAGE}/biome" or inlines the preset, with the linter on`,
+    matcher: matchesBiomeConfig,
+    optional: true,
+    hint: 'Run `npx @rtorcato/repo-tooling fix biome` to scaffold',
+};
+/**
+ * The Biome check plus the one thing a contents-only matcher can't see: whether
+ * the `$schema` URL still names the Biome that will read it (#424).
+ *
+ * `fix biome` writes the URL from the version resolved at scaffold time, and
+ * nothing re-checked it afterwards — so once the repo's Biome moved on, every
+ * single invocation (the pre-commit hook included) printed "The configuration
+ * schema version does not match the CLI version", while doctor stayed clean.
+ *
+ * Compared against the *installed* package only, never the declared range: an
+ * exact match is what Biome itself demands, and `^2.5.0` doesn't say which 2.x
+ * resolved. With no node_modules there is nothing to be wrong about, so the
+ * check says nothing rather than guessing.
+ */
+export async function checkBiome(dir) {
+    const result = await checkFile(dir, BIOME_FILE_CHECK);
+    if (result.status !== 'ok')
+        return result;
+    const installed = await installedBiomeVersion(dir);
+    if (!installed)
+        return result;
+    // The same candidate checkFile settled on — first one that exists wins.
+    for (const candidate of BIOME_FILE_CHECK.candidates) {
+        const filepath = path.join(dir, candidate);
+        if (!(await fs.pathExists(filepath)))
+            continue;
+        const url = readSchemaUrl(await fs.readFile(filepath, 'utf8'));
+        const targeted = url?.includes('biomejs.dev') ? schemaUrlVersion(url)?.join('.') : null;
+        if (targeted && targeted !== installed) {
+            return {
+                check: BIOME_FILE_CHECK.check,
+                status: 'drift',
+                detail: `${candidate} targets Biome ${targeted} but @biomejs/biome ${installed} is installed`,
+                hint: 'Run `npx @rtorcato/repo-tooling fix biome` to rewrite the $schema URL',
+            };
+        }
+        return result;
+    }
+    return result;
+}
 export const FILE_CHECKS = [
     {
         check: 'TypeScript',
@@ -160,14 +209,7 @@ export const FILE_CHECKS = [
         matcher: matchesTsConfig,
         hint: 'Run `npx @rtorcato/repo-tooling fix tsconfig` to scaffold',
     },
-    {
-        check: 'Biome',
-        candidates: ['biome.json', 'biome.jsonc'],
-        expected: `extends "${PACKAGE}/biome" or inlines the preset, with the linter on`,
-        matcher: matchesBiomeConfig,
-        optional: true,
-        hint: 'Run `npx @rtorcato/repo-tooling fix biome` to scaffold',
-    },
+    BIOME_FILE_CHECK,
     {
         check: 'ESLint',
         candidates: ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'],
@@ -685,6 +727,10 @@ export async function checkSizeLimit(dir, pkg) {
         hint: 'Add `size-limit` to enforce bundle-size budgets in CI for library projects',
     };
 }
+/** Changesets is in use when its config file is present. */
+export function usesChangesets(dir) {
+    return fs.pathExists(path.join(dir, '.changeset', 'config.json'));
+}
 const SEMANTIC_RELEASE_FILES = [
     '.releaserc',
     '.releaserc.json',
@@ -714,7 +760,7 @@ export async function checkSemanticRelease(dir, pkg) {
             break;
         }
     }
-    const hasChangesets = await fs.pathExists(path.join(dir, '.changeset', 'config.json'));
+    const hasChangesets = await usesChangesets(dir);
     const hasReleasePlease = await fs.pathExists(path.join(dir, 'release-please-config.json'));
     const hasSemanticRelease = inPkg || !!configFile;
     // Conflict: more than one of {semantic-release, Changesets, Release Please}.
@@ -1205,9 +1251,14 @@ export async function findDocsAppDir(dir) {
 export async function checkDocsSite(dir, docsAppDir) {
     const check = 'Docs site';
     const deltas = [];
+    // sync-changelog pumps a root CHANGELOG.md into the site — a semantic-release
+    // shape. Changesets writes per-package changelogs and leaves the (private)
+    // root package without one, so don't require the script there (#425). If a
+    // Changesets repo keeps the script anyway, it still has to be wired.
     const syncPath = path.join(dir, 'scripts', 'sync-changelog.mjs');
     if (!(await fs.pathExists(syncPath))) {
-        deltas.push('scripts/sync-changelog.mjs missing');
+        if (!(await usesChangesets(dir)))
+            deltas.push('scripts/sync-changelog.mjs missing');
     }
     else {
         const pkgPath = path.join(dir, docsAppDir, 'package.json');

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.12.1",
+	"version": "3.13.1",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -100,6 +100,7 @@
 		"tooling/semantic-release/*.mjs",
 		"tooling/semantic-release/*.d.mts",
 		"tooling/claude/*.md",
+		"tooling/claude/*.mjs",
 		"tooling/mcp/mcp.json.example",
 		"tooling/swift/*.yml",
 		"tooling/swift/*.json",

package/skills/ai-issue-loop/SKILL.md

@@ -694,6 +694,16 @@ Then spawn a background implementer agent:
 > 3. Read the repo's `CLAUDE.md` and obey it — especially any pre-commit build
 >    step or committed build output.
 > 4. Do the work. Conventional Commits within the branch.
+>
+>    **Do not run `pnpm install`.** This worktree's `node_modules` is a symlink to
+>    the main checkout, so pnpm sees a foreign directory it must purge first and
+>    aborts with `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`. Dependencies are
+>    already present — run tests, lint and build directly. If the work *is* a
+>    dependency change, `pnpm install --lockfile-only` updates `pnpm-lock.yaml`
+>    without touching `node_modules`. When that leaves a verification step you
+>    cannot run, say so in the PR body — name the command you could not run and
+>    why — so the reviewer knows CI is the only check on it rather than assuming
+>    you ran it.
 > 5. Push and open the PR. The title must be a Conventional Commit — it becomes
 >    the squash subject on `main` and, in repos using semantic-release, decides
 >    whether a release goes out at all. Body must contain `Closes #<N>`.

package/skills/npm-publish/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: npm-publish
-description: Use before releasing or publishing any @rtorcato/* package (repo-tooling and the whole family publish the same way). Triggers on "publish", "cut a release", "bump the version", "tag a release", "npm publish", "how do releases work here". The hard rule — releases are automated by semantic-release on merge to main; an agent must NEVER run `npm publish`, `npm version`, or `git tag`, or hand-edit the version in package.json. NOT for the day-to-day tooling audit/fix flow — that's the repo-tooling skill.
+description: Use before releasing or publishing any package in a repo set up by @rtorcato/repo-tooling. Triggers on "publish", "cut a release", "bump the version", "tag a release", "npm publish", "how do releases work here". The hard rule — releases are automated by the repo's release tool (semantic-release, Changesets, or Release Please); an agent must NEVER run `npm publish`, `npm version`, or `git tag`, or hand-edit the version in package.json. NOT for the day-to-day tooling audit/fix flow — that's the repo-tooling skill.
 ---
 
 # npm-publish
 
-Every `@rtorcato/*` package releases through **semantic-release on push to `main`**.
-Versioning, the git tag, the GitHub release, the CHANGELOG, and the npm publish are
-all derived from the commit history. There is no manual release step.
+A repo set up by `@rtorcato/repo-tooling` releases through **automation on merge to
+`main`** — one of semantic-release, Changesets, or Release Please. Versioning, the
+git tag, the GitHub release, the CHANGELOG, and the npm publish all come from that
+pipeline. There is no manual release step under any of them.
 
 ## The rule
 
@@ -17,31 +18,78 @@ all derived from the commit history. There is no manual release step.
 - `npm version` (or editing `"version"` in `package.json`)
 - `git tag` / pushing tags
 - hand-editing `CHANGELOG.md`
+- merging the "Version Packages" PR (Changesets) or the release PR (Release Please) —
+  that merge *is* the publish, so it is the human's release decision, not yours
 
-If asked to "release" or "bump the version", the correct action is to land a
-**conventional commit** on `main` (via PR) and let the pipeline do the rest.
+This holds for all three tools. Only the "what to do instead" differs, so first
+work out which tool the repo uses.
 
-## How a release actually happens
+## Which release tool is this repo on?
 
-1. Work on a branch; commit with Conventional Commits (header ≤ 100 chars).
-2. Open a PR; merge to `main` after review + green CI.
-3. semantic-release runs on `main` and decides the bump from the commits:
-   - `fix:` → patch
-   - `feat:` → minor
-   - `feat!:` / `BREAKING CHANGE:` → major
-   - `chore:` / `docs:` / `refactor:` / `test:` → **no release**
-4. It writes the version, tag, GitHub release, CHANGELOG, and publishes to npm.
+Check the repo root, in this order — these are the same signals the CLI's
+`doctor` check uses (`usesChangesets` / `checkSemanticRelease` in
+`src/languages/js/checks.ts`):
+
+| Signal | Tool |
+|---|---|
+| `.changeset/config.json` exists | **Changesets** |
+| `release-please-config.json` exists | **Release Please** |
+| `.releaserc*` / `release.config.*` exists, or a `"release"` key in `package.json` | **semantic-release** |
+
+Or just ask the tooling: `npx @rtorcato/repo-tooling doctor --json` reports the
+`semantic-release` check as ok with a detail naming the tool actually in use.
+
+If more than one is configured that's drift, not a choice — stop and flag it.
+
+## What to do instead, per tool
+
+### semantic-release
+
+The bump is derived from the commit history, so the commit type *is* the release
+decision:
+
+- `fix:` → patch
+- `feat:` → minor
+- `feat!:` / `BREAKING CHANGE:` → major
+- `chore:` / `docs:` / `refactor:` / `test:` → **no release**
+
+To ship a change: give it the right commit type and merge to `main`.
+
+### Changesets
+
+The bump is declared in a changeset file, **not** inferred from commits. A PR with
+no changeset publishes nothing, silently — so this is a required step, not an
+optional one:
+
+```bash
+pnpm changeset        # pick the packages + bump level, write the summary
+```
+
+That writes `.changeset/<name>.md`. Commit it with the change. On merge to `main`
+the release action opens (or updates) a "Version Packages" PR; merging *that* is
+what publishes — so never merge it yourself, leave it for a human. Hand-authoring
+`.changeset/*.md` is fine — it is the one file in this flow you are meant to
+write. `CHANGELOG.md` is still generated; don't touch it.
+
+### Release Please
+
+Also commit-driven, same Conventional Commit → bump mapping as semantic-release.
+On merge to `main` it opens a release PR that carries the version bump and the
+CHANGELOG entry; merging that PR tags and publishes, so leave that merge to a
+human — never do it yourself. Don't edit `.release-please-manifest.json` by hand.
 
 ## What an agent should do
 
-- To ship a change: make sure it carries the right commit type, then merge to `main`.
+- To ship a change: right commit type, plus a changeset if the repo is on Changesets.
 - To check the last release: `git tag --sort=-creatordate | head -1`, or the GitHub
-  Releases page — don't infer it from `package.json` (that's `0.0.0-development` /
-  the placeholder until CI stamps it).
-- If a release seems stuck, inspect the release workflow run — do **not** publish by hand.
+  Releases page — don't infer it from `package.json` (under semantic-release that's
+  `0.0.0-development` / a placeholder until CI stamps it).
+- If a release seems stuck, inspect the release workflow run, and check for an open
+  release / "Version Packages" PR waiting to be merged — report it, do **not** merge
+  it yourself and do **not** publish by hand.
 
 ## Why
 
 Manual publishes skip provenance, the CHANGELOG, and the tag/version invariant the
-whole family relies on, and a stray `npm version` commit derails the next automated
-bump. One automated path keeps every sibling repo publishing identically.
+pipeline maintains, and a stray `npm version` commit derails the next automated bump.
+One automated path per repo keeps releases reproducible and reviewable.

package/tooling/claude/sync-agents.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Canonical sync-agents for @rtorcato/* repos (shipped by @rtorcato/repo-tooling
+// — copy via `repo-tooling copy claude-sync-agents`).
+//
+// Regenerates AGENTS.md from the repo's SKILL.md body so the two can never
+// drift. SKILL.md (with its YAML frontmatter) is the single source of truth;
+// AGENTS.md is its frontmatter-stripped mirror for non-Claude AI tools.
+//
+//   node scripts/sync-agents.mjs           # write AGENTS.md
+//   node scripts/sync-agents.mjs --check   # exit 1 if AGENTS.md is stale (used by CI)
+//
+// Zero-config: the skill directory is derived from the root package.json `name`
+// with any npm scope stripped — `@rtorcato/js-common` → `skills/js-common/`.
+// That is the convention across the family, so this file is copied unmodified.
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const { name } = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+const skillRelative = `skills/${name.replace(/^@[^/]+\//, '')}/SKILL.md`
+const SKILL = join(root, skillRelative)
+const AGENTS = join(root, 'AGENTS.md')
+
+const HEADER = `<!-- Generated from ${skillRelative} by scripts/sync-agents.mjs — do not edit by hand; run \`pnpm sync:agents\`. -->\n\n`
+
+// Strip the leading YAML frontmatter block, keep the markdown body.
+const body = readFileSync(SKILL, 'utf8').replace(/^---\n[\s\S]*?\n---\n+/, '')
+const expected = HEADER + body
+
+if (process.argv.includes('--check')) {
+	let current = ''
+	try {
+		current = readFileSync(AGENTS, 'utf8')
+	} catch {
+		// AGENTS.md missing → treat as stale below.
+	}
+	if (current !== expected) {
+		console.error(`AGENTS.md is out of sync with ${skillRelative} — run \`pnpm sync:agents\`.`)
+		process.exit(1)
+	}
+	console.log(`AGENTS.md is in sync with ${skillRelative}.`)
+} else {
+	writeFileSync(AGENTS, expected)
+	console.log(`Wrote AGENTS.md from ${skillRelative}`)
+}