@boopkit/cli 0.6.13 → 0.6.15

package/dist/lib/update.js

@@ -39,9 +39,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_EDITS_INSTRUCTION = exports.TRIAGE_SKILL = void 0;
 exports.compareFileHash = compareFileHash;
 exports.planCapabilityUpdate = planCapabilityUpdate;
 exports.executeUpdatePlan = executeUpdatePlan;
+exports.countSkillEdits = countSkillEdits;
 exports.formatUpdateSummary = formatUpdateSummary;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -50,6 +52,11 @@ const capability_1 = require("./capability");
 const project_1 = require("./project");
 const safe_io_1 = require("./safe-io");
 const install_layout_1 = require("./install-layout");
+const script_merge_1 = require("./script-merge");
+/** The skill that splits a drifted SKILL.md — keep in step with the folder name boop-rm2l.8 gives it */
+exports.TRIAGE_SKILL = 'boop-skills-edit-triage';
+/** What to do about skills edited in SKILL.md, for a report that counts them */
+exports.SKILL_EDITS_INSTRUCTION = `Move each skill's edits into the PROJECT.md beside it: run \`boop migrate-skill-edits\` and follow the ${exports.TRIAGE_SKILL} skill.`;
 /**
  * Compare a file's current hash against a stored hash.
  */
@@ -81,6 +88,10 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
     if (!boopkit?.capability)
         return null;
     const newVersion = pkgJson.version || '0.0.0';
+    // The capability as this package declares it: the npm scripts merged below,
+    // and the skill migrations applied further down.
+    const capJsonPath = path.join(pkgDir, 'capability.json');
+    const capJson = fs.existsSync(capJsonPath) ? JSON.parse(fs.readFileSync(capJsonPath, 'utf-8')) : {};
     const meta = projectManifest.capabilityMeta?.[capabilityName];
     const storedHashes = meta?.fileHashes || {};
     const actions = [];
@@ -96,9 +107,22 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
         const destPath = path.join(targetDir, relPath);
         const storedHash = storedHashes[relPath];
         const newHash = (0, scaffold_1.hashFile)(srcPath);
+        const fileKind = fileKindOf(relPath);
         if (!storedHash) {
             // New file — not in stored hashes
-            if (fs.existsSync(destPath)) {
+            if (fs.existsSync(destPath) && (0, scaffold_1.hashFile)(destPath) === newHash) {
+                // Untracked but already holds what boop ships, as a hand-split skill does — start tracking it
+                actions.push({
+                    relativePath: relPath,
+                    action: 'record-hash',
+                    reason: 'Locally matches package',
+                    currentHash: newHash,
+                    newHash,
+                    drift: 'already-upstream',
+                    fileKind,
+                });
+            }
+            else if (fs.existsSync(destPath)) {
                 // File exists but wasn't tracked — treat as modified (skip)
                 actions.push({
                     relativePath: relPath,
@@ -106,6 +130,8 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
                     reason: 'File exists but has no stored hash (untracked)',
                     currentHash: (0, scaffold_1.hashFile)(destPath),
                     newHash,
+                    fileKind,
+                    ...skipInstruction(targetDir, relPath, srcPath, fileKind),
                 });
             }
             else {
@@ -114,6 +140,7 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
                     action: 'add',
                     reason: 'New file from package',
                     newHash,
+                    fileKind,
                 });
             }
             continue;
@@ -134,19 +161,40 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
                     storedHash,
                     currentHash: storedHash,
                     newHash,
+                    fileKind,
+                    instruction: fileKind === 'skill' ? offeredRulesInstruction(targetDir, relPath) : undefined,
                 });
                 break;
