@rtorcato/repo-tooling 3.29.0 → 3.30.0

package/AGENTS.md

@@ -19,6 +19,8 @@ Every command supports `--json` and a non-interactive mode. Combine with `--yes`
 | `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` / `declared`. |
+| `doctor --rules-from <owner/repo>` | ✅ | ✅ | Report how this repo's `config`/`rules` differ from a reference repo's `.repo-tooling.json` (read over `gh`). Informational only — adds a `rulesReference` key to the JSON, never a check result, never affects the exit code. |
+| `setup --from <owner/repo>` | ❌ (seeds the wizard) | `--dry-run` only | Seed the wizard's defaults from a reference repo's recorded config. Seeded, not skipped — every question is still asked. |
 | `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`. |

package/dist/cli/commands/doctor.js

@@ -19,6 +19,7 @@ import { checkMilestones } from '../../base/milestones.js';
 import { checkGitIdentity, checkGitIdentityHistory } from '../../base/git-identity.js';
 import { checkCopiedAssets } from '../utils/copied-assets.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
+import { compareRulesWithReference } from '../utils/reference-rules.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, checkRecommendedMcp, checkRequiredSkills, COMMITLINT_FILE_CHECK, } from '../../base/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';
@@ -465,11 +466,43 @@ export function summarize(results) {
         declared: results.filter((r) => r.status === 'declared').length,
     };
 }
+/**
+ * Print the `--rules-from` comparison (#563). Deliberately not a CheckResult:
+ * two repos legitimately differ, so a difference is never a finding about either
+ * one, and keeping it out of `results` is what makes "never affects the exit
+ * code" structural rather than a promise the next check has to remember.
+ */
+function printRulesComparison(comparison) {
+    console.log(chalk.cyan(`\n📐 Rules vs ${comparison.reference}`), chalk.gray('(informational — differences are not drift and do not affect the exit code)\n'));
+    if (!comparison.compared) {
+        console.log(`  ${chalk.gray('➖')} ${chalk.gray(`not compared — ${comparison.reason}`)}\n`);
+        return;
+    }
+    const differences = comparison.differences ?? [];
+    if (differences.length === 0) {
+        console.log(`  ${chalk.green('✅')} ${chalk.gray('identical — no differences to report')}\n`);
+        return;
+    }
+    const show = (v) => (v === undefined ? chalk.dim('(absent)') : JSON.stringify(v));
+    for (const d of differences) {
+        console.log(`  ${chalk.bold(d.path)}`);
+        console.log(`     ${chalk.gray('here:')} ${show(d.local)}`);
+        console.log(`     ${chalk.gray(`${comparison.reference}:`)} ${show(d.reference)}`);
+    }
+    console.log(chalk.gray(`\n  ${differences.length} difference(s).\n`));
+}
 export async function doctorCommand(options = {}) {
     const dir = options.directory ?? process.cwd();
     const results = await runDoctor(dir, options.skillsDir);
+    const comparison = options.rulesFrom
+        ? await compareRulesWithReference(dir, options.rulesFrom)
+        : null;
     if (options.json) {
-        console.log(JSON.stringify({ directory: path.resolve(dir), results }, null, 2));
+        console.log(JSON.stringify({
+            directory: path.resolve(dir),
+            results,
+            ...(comparison ? { rulesReference: comparison } : {}),
+        }, null, 2));
     }
     else {
         console.log(chalk.cyan(`\n🩺 Diagnosing ${path.resolve(dir)} against ${PACKAGE} presets...\n`));
@@ -491,6 +524,8 @@ export async function doctorCommand(options = {}) {
             }
             console.log();
         }
+        if (comparison)
+            printRulesComparison(comparison);
     }
     const summary = summarize(results);
     const exitCode = summary.drift > 0 || summary.missing > 0 ? 1 : 0;

package/dist/cli/commands/setup.js

@@ -8,6 +8,7 @@ import { detectLanguage } from '../utils/detect-language.js';
 import { formatGeneratedFiles } from '../utils/format.js';
 import { installDependencies } from '../utils/install.js';
 import { LOCKFILE_NAME, writeLockfile } from '../utils/lockfile.js';
