@rtorcato/repo-tooling 3.18.0 → 3.19.1

package/dist/base/checks.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import fs from 'fs-extra';
 import { BLOCK_START, hasStaleAgentBlock } from '../cli/generators/agent-rules.js';
 import { BADGE_START, hasPublicOnlyBadges } from '../cli/generators/badges.js';
-import { claudeSkillStatus, SHIPPED_SKILL } from '../cli/generators/claude-skills.js';
+import { claudeSkillStatus, SHIPPED_SKILL, skillDiffCommand, } from '../cli/generators/claude-skills.js';
 import { DEPENDABOT_CONFIG_PATHS, dependabotIgnoreRules } from '../cli/generators/security.js';
 import { detectNestedLanguages } from '../cli/utils/detect-language.js';
 /**
@@ -469,11 +469,16 @@ export async function checkAiSetup(dir) {
  * is not a defect in this repo, and either of those statuses would fail its CI
  * over a file CI has never seen. `optional-missing` is the honest verdict — an
  * opt-in workflow tool that isn't configured — and it leaves the exit code alone.
+ *
+ * `skillsDir` is doctor's `--skills-dir`. Without it this reported against
+ * `~/.claude/skills` whatever directory the repo actually installs into, so a
+ * consumer who passes the flag to `fix` saw a permanent false `optional-missing`
+ * for a skill they have (#485).
  */
-export async function checkClaudeSkills() {
+export async function checkClaudeSkills(skillsDir) {
     const check = 'Claude skills';
     const hint = `Run \`npx @rtorcato/repo-tooling fix claude-skills\` to install the ${SHIPPED_SKILL} skill (writes outside the repo; opt-in, so \`fix\` alone skips it)`;
-    const status = await claudeSkillStatus();
+    const status = await claudeSkillStatus(SHIPPED_SKILL, skillsDir);
     if (!status.installed) {
         return {
             check,
@@ -495,7 +500,9 @@ export async function checkClaudeSkills() {
     // A local fork is `ok` for the same reason a modified copied asset is (#448):
     // it is somebody's deliberate work, so it is named once and never nagged as
     // fixable — pointing at a `fix` that would refuse is worse than saying nothing.
-    if (status.contentState && status.contentState !== 'pristine') {
+    // `realFile` is set whenever `contentState` is — both mean something is
+    // installed. The extra test is TypeScript's, not a real condition.
+    if (status.realFile && status.contentState && status.contentState !== 'pristine') {
         const why = status.contentState === 'modified'
             ? `has local changes since ${status.installedVersion}`
             : 'carries no content record, so a fork cannot be told from a stale copy';
@@ -503,7 +510,9 @@ export async function checkClaudeSkills() {
             check,
             status: 'ok',
             detail: `${SHIPPED_SKILL} skill at ${status.file} ${why}; this package ships ${status.shippedVersion} and will not overwrite it`,
-            hint: `Diff it against the shipped copy, then run \`npx @rtorcato/repo-tooling fix claude-skills --force-skills\` to take the shipped version`,
+            // Name both paths: "diff it against the shipped copy" left the reader
+            // with nothing to diff, in the one case they most want to look (#484).
+            hint: `Diff it against the shipped copy — \`${skillDiffCommand({ realFile: status.realFile, shippedFile: status.shippedFile })}\` — then run \`npx @rtorcato/repo-tooling fix claude-skills --force-skills\` to take the shipped version`,
         };
     }
     return {

package/dist/base/fixers.js

@@ -16,7 +16,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { installAgentRules, installAiSetup } from '../cli/generators/agent-rules.js';
-import { installClaudeSkill, resolveSkillsDir, SHIPPED_SKILL, } from '../cli/generators/claude-skills.js';
+import { installClaudeSkill, resolveSkillsDir, SHIPPED_SKILL, skillDiffCommand, } from '../cli/generators/claude-skills.js';
 import { generateBrand } from '../cli/generators/brand.js';
 import { generateCommunityHealth } from '../cli/generators/community-health.js';
 import { generateCommitlintConfig } from '../cli/generators/git.js';
@@ -89,7 +89,7 @@ function describeSkillFork(result) {
     return [
         `skipped — ${SHIPPED_SKILL} was not overwritten with ${result.shippedVersion}: ${why}`,
         `  ${target}`,
-        `  compare:  diff "${result.realFile}" "${result.shippedFile}"`,
+        `  compare:  ${skillDiffCommand(result)}`,
         '  overwrite anyway:  fix claude-skills --force-skills',
     ];
 }

package/dist/cli/commands/doctor.js

@@ -179,12 +179,12 @@ async function runBaseChecks(dir, lock, opts) {
     results.push(await checkBrand(dir));
     results.push(await checkAiSetup(dir));
     // User-global, not repo state — see checkClaudeSkills on why it never returns drift.
-    results.push(await checkClaudeSkills());
+    results.push(await checkClaudeSkills(opts.skillsDir));
     results.push(await checkReadmeBadges(dir, opts.badges.audience, opts.badges.fixTarget));
     results.push(await checkCoverageUpload(dir));
     return results;
 }
-export async function runDoctor(dir) {
+export async function runDoctor(dir, skillsDir) {
     const targetDir = path.resolve(dir);
     const lock = await readLockfile(targetDir);
     // Per-module dispatch (#285): the base checks (repo hygiene, CI, security,
@@ -212,6 +212,7 @@ export async function runDoctor(dir) {
                 presetWorkflow: null,
                 language,
                 codeqlLanguages: languageModule.codeqlLanguages,
+                skillsDir,
             })),
         ];
         return demoteDeclined(results, lock);
@@ -234,6 +235,7 @@ export async function runDoctor(dir) {
                 presetWorkflow: renderSwiftWorkflow(await readSwiftPackage(targetDir)),
                 language,
                 codeqlLanguages: languageModule.codeqlLanguages,
+                skillsDir,
             })),
             ...(await runSwiftChecks(targetDir)),
         ];
@@ -257,6 +259,7 @@ export async function runDoctor(dir) {
                 presetWorkflow: renderPythonWorkflow(await readPyproject(targetDir)),
                 language,
                 codeqlLanguages: languageModule.codeqlLanguages,
+                skillsDir,
             })),
             ...(await runPythonChecks(targetDir)),
         ];
@@ -282,6 +285,7 @@ export async function runDoctor(dir) {
                 presetWorkflow: renderPerlWorkflow(await readPerlProject(targetDir)),
                 language,
                 codeqlLanguages: languageModule.codeqlLanguages,
+                skillsDir,
             })),
             ...(await runPerlChecks(targetDir)),
         ];
@@ -342,6 +346,7 @@ export async function runDoctor(dir) {
         presetWorkflow: renderGitHubWorkflow(githubJobs(inferProjectConfig(pkg), { scripts: scriptsOf(pkg) })),
         language,
         codeqlLanguages: languageModule.codeqlLanguages,
+        skillsDir,
     })));
     return demoteDeclined(results, lock);
 }
@@ -397,7 +402,7 @@ export function summarize(results) {
 }
 export async function doctorCommand(options = {}) {
     const dir = options.directory ?? process.cwd();
-    const results = await runDoctor(dir);
+    const results = await runDoctor(dir, options.skillsDir);
     if (options.json) {
         console.log(JSON.stringify({ directory: path.resolve(dir), results }, null, 2));
     }

package/dist/cli/commands/fix.js

@@ -333,7 +333,9 @@ export async function fixCommand(target, options = {}) {
     const pkg = await readPackageJson(targetDir);
     const lock = await readLockfile(targetDir);
     const fixers = fixersForLanguage(await detectLanguage(targetDir));
-    const results = await runDoctor(targetDir);
+    // Same --skills-dir the claude-skills fixer writes to, so the diagnosis fix
+    // acts on and the install it performs agree on one directory (#485).
+    const results = await runDoctor(targetDir, options.skillsDir);
     const actions = [];
     const noteLockConflict = (check) => {
         if (!lock)

package/dist/cli/generators/claude-skills.js

@@ -129,6 +129,16 @@ export async function readShippedSkill(name = SHIPPED_SKILL) {
     const pkg = await fs.readJson(path.join(root, 'package.json'));
     return { content, version: String(pkg.version), file };
 }
+/**
+ * The command a human runs to see what their fork changed, before deciding
+ * whether to take the shipped copy. One builder, because `doctor` and `fix`
+ * both print it and two independently-built strings drift (#484). Always
+ * `realFile`: through a stow symlink the nominal path is the link, and the
+ * bytes worth reading are in the dotfiles checkout it points at.
+ */
+export function skillDiffCommand(paths) {
+    return `diff "${paths.realFile}" "${paths.shippedFile}"`;
+}
 /** Whether `file` is itself a symlink, as opposed to merely resolving through one. */
 async function isSymlink(file) {
     return await fs
@@ -185,6 +195,8 @@ export async function claudeSkillStatus(name = SHIPPED_SKILL, explicit) {
     const shipped = await readShippedSkill(name);
     const { dir } = await resolveSkillsDir(explicit);
     const absent = {
+        realFile: null,
+        shippedFile: shipped.file,
         installed: false,
         installedVersion: null,
         shippedVersion: shipped.version,
@@ -202,6 +214,8 @@ export async function claudeSkillStatus(name = SHIPPED_SKILL, explicit) {
     const behind = installedVersion === null || isNewerVersion(shipped.version, installedVersion);
     return {
         file,
+        realFile: (await isSymlink(file)) ? await fs.realpath(file) : file,
+        shippedFile: shipped.file,
         installed: true,
         installedVersion,
         shippedVersion: shipped.version,

package/dist/cli/index.js

@@ -317,6 +317,9 @@ program
     .description('🩺 Diagnose project alignment with @rtorcato/repo-tooling presets')
     .option('-d, --directory <path>', 'Target directory to diagnose', process.cwd())
     .option('--json', 'Emit machine-readable JSON output')
+    // The read side of `fix --skills-dir` (#485). No --yes/--json requirement
+    // here: doctor never writes, so an unresolved directory is just reported.
+    .option('--skills-dir <path>', 'Where `fix claude-skills` installs user-global agent skills (default: ~/.claude/skills). Pass the same path `fix` was given, or the skill reports as not installed')
     .action(doctorCommand);
 program
     .command('fix [target]')

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

@@ -4,7 +4,9 @@ import fs from 'fs-extra';
 import { recordAssetHash } from './lockfile.js';
 export const PRESETS = {
     biome: {
-        source: 'tooling/biome/biome.json',
+        // Not named `biome.json`: Biome auto-discovers any file by that name, so
+        // shipping one inside this package made it a second root config here (#486).
+        source: 'tooling/biome/preset.json',
         target: 'biome.json',
         desc: 'Biome formatter and linter configuration',
     },

package/dist/languages/js/checks.js

@@ -84,7 +84,7 @@ function matchesBiomeConfig(contents) {
     if (BIOME_PRESET_REF.test(JSON.stringify(config.extends ?? '')))
         return true;
     // The inlined preset: biome's own `$schema` plus the `linter.rules.preset`
-    // key the shipped `tooling/biome/biome.json` sets.
+    // key the shipped `tooling/biome/preset.json` sets.
     const schema = config.$schema;
     return (typeof schema === 'string' &&
         schema.includes('biomejs.dev/schemas/') &&
@@ -1373,7 +1373,7 @@ function readSchemaUrl(contents) {
  * of which version the config targets, so comparing it against the declared
  * dependency floor is exact — no heuristics, no false positives.
  *
- * This is the #330 defect precisely: `tooling/biome/biome.json` carries
+ * This is the #330 defect precisely: `tooling/biome/preset.json` carries
  * `$schema` 2.5.0 and uses `linter.rules.preset`, a 2.5 key, while
  * `peerDependencies` advertised `@biomejs/biome: ^2.0.0`. Consumers on 2.0–2.4
  * got `Found an unknown key \`preset\`` with nothing pointing at the range.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.18.0",
+	"version": "3.19.1",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -90,7 +90,7 @@
 		"tooling/docusaurus/docs-helpers.mjs",
 		"tooling/docusaurus/theme-tokens.css",
 		"tooling/docusaurus/theme.css",
-		"tooling/biome/biome.json",
+		"tooling/biome/preset.json",
 		"tooling/bun/bunfig.toml",
 		"tooling/nx/nx.json",
 		"tooling/changesets/config.json",
@@ -201,7 +201,7 @@
 			"types": "./tooling/docusaurus/index.d.mts",
 			"import": "./tooling/docusaurus/index.mjs"
 		},
-		"./biome": "./tooling/biome/biome.json",
+		"./biome": "./tooling/biome/preset.json",
 		"./nx": "./tooling/nx/nx.json",
 		"./changesets": "./tooling/changesets/config.json",
 		"./release-please": "./tooling/release-please/release-please-config.json",

package/tooling/biome/{biome.json → preset.json}

@@ -1,6 +1,5 @@
 {
   "$schema": "https://biomejs.dev/schemas/latest/schema.json",
-  "root": false,
   "vcs": {
     "enabled": true,
     "clientKind": "git",