-            case 'modified':
-                // Locally modified — skip with warning
+            case 'modified': {
+                const currentHash = (0, scaffold_1.hashFile)(destPath);
+                if (currentHash === newHash) {
+                    // Already holds what boop ships — move the base forward, or it reads as modified forever
+                    actions.push({
+                        relativePath: relPath,
+                        action: 'record-hash',
+                        reason: 'Locally matches package',
+                        storedHash,
+                        currentHash,
+                        newHash,
+                        drift: 'already-upstream',
+                        fileKind,
+                    });
+                    break;
+                }
+                const drift = newHash === storedHash ? 'project-only' : 'both-changed';
                 actions.push({
                     relativePath: relPath,
                     action: 'skip',
                     reason: 'Locally modified',
                     storedHash,
-                    currentHash: (0, scaffold_1.hashFile)(destPath),
+                    currentHash,
                     newHash,
+                    drift,
+                    fileKind,
+                    ...skipInstruction(targetDir, relPath, srcPath, fileKind, drift),
                 });
                 break;
+            }
             case 'missing':
                 // File was deleted locally — respect user's deletion, skip by default
                 actions.push({
@@ -155,6 +203,7 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
                     reason: 'Locally deleted',
                     storedHash,
                     newHash,
+                    fileKind,
                 });
                 break;
         }
@@ -171,53 +220,59 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
         }
     }
     // Apply skill migration logic: upgrade deprecate+add pairs to migrate actions
-    const capJsonPath = path.join(pkgDir, 'capability.json');
-    if (fs.existsSync(capJsonPath)) {
-        const capJson = JSON.parse(fs.readFileSync(capJsonPath, 'utf-8'));
-        const migrations = capJson.skill_migrations;
-        if (migrations) {
-            for (const [newSkillName, oldFlatFilename] of Object.entries(migrations)) {
-                const oldRelPath = path.join('skills', oldFlatFilename);
-                const newPrefix = path.join('skills', newSkillName) + path.sep;
-                const oldStoredHash = storedHashes[oldRelPath];
-                if (!oldStoredHash)
-                    continue;
-                const oldFilePath = path.join(targetDir, oldRelPath);
-                const oldState = compareFileHash(oldFilePath, oldStoredHash);
-                if (oldState === 'modified') {
-                    // User modified the old file — skip new folder files, keep old file
-                    for (const action of actions) {
-                        if (action.relativePath.startsWith(newPrefix) || action.relativePath === path.join('skills', newSkillName)) {
-                            action.action = 'skip';
-                            action.reason = `Skipped: old skill file '${oldRelPath}' was locally modified`;
-                        }
-                    }
-                    // Change deprecate to skip for the old file
-                    const oldAction = actions.find(a => a.relativePath === oldRelPath);
-                    if (oldAction) {
-                        oldAction.action = 'skip';
-                        oldAction.reason = 'Locally modified (migration skipped)';
+    const migrations = capJson.skill_migrations;
+    if (migrations) {
+        for (const [newSkillName, oldFlatFilename] of Object.entries(migrations)) {
+            const oldRelPath = path.join('skills', oldFlatFilename);
+            const newPrefix = path.join('skills', newSkillName) + path.sep;
+            const oldStoredHash = storedHashes[oldRelPath];
+            if (!oldStoredHash)
+                continue;
+            const oldFilePath = path.join(targetDir, oldRelPath);
+            const oldState = compareFileHash(oldFilePath, oldStoredHash);
+            if (oldState === 'modified') {
+                // User modified the old file — keep it, and don't install the folder that replaces it.
+                // A folder file already installed has its own comparison, so only an install is held back.
+                for (const action of actions) {
+                    if (action.action === 'add' && (action.relativePath.startsWith(newPrefix) || action.relativePath === path.join('skills', newSkillName))) {
+                        action.action = 'skip';
+                        action.reason = `Skipped: old skill file '${oldRelPath}' was locally modified`;
+                        action.oldPath = oldRelPath;
+                        action.instruction = `boop installs this once ${oldRelPath} is gone; see what to do about that file.`;
                     }
                 }
-                else if (oldState === 'match') {
-                    // Old file unmodified — convert deprecate to migrate
-                    const oldAction = actions.find(a => a.relativePath === oldRelPath);
-                    if (oldAction) {
-                        oldAction.action = 'migrate';
-                        oldAction.reason = `Migrated to folder: skills/${newSkillName}/`;
-                    }
-                    // Tag new folder files with the old path they're replacing
-                    for (const action of actions) {
-                        if (action.relativePath.startsWith(newPrefix) || action.relativePath === path.join('skills', newSkillName)) {
-                            action.oldPath = oldRelPath;
-                        }
+                // Change deprecate to skip for the old file
+                const oldAction = actions.find(a => a.relativePath === oldRelPath);
+                if (oldAction) {
+                    const projectFile = path.join('skills', newSkillName, 'PROJECT.md');
+                    oldAction.action = 'skip';
+                    oldAction.reason = 'Locally modified (migration skipped)';
+                    oldAction.replacedBy = newSkillName;
+                    oldAction.instruction = `This is the old single-file form of the ${newSkillName} skill, and this project edited it. ` +
+                        `Move the rules this project needs from it into ${projectFile}, following the ${exports.TRIAGE_SKILL} skill, then delete it and run \`boop update\`.`;
+                }
+            }
+            else if (oldState === 'match') {
+                // Old file unmodified — convert deprecate to migrate
+                const oldAction = actions.find(a => a.relativePath === oldRelPath);
+                if (oldAction) {
+                    oldAction.action = 'migrate';
+                    oldAction.reason = `Migrated to folder: skills/${newSkillName}/`;
+                }
+                // Tag new folder files with the old path they're replacing
+                for (const action of actions) {
+                    if (action.relativePath.startsWith(newPrefix) || action.relativePath === path.join('skills', newSkillName)) {
+                        action.oldPath = oldRelPath;
                     }
                 }
-                // oldState === 'missing': old file already gone, add new files normally
             }
+            // oldState === 'missing': old file already gone, add new files normally
         }
     }
-    const upToDate = actions.length === 0;
+    // A capability that ships a new command ships it as a file and a script; an
+    // update that delivered only the file left nothing able to run it (boop-ldou).
+    const scriptActions = (0, script_merge_1.planScriptUpdates)(capJson.scripts, (0, script_merge_1.readProjectScripts)(targetDir));
+    const upToDate = actions.length === 0 && !scriptActions.some(a => a.action === 'add');
     return {
         capability: capabilityName,
         targetDir,
@@ -225,6 +280,7 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
         currentVersion: meta?.version,
         newVersion,
         actions,
+        scriptActions,
         unchangedCount,
         upToDate,
     };
@@ -244,7 +300,10 @@ function executeUpdatePlan(plan, options = {}) {
         skippedDeleted: [],
         pruned: [],
         migrated: [],
+        scriptsAdded: [],
+        scriptsKept: [],
         unchangedCount: plan.unchangedCount,
+        instructions: [],
     };
     const pkgJson = JSON.parse(fs.readFileSync(path.join(plan.packageDir, 'package.json'), 'utf-8'));
     const boopkit = pkgJson.boopkit;
@@ -264,9 +323,16 @@ function executeUpdatePlan(plan, options = {}) {
                     fs.copyFileSync(srcPath, destPath);
                     newHashes[action.relativePath] = (0, scaffold_1.hashFile)(destPath);
                     result.overwritten.push(action.relativePath);
+                    if (action.instruction) {
+                        result.instructions.push({ relativePath: action.relativePath, instruction: action.instruction });
+                    }
                 }
                 break;
             }
+            case 'record-hash':
+                newHashes[action.relativePath] = action.newHash;
+                result.unchangedCount++;
+                break;
             case 'skip': {
                 const isLocallyDeleted = action.reason === 'Locally deleted';
                 if (isLocallyDeleted && options.restore) {
@@ -291,6 +357,10 @@ function executeUpdatePlan(plan, options = {}) {
                         newHashes[action.relativePath] = (0, scaffold_1.hashFile)(destPath);
                         result.overwritten.push(action.relativePath);
                         result.forcedOverwrite.push(action.relativePath);
+                        const instruction = action.fileKind === 'skill' ? offeredRulesInstruction(plan.targetDir, action.relativePath) : undefined;
+                        if (instruction) {
+                            result.instructions.push({ relativePath: action.relativePath, instruction });
+                        }
                         console.warn(`\x1b[33mWARN\x1b[0m Force-overwriting modified file: ${action.relativePath} (backup saved as ${action.relativePath}.bak)`);
                     }
                 }
@@ -299,6 +369,13 @@ function executeUpdatePlan(plan, options = {}) {
                     if (isLocallyDeleted) {
                         result.skippedDeleted.push(action.relativePath);
                     }
+                    if (action.instruction) {
+                        result.instructions.push({
+                            relativePath: action.relativePath,
+                            instruction: action.instruction,
+                            upstreamPath: action.upstreamPath,
+                        });
+                    }
                     // Keep existing hash unchanged
                 }
                 break;
@@ -341,6 +418,11 @@ function executeUpdatePlan(plan, options = {}) {
             }
         }
     }
+    // Merge the capability's npm scripts, so a command it ships as file + script
+    // arrives whole. Additive only: a name the project already uses is left alone.
+    const scriptActions = plan.scriptActions ?? [];
+    result.scriptsAdded = (0, script_merge_1.applyScriptUpdates)(plan.targetDir, scriptActions);
+    result.scriptsKept = scriptActions.filter(a => a.action === 'keep');
     // Update .boop/config.json
     if (manifest) {
         if (!manifest.capabilityMeta) {
@@ -355,6 +437,79 @@ function executeUpdatePlan(plan, options = {}) {
     }
     return result;
 }
+/**
+ * What to tell whoever ran the update about a file it skipped, or nothing.
+ * `drift` is absent for a file boop has no stored hash for.
+ *
+ * An edited SKILL.md always gets an instruction: any edit there is project
+ * content in boop's file. An edited reference page or code file is doing what
+ * those files are for, so it gets one only when boop has changed it too.
+ */
+function skipInstruction(targetDir, relPath, srcPath, fileKind, drift) {
+    const upstreamPath = displayPath(targetDir, srcPath);
+    if (!drift) {
+        const untracked = `boop has no record of installing this file, so it cannot tell this project's changes from its own. boop's current copy is at ${upstreamPath}`;
+        if (fileKind === 'skill') {
+            const projectFile = path.join(path.dirname(relPath), 'PROJECT.md');
+            return {
+                instruction: `${untracked}. Split it by hand: move this project's rules into ${projectFile}, following the ${exports.TRIAGE_SKILL} skill, then copy boop's copy into place, and the next update tracks it.`,
+                upstreamPath,
+            };
+        }
+        return { instruction: `${untracked}; compare the two by hand.`, upstreamPath };
+    }
+    if (fileKind === 'skill') {
+        const projectFile = path.join(path.dirname(relPath), 'PROJECT.md');
+        return {
+            instruction: `Move this project's edits into ${projectFile}: run \`boop migrate-skill-edits\` and follow the ${exports.TRIAGE_SKILL} skill.`,
+        };
+    }
+    if (drift !== 'both-changed')
+        return {};
+    const advice = fileKind === 'reference'
+        ? 'Blend in what applies to this project, following the boop-product-design-reference-integration skill.'
+        : 'Compare the two and take what applies.';
+    return { instruction: `boop's current copy is at ${upstreamPath}. ${advice}`, upstreamPath };
+}
+/**
+ * When an update replaces a SKILL.md whose PROJECT.md offers rules to boop,
+ * boop's new text may now cover them, and a rule left behind would duplicate it.
+ */
+function offeredRulesInstruction(targetDir, relPath) {
+    const projectFile = path.join(path.dirname(relPath), 'PROJECT.md');
+    if (!(0, scaffold_1.hasOfferedRules)(path.join(targetDir, projectFile)))
+        return undefined;
+    return `boop replaced this skill, and ${projectFile} offers rules to boop. Check whether boop's new text covers each rule under "Offered to boop", and delete any it does.`;
+}
+/** A path relative to the project when it lies inside it, as a package in node_modules does */
+function displayPath(targetDir, filePath) {
+    const relative = path.relative(targetDir, filePath);
+    return relative.startsWith('..') || path.isAbsolute(relative) ? filePath : relative;
+}
+/**
+ * Count the skills a capability's project copy has edited in SKILL.md, and how
+ * many of those boop has changed since — from the same comparison `boop update`
+ * makes. Null when there are none, or the capability has no package to compare with.
+ */
+function countSkillEdits(targetDir, capabilityName, projectManifest) {
+    const plan = planCapabilityUpdate(targetDir, capabilityName, projectManifest);
+    const edited = (plan?.actions ?? []).filter(a => a.action === 'skip' && a.fileKind === 'skill' && (a.drift === 'project-only' || a.drift === 'both-changed'));
+    if (edited.length === 0)
+        return null;
+    return { edited: edited.length, changesWaiting: edited.filter(a => a.drift === 'both-changed').length };
+}
+/**
+ * Classify a project-relative destination path: a skill's SKILL.md, a
+ * reference page, or anything else (code, views, config).
+ */
+function fileKindOf(relativePath) {
+    const segments = relativePath.split(path.sep);
+    if (segments.length === 3 && segments[0] === 'skills' && segments[2] === 'SKILL.md')
+        return 'skill';
+    if (relativePath.endsWith('.ref.md'))
+        return 'reference';
+    return 'code';
+}
 /**
  * Resolve the source path a project-relative file was installed from — the
  * placement list read backwards, so it cannot disagree with what was copied.
@@ -388,6 +543,14 @@ function formatUpdateSummary(result) {
     if (result.added.length > 0) {
         parts.push(`added ${result.added.length} new file${result.added.length === 1 ? '' : 's'}`);
     }
+    const scriptsAdded = result.scriptsAdded?.length || 0;
+    if (scriptsAdded > 0) {
+        parts.push(`added ${scriptsAdded} script${scriptsAdded === 1 ? '' : 's'}`);
+    }
+    const scriptsKept = result.scriptsKept?.length || 0;
+    if (scriptsKept > 0) {
+        parts.push(`kept ${scriptsKept} customised script${scriptsKept === 1 ? '' : 's'}`);
+    }
     if (result.pruned && result.pruned.length > 0) {
         parts.push(`pruned ${result.pruned.length} deprecated file${result.pruned.length === 1 ? '' : 's'}`);
     }

package/docs/skills.md

@@ -38,6 +38,7 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 - **boop-get-smart** — When there is a recurring fault in your own behaviour during a chat, run the five whys to find its root cause, and agree a change with the operator that makes it less likely.
 - **boop-so-what** — When the operator asks for the so-what, or says some version of 'thanks for the essay', compress what you just produced into three sentences about what they should care about.
 - **boop-skills-hyperlinking** — When you need to add, review, or repair a `## Related` section that points one skill at another, follow these rules for what earns a link, how to phrase it, which way it points, how many are too many, and how to write a path that survives `boop add`.
+- **boop-skills-edit-triage** — When you need to move a project's edits out of a boop skill's SKILL.md — because `boop update` or `boop status` reports the skill as edited here, or `boop migrate-skill-edits` wrote a plan for it — decide whether each edit is kept in this project, offered to boop, or dropped, and rewrite each kept edit as a standalone rule for the PROJECT.md beside it. Not for reference pages, which are blended rather than split.
 
 ### `testing` — Jest testing setup
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "boop: the opinionated bootstrap for founder friendly, AI-first web apps - code plus agent skills, composable from day one.",
   "main": "dist/cli.js",
   "workspaces": [

package/src/templates/skill-project/PROJECT.md

@@ -0,0 +1,28 @@
+# How this project applies this skill
+
+This file belongs to the project.
+`SKILL.md`, beside it, belongs to boop and is replaced on every `boop update`, so a rule written there is lost.
+boop created this file and never tracks, updates or overwrites it, so write this project's rules here.
+Where this file and `SKILL.md` conflict, this file wins.
+
+Put each rule under the heading that describes it.
+To decide between this file and `SKILL.md`, ask whether the rule would still be true in a brand-new boop project scaffolded tomorrow.
+If it would not, it belongs here.
+If it would, it belongs under "Offered to boop".
+
+## Adds
+
+Rules this project follows that the skill's guidance does not cover.
+
+## Narrows
+
+Where the skill offers a choice, the one this project always makes.
+
+## Overrides
+
+Where this project deliberately contradicts the skill's guidance, and why.
+
+## Offered to boop
+
+Rules that apply here and that this project thinks boop should adopt for every project.
+They stay in effect here until boop ships them.