@boopkit/cli 0.6.12 → 0.6.14

package/dist/commands/migrate-skill-edits.d.ts

@@ -0,0 +1,24 @@
+import { ApplyDeps, ApplyResult } from '../lib/apply-skill-edits';
+import { FindOriginalTextOptions } from '../lib/original-text';
+import { SkillEditOutcome } from '../lib/skill-edits';
+/** Replaceable in tests, so no test reaches the npm registry. */
+export type MigrateSkillEditsDeps = FindOriginalTextOptions;
+/**
+ * Write a decision plan for every skill edited in SKILL.md. Changes no skill,
+ * no PROJECT.md and no manifest: only files under `.boop/skill-edits/`.
+ */
+export declare function runMigrateSkillEdits(deps?: MigrateSkillEditsDeps): void;
+/**
+ * `--run`: apply every decided plan that passes its checks, and list the rest
+ * with the reason each was refused. A drop is applied only once a person at a
+ * terminal agrees to it.
+ */
+export declare function runApplySkillEdits(deps?: ApplyDeps): Promise<void>;
+/**
+ * Put a yes-or-no question to a person. Anything but y or yes is no, and so is
+ * ending input instead of answering (Ctrl+D), which would otherwise reject at a
+ * terminal and never settle on a stream.
+ */
+export declare function askYesNo(question: string, input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<boolean>;
+export declare function formatApplyResult(result: ApplyResult): string;
+export declare function formatOutcomes(outcomes: SkillEditOutcome[]): string;

package/dist/commands/migrate-skill-edits.js

@@ -0,0 +1,190 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMigrateSkillEdits = runMigrateSkillEdits;
+exports.runApplySkillEdits = runApplySkillEdits;
+exports.askYesNo = askYesNo;
+exports.formatApplyResult = formatApplyResult;
+exports.formatOutcomes = formatOutcomes;
+const readline = __importStar(require("readline/promises"));
+const apply_skill_edits_1 = require("../lib/apply-skill-edits");
+const project_1 = require("../lib/project");
+const skill_edits_1 = require("../lib/skill-edits");
+const update_1 = require("../lib/update");
+/**
+ * Write a decision plan for every skill edited in SKILL.md. Changes no skill,
+ * no PROJECT.md and no manifest: only files under `.boop/skill-edits/`.
+ */
+function runMigrateSkillEdits(deps = {}) {
+    const projectDir = process.cwd();
+    const manifest = (0, project_1.readProjectManifest)(projectDir);
+    if (!manifest) {
+        console.error('\x1b[31mERR\x1b[0m Not a boop project (no .boop/config.json). Run `boop init` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const outcomes = (0, skill_edits_1.writeSkillEditPlans)(projectDir, manifest, deps);
+    console.log(formatOutcomes(outcomes));
+}
+/**
+ * `--run`: apply every decided plan that passes its checks, and list the rest
+ * with the reason each was refused. A drop is applied only once a person at a
+ * terminal agrees to it.
+ */
+async function runApplySkillEdits(deps = terminalDeps()) {
+    const projectDir = process.cwd();
+    const manifest = (0, project_1.readProjectManifest)(projectDir);
+    if (!manifest) {
+        console.error('\x1b[31mERR\x1b[0m Not a boop project (no .boop/config.json). Run `boop init` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const result = await (0, apply_skill_edits_1.applySkillEditPlans)(projectDir, manifest, deps);
+    console.log(formatApplyResult(result));
+    if (result.outcomes.some(o => o.kind !== 'applied'))
+        process.exitCode = 1;
+}
+function terminalDeps() {
+    return {
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        confirm: question => askYesNo(question),
+    };
+}
+/**
+ * Put a yes-or-no question to a person. Anything but y or yes is no, and so is
+ * ending input instead of answering (Ctrl+D), which would otherwise reject at a
+ * terminal and never settle on a stream.
+ */
+async function askYesNo(question, input = process.stdin, output = process.stdout) {
+    const prompt = readline.createInterface({ input, output });
+    const closed = new Promise(resolve => prompt.once('close', () => resolve('')));
+    try {
+        const answer = await Promise.race([prompt.question(`${question} [y/N] `).catch(() => ''), closed]);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
+function formatApplyResult(result) {
+    const lines = [];
+    const applied = result.outcomes.filter((o) => o.kind === 'applied');
+    const notApplied = result.outcomes.filter(o => o.kind !== 'applied');
+    if (result.outcomes.length === 0) {
+        lines.push(`No plans in ${skill_edits_1.SKILL_EDITS_DIR}/ to apply. Run \`boop migrate-skill-edits\` to write them.`);
+    }
+    if (applied.length > 0) {
+        lines.push(`Applied ${plural(applied.length, 'plan')}:`);
+        for (const plan of applied) {
+            lines.push(`  \x1b[32m✓\x1b[0m ${plan.skillPath}: restored boop's copy; the edited copy is at ${plan.backupPath}`);
+            for (const rule of plan.rules) {
+                lines.push(`    ${rule.edit}: moved to ${plan.projectFile}, under ${rule.heading}${rule.reason ? ` — ${rule.reason}` : ''}`);
+            }
+            for (const drop of plan.drops)
+                lines.push(`    Dropped ${drop.edit}: ${drop.reason}`);
+        }
+    }
+    if (notApplied.length > 0) {
+        if (lines.length > 0)
+            lines.push('');
+        lines.push(`Applied nothing from ${notApplied.length === 1 ? 'this plan' : `these ${notApplied.length} plans`}:`);
+        for (const plan of notApplied) {
+            lines.push(`  \x1b[31m✗\x1b[0m ${plan.planPath}`);
+            if (plan.kind === 'refused') {
+                for (const reason of plan.reasons)
+                    lines.push(`    ${reason}`);
+            }
+            else if (plan.kind === 'needs-person') {
+                lines.push('    It drops edits, and a drop needs a person to agree to it at a yes-or-no prompt, which this shell cannot show. ' +
+                    'A person must confirm this by running `boop migrate-skill-edits --run` themselves. The drops:', ...dropLines(plan.drops));
+            }
+            else {
+                lines.push('    A person declined these drops. Change their decisions in the plan and run again:', ...dropLines(plan.declined));
+            }
+        }
+    }
+    if (result.recordedHashes.length > 0) {
+        if (lines.length > 0)
+            lines.push('');
+        lines.push(`Recorded the hash of ${plural(result.recordedHashes.length, 'skill')} that already held boop's copy:`);
+        for (const skill of result.recordedHashes)
+            lines.push(`  · ${skill}`);
+    }
+    return lines.join('\n');
+}
+function dropLines(drops) {
+    return drops.map(drop => `      ${drop.edit}: ${drop.reason}`);
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+function formatOutcomes(outcomes) {
+    const written = outcomes.filter((o) => o.kind === 'written');
+    const kept = outcomes.filter(o => o.kind === 'kept');
+    const handSplit = outcomes.filter((o) => o.kind === 'hand-split');
+    if (outcomes.length === 0)
+        return 'No skill is edited in SKILL.md, so there is nothing to migrate.';
+    const lines = [];
+    if (written.length > 0) {
+        lines.push(`Wrote ${written.length} plan${written.length === 1 ? '' : 's'} to ${skill_edits_1.SKILL_EDITS_DIR}/:`);
+        for (const plan of written) {
+            const notes = [`${plan.edits} edit${plan.edits === 1 ? '' : 's'}`];
+            if (plan.boopChanged)
+                notes.push('boop has changes waiting');
+            if (plan.replacedStale)
+                notes.push('replaced a plan written for older text; the old one is beside it as .bak');
+            lines.push(`  \x1b[33m◐\x1b[0m ${plan.planPath} (${notes.join(', ')})`);
+            if (plan.comparedWithoutOriginal) {
+                lines.push("    Could not find the text boop installed, in git history or on npm. The plan compares this project's copy " +
+                    "with what boop ships now, which cannot tell the project's edits from boop's changes, so every difference needs a decision.");
+            }
+        }
+    }
+    if (kept.length > 0) {
+        lines.push(`Left ${kept.length} plan${kept.length === 1 ? '' : 's'} as they were, because the skill and boop's copy have not changed since they were written:`);
+        for (const plan of kept)
+            lines.push(`  · ${plan.planPath}`);
+    }
+    if (handSplit.length > 0) {
+        lines.push(`Split ${handSplit.length === 1 ? 'this skill' : 'these skills'} by hand. boop has no record of installing ${handSplit.length === 1 ? 'it' : 'them'}, so there is no original to compare against:`);
+        for (const skill of handSplit) {
+            lines.push(`  \x1b[33m◐\x1b[0m ${skill.relativePath}${skill.upstreamPath ? ` (boop's current copy is at ${skill.upstreamPath})` : ''}`);
+        }
+    }
+    if (written.length + kept.length > 0) {
+        lines.push('', `Next: record a decision for every edit in each plan, following the ${update_1.TRIAGE_SKILL} skill.`);
+    }
+    return lines.join('\n');
+}

package/dist/commands/status.d.ts

@@ -11,6 +11,14 @@ export interface CapabilityStatus {
     nextSteps?: string[];
     optionalSteps?: string[];
     reachable?: boolean;
+    /** Skills whose SKILL.md this project has edited, which no boop update can improve until the edits move out */
+    skillEdits?: SkillEditsStatus;
+}
+export interface SkillEditsStatus {
+    edited: number;
+    /** How many of the edited skills boop has also changed since they were installed */
+    changesWaiting: number;
+    instruction: string;
 }
 export interface StatusData {
     name: string;

package/dist/commands/status.js

@@ -45,6 +45,7 @@ const env_1 = require("../lib/env");
 const capability_1 = require("../lib/capability");
 const interpolate_1 = require("../lib/interpolate");
 const db_status_1 = require("../lib/db-status");
+const update_1 = require("../lib/update");
 function formatStatus(manifest) {
     const caps = manifest.capabilities.length > 0
         ? manifest.capabilities.join(', ')
@@ -156,6 +157,13 @@ function getStatusData(manifest, dir) {
             capabilities[capName] = { status: 'pending', type: capType, env: envStatus, nextSteps };
         }
     }
+    // The one check no capability declares: it comes from the same hash comparison `boop update` makes
+    for (const capName of manifest.capabilities) {
+        const counts = (0, update_1.countSkillEdits)(dir, capName, manifest);
+        if (counts) {
+            capabilities[capName].skillEdits = { ...counts, instruction: update_1.SKILL_EDITS_INSTRUCTION };
+        }
+    }
     return { name: manifest.name, profile: manifest.profile, capabilities };
 }
 // Re-export for backward compatibility in tests
@@ -248,6 +256,11 @@ function formatCapabilityLine(capName, cap) {
             }
         }
     }
+    if (cap.skillEdits) {
+        const { edited, changesWaiting, instruction } = cap.skillEdits;
+        lines.push(`                    \x1b[33m◐\x1b[0m ${edited} skill${edited === 1 ? '' : 's'} edited in SKILL.md, ${changesWaiting} with boop changes waiting`);
+        lines.push(`                    → ${instruction}`);
+    }
     return lines;
 }
 /**

package/dist/commands/update.js

@@ -103,17 +103,24 @@ function runUpdate(capabilityName, options) {
         }
         for (const plan of plans) {
             console.log(`\n${plan.capability}:`);
-            if (plan.upToDate) {
+            // Recording a hash for a file that already holds what boop ships changes nothing the project can see
+            const visible = plan.actions.filter(a => a.action !== 'record-hash');
+            if (visible.length === 0) {
                 console.log('  Already up to date');
                 continue;
             }
-            for (const action of plan.actions) {
+            for (const action of visible) {
+                if (isEditDoingItsJob(action))
+                    continue;
                 const icon = action.action === 'overwrite' ? '\x1b[32m↑\x1b[0m'
                     : action.action === 'skip' ? '\x1b[33m◐\x1b[0m'
                         : action.action === 'add' ? '\x1b[32m+\x1b[0m'
                             : action.action === 'migrate' ? '\x1b[36m↗\x1b[0m'
                                 : '\x1b[90m⚠\x1b[0m';
-                console.log(`  ${icon} ${action.relativePath} — ${action.reason}`);
+                const label = action.action === 'skip' && (action.drift || action.instruction) ? skipLabel(action) : action.reason;
+                console.log(`  ${icon} ${action.relativePath} — ${label}`);
+                if (action.instruction)
+                    console.log(instructionLine(action.instruction));
             }
         }
         if (stale.length > 0) {
@@ -136,15 +143,18 @@ function runUpdate(capabilityName, options) {
                 pruned: [],
                 migrated: [],
                 unchangedCount: plan.unchangedCount,
+                instructions: [],
             });
             continue;
         }
         const result = (0, update_1.executeUpdatePlan)(plan, { force: options.force, restore: options.restore, prune: options.prune });
         results.push(result);
     }
-    // Refresh .claude/skills/ symlinks for any new skill folders added by this update
+    // Refresh .claude/skills/ symlinks for any new skill folders added by this update,
+    // and put back any PROJECT.md the project has deleted
     if (!options.dryRun) {
         (0, scaffold_1.linkSkillsToClaude)(targetDir);
+        (0, scaffold_1.createSkillProjectFiles)(targetDir);
     }
     // A script that contradicts the settings a capability now ships survives the
     // update, because scripts are only merged when absent. Say so, or fix it on
@@ -164,9 +174,11 @@ function runUpdate(capabilityName, options) {
         return;
     }
     console.log(`\n${'─'.repeat(40)}`);
-    for (const result of results) {
+    results.forEach((result, i) => {
         const summary = (0, update_1.formatUpdateSummary)(result);
         console.log(`${result.capability}: ${summary}`);
+        const actionFor = (f) => plans[i].actions.find(a => a.relativePath === f);
+        const instructionFor = (f) => result.instructions.find(entry => entry.relativePath === f)?.instruction;
         // Show details for non-trivial updates
         for (const f of result.migrated || []) {
             console.log(`  \x1b[36m↗\x1b[0m ${f} (migrated to folder)`);
@@ -178,12 +190,21 @@ function runUpdate(capabilityName, options) {
             else {
                 console.log(`  \x1b[32m↑\x1b[0m ${f}`);
             }
+            const instruction = instructionFor(f);
+            if (instruction)
+                console.log(instructionLine(instruction));
         }
         for (const f of result.skipped) {
+            const action = actionFor(f);
+            const instruction = instructionFor(f);
             if (result.skippedDeleted?.includes(f)) {
                 console.log(`  \x1b[36mℹ\x1b[0m ${f} (locally deleted, skipped — use --restore to re-add)`);
             }
-            else {
+            else if (instruction) {
+                console.log(`  \x1b[33m◐\x1b[0m ${f} (${skipLabel(action)})`);
+                console.log(instructionLine(instruction));
+            }
+            else if (!action || !isEditDoingItsJob(action)) {
                 console.log(`  \x1b[33m◐\x1b[0m ${f} (locally modified, skipped)`);
             }
         }
@@ -198,7 +219,7 @@ function runUpdate(capabilityName, options) {
                 console.log(`  \x1b[33m⚠\x1b[0m ${f} (deprecated — removed from package, use --prune to delete)`);
             }
         }
-    }
+    });
     for (const fixed of fixedScripts) {
         console.log(`\n\x1b[32m✓\x1b[0m package.json script "${fixed.name}" rewritten: ${fixed.command} → ${fixed.rewritten}`);
     }
@@ -206,6 +227,33 @@ function runUpdate(capabilityName, options) {
         console.log(`\n${(0, stale_scripts_1.formatStaleScriptWarning)(remainingStale)}`);
     }
 }
+/**
+ * A reference page or code file the project edited, and boop has not, is doing
+ * what those files are for, so the report does not list it.
+ */
+function isEditDoingItsJob(action) {
+    return action.action === 'skip' && action.drift !== undefined && !action.instruction;
+}
+/** What the report says happened to a file the update skipped */
+function skipLabel(action) {
+    if (action?.drift === 'project-only')
+        return 'edited here, skipped';
+    if (action?.drift === 'both-changed') {
+        return action.fileKind === 'skill'
+            ? 'edited here, and boop has changes waiting, skipped'
+            : 'changed here and in boop, skipped';
+    }
+    if (action?.replacedBy)
+        return 'old single-file skill, edited here, skipped';
+    if (action?.oldPath)
+        return `not installed while ${action.oldPath} is edited, skipped`;
+    if (action?.instruction)
+        return 'not tracked by boop, skipped';
+    return 'locally modified, skipped';
+}
+function instructionLine(instruction) {
+    return `      → ${instruction}`;
+}
 /**
  * Read the project's package.json scripts and return those that contradict the
  * runner settings the capabilities now ship. Missing or unreadable package.json

package/dist/lib/apply-skill-edits.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The applying half of `boop migrate-skill-edits`: check each decided plan,
+ * move its kept and offered rules into PROJECT.md, hand SKILL.md back to boop,
+ * and record boop's hash, so the skill reads as unmodified at once.
+ */
+import { BoopManifest } from './project';
+/**
+ * The block every boop SKILL.md opens with. Keep in step with POINTER_BLOCK in
+ * tools/audit-skill-links.js, which holds the shipped skills to it.
+ */
+export declare const POINTER_BLOCK: string;
+/** The PROJECT.md heading each kind of rule goes under */
+export declare const RULE_HEADINGS: {
+    readonly adds: "Adds";
+    readonly narrows: "Narrows";
+    readonly overrides: "Overrides";
+    readonly offer: "Offered to boop";
+};
+export interface ApplyDeps {
+    /** Whether a person is at a terminal to answer the prompt a drop needs */
+    interactive: boolean;
+    /** Ask a yes-or-no question; resolves true for yes */
+    confirm: (question: string) => Promise<boolean>;
+}
+export interface Drop {
+    edit: string;
+    reason: string;
+}
+export interface Rule {
+    edit: string;
+    heading: string;
+    rule: string;
+    /** What the rewritten rule left out, when the triage skill recorded it */
+    reason?: string;
+}
+export type PlanOutcome = {
+    kind: 'applied';
+    planPath: string;
+    skillPath: string;
+    projectFile: string;
+    backupPath: string;
+    rules: Rule[];
+    drops: Drop[];
+} | {
+    kind: 'refused';
+    planPath: string;
+    reasons: string[];
+}
+/** Checks passed, but it drops edits and nobody is at a terminal to agree */
+ | {
+    kind: 'needs-person';
+    planPath: string;
+    drops: Drop[];
+} | {
+    kind: 'declined';
+    planPath: string;
+    declined: Drop[];
+};
+export interface ApplyResult {
+    outcomes: PlanOutcome[];
+    /** Skills that already held boop's copy, whose hash this run recorded */
+    recordedHashes: string[];
+}
+/**
+ * Check every plan in `.boop/skill-edits/`, apply each one that passes, and
+ * record the hash of every skill that already holds boop's copy. A plan that
+ * fails any check, or whose drops nobody confirms, has nothing applied.
+ */
+export declare function applySkillEditPlans(projectDir: string, manifest: BoopManifest, deps: ApplyDeps): Promise<ApplyResult>;
+/** Whether a SKILL.md's body, below its frontmatter, opens with the pointer block. */
+export declare function opensWithPointer(markdown: string): boolean;
+/**
+ * Append a rule to the end of a section of PROJECT.md, adding the heading at
+ * the end of the file when the project has removed it.
+ */
+export declare function addRule(text: string, heading: string, rule: string): string;