+import { fetchReferenceLockfile } from '../utils/reference-rules.js';
 import { buildPresetConfig, computeFileList, CONFIG_SCHEMA, PRESET_NAMES, validateProjectConfig, } from './setup-presets.js';
 /**
  * The opinionated extras a preset turns on, in the order they're offered for
@@ -63,11 +64,36 @@ async function reviewPresetConfig(config) {
     }
     return reviewed;
 }
+/**
+ * Read a reference repo's recorded config to seed the wizard (#563). Only
+ * `record.config` — the answers — crosses over: `assets` and the
+ * `writtenBy`/`writtenAt` stamps describe the reference's own history, and this
+ * repo's lockfile gets its own on the first write. `rules` is left behind too,
+ * since an `exceptions` entry excuses a deviation in the repo that wrote it.
+ *
+ * `null` means the reference could not be read — reported plainly and declined,
+ * the way `doctor --rules-from` reports "not compared". Falling through to an
+ * unseeded wizard would be worse: the user asked for that repo's answers, and
+ * generic defaults would be written as though they had confirmed them.
+ */
+async function seedFromReference(reference) {
+    const result = await fetchReferenceLockfile(reference);
+    if (!result.ok) {
+        console.error(chalk.red(`\n❌ Cannot seed from ${reference} — ${result.reason}.`));
+        console.error(chalk.gray('   Re-run without --from to answer the wizard from scratch.\n'));
+        return null;
+    }
+    console.log(chalk.cyan(`\n🌱 Seeding defaults from ${reference} — every answer is still yours to change.\n`));
+    return result.lockfile.record.config;
+}
 /** `null` means the run was declined, not that it failed — see promptForConfig. */
 async function resolveConfig(options) {
     if (options.config && options.preset) {
         console.warn(chalk.yellow('⚠️  Both --config and --preset given; --config wins.\n'));
     }
+    if (options.from && (options.config || options.preset)) {
+        console.warn(chalk.yellow('⚠️  --from seeds the wizard, which --config/--preset skip; ignoring --from.\n'));
+    }
     if (options.config) {
         const configPath = path.resolve(options.config);
         if (!(await fs.pathExists(configPath))) {
@@ -99,7 +125,14 @@ async function resolveConfig(options) {
             return config;
         return reviewPresetConfig(config);
     }
-    return promptForConfig(path.resolve(options.directory));
+    let seed;
+    if (options.from) {
+        const seeded = await seedFromReference(options.from);
+        if (seeded === null)
+            return null;
+        seed = seeded;
+    }
+    return promptForConfig(path.resolve(options.directory), seed);
 }
 export async function setupProject(options) {
     if (options.configSchema) {
@@ -165,7 +198,7 @@ const SCAFFOLDABLE = ['js', 'swift'];
  * like. Languages setup can't scaffold yet are still offered — hiding them reads
  * as "repo-tooling is JS-only" when the honest answer is "not yet" (#139).
  */
-async function promptForLanguage(targetDir) {
+async function promptForLanguage(targetDir, seed) {
     const detected = await detectLanguage(targetDir);
     const { language } = await inquirer.prompt([
         {
@@ -178,8 +211,10 @@ async function promptForLanguage(targetDir) {
                     : `${module.label} (${module.supported ? 'doctor/fix only — no setup preset yet' : 'setup lands with its module'})`,
                 value: module.id,
             })),
+            // What this dir already looks like beats the reference's language: the
+            // files on disk are evidence, the reference is only a suggestion.
             // 'unknown' is a bare dir mid-setup — JS is the historical default.
-            default: detected === 'unknown' ? 'js' : detected,
+            default: detected !== 'unknown' ? detected : (seed?.language ?? 'js'),
         },
     ]);
     return LANGUAGES[language];
@@ -196,9 +231,16 @@ function explainNotScaffoldable(module) {
     console.log(chalk.gray(`   ${module.label} setup presets are tracked at\n` +
         '   https://github.com/rtorcato/repo-tooling/issues/139\n'));
 }
-/** `null` when the chosen language has no scaffolding yet; nothing is written. */
-async function promptForConfig(targetDir) {
-    const language = await promptForLanguage(targetDir);
+/**
+ * `null` when the chosen language has no scaffolding yet; nothing is written.
+ *
+ * @param seed A reference repo's recorded config (#563). It moves the *defaults*
+ *   only — every question is still asked, so seeding can never write an answer
+ *   the user did not see. `projectName` is deliberately never seeded: a new repo
+ *   is not the reference repo.
+ */
+async function promptForConfig(targetDir, seed) {
+    const language = await promptForLanguage(targetDir, seed);
     // Gate on SCAFFOLDABLE, not `module.supported` — Swift is supported (#286)
     // but has no preset yet (#288), and falling through here would write a
     // package.json into a Swift repo.
@@ -228,6 +270,18 @@ async function promptForConfig(targetDir) {
     // Turborepo only makes sense in a pnpm-workspace monorepo, so the prompt is
     // only offered when one is already present in the target dir.
     const hasWorkspace = await fs.pathExists(path.join(targetDir, 'pnpm-workspace.yaml'));
+    // Two questions ask for something the config stores as a set of booleans, so
+    // their seeded default has to be derived rather than read.
+    const seededReleaseTool = !seed
+        ? 'semantic-release'
+        : seed.semanticRelease
+            ? 'semantic-release'
+            : seed.changesets
+                ? 'changesets'
+                : seed.releasePlease
+                    ? 'release-please'
+                    : 'none';
+    const seededOrchestrator = !seed ? 'turbo' : seed.turborepo ? 'turbo' : seed.nx ? 'nx' : 'none';
     const answers = await inquirer.prompt([
         {
             type: 'input',
@@ -240,6 +294,7 @@ async function promptForConfig(targetDir) {
             type: 'select',
             name: 'projectType',
             message: '🏗️  What type of project are you building?',
+            default: seed?.projectType,
             choices: [
                 { name: '📚 Library/Package', value: 'library' },
                 { name: '🌐 Web Application', value: 'web-app' },
@@ -252,7 +307,7 @@ async function promptForConfig(targetDir) {
             type: 'confirm',
             name: 'useTypeScript',
             message: '📘 Do you want to use TypeScript?',
-            default: true,
+            default: seed?.typescript.enabled ?? true,
         },
         {
             type: 'select',
@@ -277,6 +332,7 @@ async function promptForConfig(targetDir) {
                 }
                 return baseChoices;
             },
+            default: seed?.typescript.config,
             when: (answers) => answers.useTypeScript,
         },
         {
@@ -289,7 +345,7 @@ async function promptForConfig(targetDir) {
                 { name: '🔥 Both Biome + ESLint', value: 'both' },
                 { name: '❌ None', value: 'none' },
             ],
-            default: 'biome',
+            default: seed?.linting.tool ?? 'biome',
         },
         {
             type: 'select',
@@ -302,13 +358,14 @@ async function promptForConfig(targetDir) {
                 }
                 return choices;
             },
+            default: seed?.linting.eslintConfig,
             when: (answers) => answers.lintingTool === 'eslint' || answers.lintingTool === 'both',
         },
         {
             type: 'confirm',
             name: 'oxlint',
             message: '🦀 Also run Oxlint alongside (50–100× faster than ESLint)?',
-            default: false,
+            default: seed?.oxlint ?? false,
             when: (answers) => answers.lintingTool !== 'none',
         },
         {
@@ -322,7 +379,7 @@ async function promptForConfig(targetDir) {
                 { name: '🌲 Cypress (E2E)', value: 'cypress' },
                 { name: '❌ None', value: 'none' },
             ],
-            default: 'vitest',
+            default: seed?.testing.framework ?? 'vitest',
         },
         {
             type: 'select',
@@ -334,19 +391,19 @@ async function promptForConfig(targetDir) {
                 { name: '🔄 Both', value: 'both' },
             ],
             when: (answers) => answers.testingFramework === 'jest',
-            default: 'node',
+            default: seed?.testing.environment ?? 'node',
         },
         {
             type: 'confirm',
             name: 'gitHooks',
             message: '🪝 Set up Git hooks (Husky + lint-staged)?',
-            default: true,
+            default: seed?.gitHooks ?? true,
         },
         {
             type: 'confirm',
             name: 'commitLint',
             message: '📝 Set up conventional commit linting?',
-            default: true,
+            default: seed?.commitLint ?? true,
             when: (answers) => answers.gitHooks,
         },
         {
@@ -359,40 +416,40 @@ async function promptForConfig(targetDir) {
                 { name: '🙏 Release Please (Google, release-PR-driven)', value: 'release-please' },
                 { name: '❌ None', value: 'none' },
             ],
-            default: 'semantic-release',
+            default: seededReleaseTool,
             when: (answers) => answers.projectType === 'library',
         },
         {
             type: 'confirm',
             name: 'treeshakeCheck',
             message: '🌳 Add a tree-shake verification check (apps/treeshake-check)?',
-            default: false,
+            default: seed?.treeshakeCheck ?? false,
             when: (answers) => answers.projectType === 'library',
         },
         {
             type: 'confirm',
             name: 'publint',
             message: '📦 Add publint to lint your package before publishing?',
-            default: true,
+            default: seed?.publint ?? true,
             when: (answers) => answers.projectType === 'library',
         },
         {
             type: 'confirm',
             name: 'badges',
             message: '🔖 Add status badges (CI, npm, coverage, license) to the README?',
-            default: true,
+            default: seed?.badges ?? true,
         },
         {
             type: 'confirm',
             name: 'securityAutomation',
             message: '🛡️  Include security automation (Dependabot + CodeQL)?',
-            default: true,
+            default: seed?.securityAutomation ?? true,
         },
         {
             type: 'confirm',
             name: 'aiSetup',
             message: '🤖 Add AI agent rules (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill)?',
-            default: true,
+            default: seed?.aiSetup ?? true,
         },
         {
             type: 'select',
@@ -403,14 +460,14 @@ async function promptForConfig(targetDir) {
                 { name: '🔷 Nx (nx.json)', value: 'nx' },
                 { name: '❌ None', value: 'none' },
             ],
-            default: 'turbo',
+            default: seededOrchestrator,
             when: () => hasWorkspace,
         },
         {
             type: 'confirm',
             name: 'tailwind',
             message: '🎨 Add Tailwind CSS v4 (PostCSS plugin + globals.css)?',
-            default: true,
+            default: seed?.tailwind ?? true,
             // Only meaningful for frontend project types.
             when: (answers) => answers.projectType === 'web-app' ||
                 answers.projectType === 'react-app' ||
@@ -433,13 +490,14 @@ async function promptForConfig(targetDir) {
                 }
                 return choices;
             },
+            default: seed?.bundler,
             when: (answers) => answers.projectType !== 'nextjs-app', // Next.js has its own bundler
         },
         {
             type: 'confirm',
             name: 'bun',
             message: '🥟 Target the Bun runtime (bunfig.toml + Bun-typed tsconfig)?',
-            default: false,
+            default: seed?.bun ?? false,
             // A runtime flag, not a project type — offer it for Node-compatible
             // library/API targets, not the browser-framework types.
             when: (answers) => answers.projectType === 'library' || answers.projectType === 'node-api',

package/dist/cli/index.js

@@ -34,6 +34,8 @@ program
     .option('--config <path>', 'Skip prompts; read a ProjectConfig or .repo-tooling.json lockfile from <path>')
     .option('--dry-run', 'Print the resolved config and file list, write nothing')
     .option('--config-schema', 'Print the JSON Schema for ProjectConfig and exit')
+    // Seeds the wizard, never skips it (#563) — every answer is still yours.
+    .option('--from <owner/repo>', "Seed the wizard's defaults from that repo's .repo-tooling.json instead of the built-in ones (read via `gh`)")
     .action(setupProject);
 program
     .command('copy <config>')
@@ -321,6 +323,9 @@ program
     // 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')
+    // Rules are per-repo (#563): this compares them against another repo's, and
+    // only reports. Never drift, never a fixer, never part of the exit code.
+    .option('--rules-from <owner/repo>', "Report how this repo's config and rules differ from that repo's .repo-tooling.json (informational; read via `gh`)")
     .action(doctorCommand);
 program
     .command('fix [target]')

package/dist/cli/utils/json-schema.js

@@ -0,0 +1,64 @@
+/**
+ * A JSON Schema validator covering exactly the keyword subset `lockfileSchema()`
+ * and `CONFIG_SCHEMA` use: type (object/array/string/integer/boolean), enum,
+ * minLength, required, properties, additionalProperties (`false` or a schema)
+ * and items. Returns one message per problem; an empty array means valid.
+ *
+ * Hand-rolled because the repo has no JSON Schema validator and the schemas lean
+ * on seven keywords — not enough to justify an ajv dependency. It lives in src
+ * rather than in a test because a reference repo's lockfile is untrusted input
+ * that has to be schema-checked before it is read (#563).
+ */
+// ponytail: `format: date-time` is not checked, and neither are composition
+// keywords — none appear in either schema. Reach for ajv the day one does.
+export function validateAgainstSchema(value, schema, path = '$') {
+    const errors = [];
+    if (schema.enum && !schema.enum.includes(value)) {
+        errors.push(`${path}: ${JSON.stringify(value)} is not one of ${schema.enum.join(', ')}`);
+    }
+    if (schema.type === 'array') {
+        if (!Array.isArray(value))
+            return [`${path}: expected array`];
+        if (schema.items) {
+            for (const [i, item] of value.entries()) {
+                errors.push(...validateAgainstSchema(item, schema.items, `${path}[${i}]`));
+            }
+        }
+        return errors;
+    }
+    if (schema.type === 'object') {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return [`${path}: expected object`];
+        }
+        const obj = value;
+        for (const key of schema.required ?? []) {
+            if (!(key in obj))
+                errors.push(`${path}: missing required property "${key}"`);
+        }
+        for (const [key, child] of Object.entries(obj)) {
+            const property = schema.properties?.[key];
+            if (property)
+                errors.push(...validateAgainstSchema(child, property, `${path}.${key}`));
+            else if (schema.additionalProperties === false) {
+                errors.push(`${path}: unknown property "${key}"`);
+            }
+            else if (typeof schema.additionalProperties === 'object') {
+                errors.push(...validateAgainstSchema(child, schema.additionalProperties, `${path}.${key}`));
+            }
+        }
+        return errors;
+    }
+    if (schema.type === 'integer') {
+        if (!Number.isInteger(value))
+            errors.push(`${path}: expected integer`);
+    }
+    else if (schema.type && typeof value !== schema.type) {
+        errors.push(`${path}: expected ${schema.type}, got ${typeof value}`);
+    }
+    if (schema.minLength !== undefined &&
+        typeof value === 'string' &&
+        value.length < schema.minLength) {
+        errors.push(`${path}: shorter than minLength ${schema.minLength}`);
+    }
+    return errors;
+}

package/dist/cli/utils/lockfile.js

@@ -184,6 +184,26 @@ function migrate(raw) {
         ...(Object.keys(rules).length > 0 ? { rules } : {}),
     };
 }
+/**
+ * Normalize already-parsed JSON into a Lockfile, or null when it isn't one.
+ * Split out of readLockfile so a lockfile fetched from somewhere other than the
+ * filesystem — a reference repo, over `gh` — goes through the same migration
+ * before anything reads it (#563).
+ */
+export function parseLockfile(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const obj = raw;
+    if (typeof obj.version !== 'number')
+        return null;
+    // v4+ keeps config under `record`; v1–v3 keep it at the top level (#559).
+    const config = obj.version >= LOCKFILE_VERSION
+        ? obj.record?.config
+        : obj.config;
+    if (typeof config !== 'object' || config === null)
+        return null;
+    return migrate(obj);
+}
 export async function readLockfile(dir) {
     let filepath = path.join(dir, LOCKFILE_NAME);
     if (!(await fs.pathExists(filepath))) {
@@ -194,19 +214,7 @@ export async function readLockfile(dir) {
         filepath = legacy;
     }
     try {
-        const raw = (await fs.readJson(filepath));
-        if (typeof raw !== 'object' || raw === null)
-            return null;
-        const obj = raw;
-        if (typeof obj.version !== 'number')
-            return null;
-        // v4+ keeps config under `record`; v1–v3 keep it at the top level (#559).
-        const config = obj.version >= LOCKFILE_VERSION
-            ? obj.record?.config
-            : obj.config;
-        if (typeof config !== 'object' || config === null)
-            return null;
-        return migrate(obj);
+        return parseLockfile((await fs.readJson(filepath)));
     }
     catch {
         return null;

package/dist/cli/utils/reference-rules.js

@@ -0,0 +1,125 @@
+import { realGhExec } from '../../base/github-settings.js';
+import { validateAgainstSchema } from './json-schema.js';
+import { LOCKFILE_NAME, lockfileSchema, parseLockfile, readLockfile, } from './lockfile.js';
+/**
+ * Rules are per-repo (#563): there is no guideline package, so sharing a
+ * guideline means pointing at another repo. This module is the one fetcher both
+ * halves of that share — `doctor --rules-from` reads a reference repo's rules to
+ * report differences, and `setup --from` reads the same file to seed the wizard.
+ *
+ * The reference is untrusted input from end to end: the `owner/repo` string is
+ * shape-checked before it reaches an API path, the response is size-capped, and
+ * the JSON is validated against the published schema before a single field is
+ * read. Nothing here ever writes, and nothing is ever applied.
+ */
+/**
+ * `owner/repo`. The injection boundary — the reference is interpolated into the
+ * gh API path below, so anything with a slash, `..` or a shell metacharacter in
+ * it has to be rejected here rather than defended against later.
+ */
+const REFERENCE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Generous by four orders of magnitude — a real lockfile is ~1 KB. This is not a
+ * tuning knob, it is the "huge file" guard: the response is fully buffered by the
+ * time we see it, so the cap stops us parsing and diffing a repo's 40 MB joke.
+ */
+const MAX_BYTES = 128 * 1024;
+/**
+ * The GitHub arm of the fetch. Another forge is a second function of this shape
+ * dispatched from fetchReferenceLockfile — everything downstream (size cap,
+ * parse, schema validation, diff) is forge-agnostic and already shared.
+ */
+async function fetchFromGitHub(reference, exec) {
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin));
+    // `Accept: raw` returns the file itself rather than the base64-in-JSON envelope.
+    const r = await gh([
+        'api',
+        `repos/${reference}/contents/${LOCKFILE_NAME}`,
+        '-H',
+        'Accept: application/vnd.github.raw',
+    ]);
+    if (r.ok)
+        return { ok: true, text: r.stdout };
+    if (/HTTP 404/.test(r.stderr)) {
+        return { ok: false, reason: `${reference} has no ${LOCKFILE_NAME} (or is not visible to you)` };
+    }
+    const detail = r.stderr.trim().split('\n').pop() ?? 'gh failed';
+    return { ok: false, reason: `could not read ${reference}: ${detail}` };
+}
+function parseReference(reference, text) {
+    if (Buffer.byteLength(text) > MAX_BYTES) {
+        return {
+            ok: false,
+            reason: `${reference}'s ${LOCKFILE_NAME} is larger than ${MAX_BYTES} bytes`,
+        };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: `${reference}'s ${LOCKFILE_NAME} is not valid JSON` };
+    }
+    // Migrate first, then validate: an older reference is flat on disk and would
+    // fail the current schema for a reason that says nothing about its rules.
+    const lockfile = parseLockfile(raw);
+    if (!lockfile) {
+        return { ok: false, reason: `${reference}'s ${LOCKFILE_NAME} is not a recognisable lockfile` };
+    }
+    const errors = validateAgainstSchema(lockfile, lockfileSchema());
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            reason: `${reference}'s ${LOCKFILE_NAME} fails the published schema: ${errors.slice(0, 3).join('; ')}`,
+        };
+    }
+    return { ok: true, lockfile };
+}
+export async function fetchReferenceLockfile(reference, exec) {
+    if (!REFERENCE.test(reference)) {
+        return { ok: false, reason: `"${reference}" is not an owner/repo reference` };
+    }
+    const fetched = await fetchFromGitHub(reference, exec);
+    if (!fetched.ok)
+        return fetched;
+    return parseReference(reference, fetched.text);
+}
+/**
+ * The comparable half of a lockfile: the resolved config plus the human-written
+ * rules. `assets` hashes and the `writtenBy`/`writtenAt` stamps are excluded on
+ * purpose — they differ between any two repos by construction, so diffing them
+ * would bury every difference that means something.
+ */
+function rulesView(lock) {
+    return { config: lock.record.config, ...(lock.rules ?? {}) };
+}
+function flatten(value, prefix = '', out = new Map()) {
+    // Arrays are leaves: `requiredSkills` differing by one entry is one difference
+    // about the list, not a per-index report that shifts when the order does.
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        for (const [key, child] of Object.entries(value)) {
+            flatten(child, prefix ? `${prefix}.${key}` : key, out);
+        }
+        return out;
+    }
+    out.set(prefix, value);
+    return out;
+}
+export function diffRules(local, reference) {
+    const mine = local ? flatten(rulesView(local)) : new Map();
+    const theirs = flatten(rulesView(reference));
+    return [...new Set([...mine.keys(), ...theirs.keys()])]
+        .sort()
+        .filter((p) => JSON.stringify(mine.get(p)) !== JSON.stringify(theirs.get(p)))
+        .map((p) => ({ path: p, local: mine.get(p), reference: theirs.get(p) }));
+}
+export async function compareRulesWithReference(dir, reference, exec) {
+    const result = await fetchReferenceLockfile(reference, exec);
+    if (!result.ok)
+        return { reference, compared: false, reason: result.reason };
+    return {
+        reference,
+        compared: true,
+        differences: diffRules(await readLockfile(dir), result.lockfile),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.29.0",
+	"version": "3.30.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [