@rtorcato/repo-tooling 3.16.3 → 3.17.0

package/dist/base/checks.js

@@ -492,6 +492,20 @@ export async function checkClaudeSkills() {
             hint,
         };
     }
+    // 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') {
+        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';
+        return {
+            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`,
+        };
+    }
     return {
         check,
         status: 'ok',

package/dist/base/fixers.js

@@ -76,6 +76,23 @@ async function resolveInstallDir(explicit, assumeYes) {
     const trimmed = typeof answer === 'string' ? answer.trim() : '';
     return trimmed ? path.resolve(trimmed) : null;
 }
+/**
+ * Why the install refused, and what to do about it. A bare "skipped" would be
+ * its own failure mode: the user still wants the update, and nothing on screen
+ * would say how to get it or what they would be giving up (#480).
+ */
+function describeSkillFork(result) {
+    const target = result.viaSymlink ? `${result.file} → ${result.realFile}` : result.realFile;
+    const why = result.contentState === 'modified'
+        ? `its content has diverged from the ${result.installedVersion} release it was installed from`
+        : 'it carries no content record, so a local fork and a stale copy are indistinguishable';
+    return [
+        `skipped — ${SHIPPED_SKILL} was not overwritten with ${result.shippedVersion}: ${why}`,
+        `  ${target}`,
+        `  compare:  diff "${result.realFile}" "${result.shippedFile}"`,
+        '  overwrite anyway:  fix claude-skills --force-skills',
+    ];
+}
 export const BASE_FIXERS = [
     {
         target: 'copied-assets',
@@ -321,15 +338,22 @@ export const BASE_FIXERS = [
         riskLevel: 'safe-add',
         explicitOnly: true,
         canFixDrift: true,
-        async run({ skillsDir, assumeYes }) {
+        async run({ skillsDir, forceSkills, assumeYes }) {
             const dir = await resolveInstallDir(skillsDir, assumeYes);
             if (!dir)
                 return { filesWritten: [] };
-            const result = await installClaudeSkill(dir);
+            const result = await installClaudeSkill(dir, SHIPPED_SKILL, { force: forceSkills });
             if (result.status === 'declined-downgrade') {
                 console.error(chalk.yellow(`   skipped — ${result.file} is at ${result.installedVersion}, newer than the ${result.shippedVersion} this package ships`));
                 return { filesWritten: [] };
             }
+            if (result.status === 'declined-fork') {
+                // Name `realFile`: through a stow symlink the overwrite would land in a
+                // *second* repo's working tree, and that is the path to look at (#480).
+                for (const line of describeSkillFork(result))
+                    console.error(chalk.yellow(`   ${line}`));
+                return { filesWritten: [] };
+            }
             if (result.status === 'up-to-date')
                 return { filesWritten: [] };
             // Report the resolved real path when the skill is a stow symlink: the bytes

package/dist/cli/commands/fix.js

@@ -413,6 +413,7 @@ export async function fixCommand(target, options = {}) {
         // branch and records a skip, since one refusal must not abandon the rest.
         const outcome = await applyFixer(fixer, effectiveResult, targetDir, pkg, lock, dryRun, silent, {
             skillsDir: options.skillsDir,
+            forceSkills: options.forceSkills,
             assumeYes,
         }).catch((err) => {
             if (!(err instanceof FixerAbort))
@@ -488,6 +489,7 @@ export async function fixCommand(target, options = {}) {
         try {
             outcome = await applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent, {
                 skillsDir: options.skillsDir,
+                forceSkills: options.forceSkills,
                 assumeYes,
             });
         }

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

@@ -4,6 +4,7 @@
  * project on the machine. That difference drives all three rules below — the
  * version stamp, the symlink handling, and the fixer's opt-in `explicitOnly`.
  */
+import { createHash } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import fs from 'fs-extra';
@@ -17,6 +18,19 @@ export const SHIPPED_SKILL = 'ai-issue-loop';
  * is wrong to do so.
  */
 export const VERSION_KEY = 'repo-tooling-version';
+/**
+ * The pristine sha256 of the content we wrote, stamped beside the version — the
+ * skills half of #448. The version alone cannot tell a stale copy from a
+ * deliberate local fork: a fork that is merely older than the package looks
+ * exactly like a copy waiting for an update, and gets overwritten (#480).
+ * With the hash, "installed content still matches what some release of this
+ * package shipped" is a fact rather than an inference.
+ *
+ * It lives in the file instead of `.repo-tooling.json` because skills are
+ * user-global — no one repo owns the record.
+ */
+export const HASH_KEY = 'repo-tooling-hash';
+const STAMP_KEYS = [VERSION_KEY, HASH_KEY];
 const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
 /**
  * Where to install. `explicit` is `--skills-dir`; otherwise the user-level
@@ -35,25 +49,64 @@ export async function resolveSkillsDir(explicit, home = os.homedir()) {
         return { dir: userDir, source: 'user' };
     return { dir: null, source: 'none' };
 }
+function readStamp(content, key) {
+    return content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim() ?? null;
+}
 /** The version recorded in an installed copy, or null if it predates the stamp. */
 export function readSkillVersion(content) {
-    return content.match(new RegExp(`^${VERSION_KEY}:\\s*(.+)$`, 'm'))?.[1]?.trim() ?? null;
+    return readStamp(content, VERSION_KEY);
+}
+/** The pristine hash recorded in an installed copy, or null if it predates it. */
+export function readSkillHash(content) {
+    return readStamp(content, HASH_KEY);
 }
 /**
- * Replace (or add) the version line in the frontmatter. Appending it last is
+ * Replace (or add) the stamp lines in the frontmatter. Appending them last is
  * safe even after a multi-line `description: |` block: an unindented key ends
- * the block scalar, which is exactly what this line is.
+ * the block scalar, which is exactly what these lines are.
+ *
+ * With no stamps this is the exact inverse of stamping, so a file we wrote
+ * strips back to the bytes we were given — which is what makes the hash
+ * comparable.
  */
-export function stampSkillVersion(content, version) {
-    const stamp = `${VERSION_KEY}: ${version}`;
+function setStamps(content, stamps) {
     const match = content.match(FRONTMATTER);
     if (!match)
-        return `---\n${stamp}\n---\n\n${content}`;
-    const fields = (match[1] ?? '')
+        return stamps.length === 0 ? content : `---\n${stamps.join('\n')}\n---\n\n${content}`;
+    const kept = (match[1] ?? '')
         .split('\n')
-        .filter((line) => !line.startsWith(`${VERSION_KEY}:`))
-        .join('\n');
-    return `---\n${fields}\n${stamp}\n---\n${content.slice(match[0].length)}`;
+        .filter((line) => !STAMP_KEYS.some((key) => line.startsWith(`${key}:`)));
+    return `---\n${[...kept, ...stamps].join('\n')}\n---\n${content.slice(match[0].length)}`;
+}
+/** An installed copy with this package's own bookkeeping lines removed. */
+export function stripSkillStamps(content) {
+    return setStamps(content, []);
+}
+/**
+ * The version stamp on its own — the shape releases before #480 wrote, and what
+ * `classifySkillContent` sees as `unknown`. Not the write path; `stampSkill` is.
+ */
+export function stampSkillVersion(content, version) {
+    return setStamps(content, [`${VERSION_KEY}: ${version}`]);
+}
+/** sha256 of the content this package shipped, ignoring the stamps it adds. */
+export function hashSkillContent(content) {
+    return createHash('sha256').update(stripSkillStamps(content)).digest('hex');
+}
+/** The version + hash stamps, as written to disk. */
+export function stampSkill(content, version) {
+    return setStamps(content, [
+        `${VERSION_KEY}: ${version}`,
+        `${HASH_KEY}: ${hashSkillContent(content)}`,
+    ]);
+}
+export function classifySkillContent(installed, shipped) {
+    if (stripSkillStamps(installed) === stripSkillStamps(shipped))
+        return 'pristine';
+    const recorded = readSkillHash(installed);
+    if (!recorded)
+        return 'unknown';
+    return recorded === hashSkillContent(installed) ? 'pristine' : 'modified';
 }
 function versionParts(version) {
     return version.split('.').map((n) => Number.parseInt(n, 10) || 0);
@@ -71,9 +124,10 @@ export function isNewerVersion(a, b) {
 /** The skill source and the package version that will be stamped into it. */
 export async function readShippedSkill(name = SHIPPED_SKILL) {
     const root = getPackageRoot();
-    const content = await fs.readFile(path.join(root, 'skills', name, 'SKILL.md'), 'utf8');
+    const file = path.join(root, 'skills', name, 'SKILL.md');
+    const content = await fs.readFile(file, 'utf8');
     const pkg = await fs.readJson(path.join(root, 'package.json'));
-    return { content, version: String(pkg.version) };
+    return { content, version: String(pkg.version), file };
 }
 /** Whether `file` is itself a symlink, as opposed to merely resolving through one. */
 async function isSymlink(file) {
@@ -94,7 +148,7 @@ async function isSymlink(file) {
  * rename *replaces* the symlink with a real file, orphaning the dotfiles copy
  * with no error at all, which is the split-brain this feature exists to end.
  */
-export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL) {
+export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL, { force = false } = {}) {
     const shipped = await readShippedSkill(name);
     const file = path.join(skillsDir, name, 'SKILL.md');
     const existing = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf8') : null;
@@ -102,8 +156,10 @@ export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL) {
     const viaSymlink = await isSymlink(file);
     const base = {
         name,
+        contentState: existing === null ? null : classifySkillContent(existing, shipped.content),
         file,
         viaSymlink,
+        shippedFile: shipped.file,
         realFile: viaSymlink ? await fs.realpath(file) : file,
         installedVersion,
         shippedVersion: shipped.version,
@@ -111,7 +167,13 @@ export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL) {
     if (installedVersion && isNewerVersion(installedVersion, shipped.version)) {
         return { ...base, status: 'declined-downgrade' };
     }
-    const next = stampSkillVersion(shipped.content, shipped.version);
+    // Only `pristine` content is provably ours to replace. Anything else is a
+    // fork (or unprovable, which for a destructive write is the same thing) and
+    // stays a human decision — the same rule `fix copied-assets` follows (#448).
+    if (!force && base.contentState !== null && base.contentState !== 'pristine') {
+        return { ...base, status: 'declined-fork' };
+    }
+    const next = stampSkill(shipped.content, shipped.version);
     if (existing === next)
         return { ...base, status: 'up-to-date' };
     await fs.ensureDir(path.dirname(file));
@@ -120,12 +182,13 @@ export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL) {
 }
 /** Read-only counterpart of `installClaudeSkill`, for doctor. */
 export async function claudeSkillStatus(name = SHIPPED_SKILL, explicit) {
-    const { version } = await readShippedSkill(name);
+    const shipped = await readShippedSkill(name);
     const { dir } = await resolveSkillsDir(explicit);
     const absent = {
         installed: false,
         installedVersion: null,
-        shippedVersion: version,
+        shippedVersion: shipped.version,
+        contentState: null,
         needsInstall: true,
     };
     if (!dir)
@@ -133,12 +196,16 @@ export async function claudeSkillStatus(name = SHIPPED_SKILL, explicit) {
     const file = path.join(dir, name, 'SKILL.md');
     if (!(await fs.pathExists(file)))
         return { file, ...absent };
-    const installedVersion = readSkillVersion(await fs.readFile(file, 'utf8'));
+    const content = await fs.readFile(file, 'utf8');
+    const installedVersion = readSkillVersion(content);
+    const contentState = classifySkillContent(content, shipped.content);
+    const behind = installedVersion === null || isNewerVersion(shipped.version, installedVersion);
     return {
         file,
         installed: true,
         installedVersion,
-        shippedVersion: version,
-        needsInstall: installedVersion === null || isNewerVersion(version, installedVersion),
+        shippedVersion: shipped.version,
+        contentState,
+        needsInstall: behind && contentState === 'pristine',
     };
 }

package/dist/cli/index.js

@@ -329,6 +329,9 @@ program
     .option('--resync', 'Re-scaffold every file recorded in .repo-tooling.json')
     .option('--diff', 'Show a unified diff of each change before confirming')
     .option('--skills-dir <path>', 'Where `fix claude-skills` installs user-global agent skills (default: ~/.claude/skills). Required with --yes/--json when that directory does not exist')
+    // Deliberately not folded into --yes: unattended runs pass --yes, and this is
+    // the one overwrite that destroys work living outside the repo (#480).
+    .option('--force-skills', 'Let `fix claude-skills` overwrite a locally modified skill instead of refusing')
     .action((target, options) => fixCommand(target, {
     directory: options.directory,
     yes: options.yes,
@@ -338,6 +341,7 @@ program
     resync: options.resync,
     diff: options.diff,
     skillsDir: options.skillsDir,
+    forceSkills: options.forceSkills,
 }));
 program.hook('preAction', async (_, actionCommand) => {
     const name = actionCommand.name();

package/package.json

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