@boopkit/cli 0.6.13 → 0.6.15

package/dist/lib/skill-edits.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * The mechanical half of splitting a drifted skill: find each skill whose
+ * SKILL.md the project edited, recover the text boop installed, list every
+ * edit, and write one plan per skill for an agent to decide. Nothing here
+ * decides where an edit belongs.
+ */
+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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_EDITS_DIR = void 0;
+exports.writeSkillEditPlans = writeSkillEditPlans;
+exports.diffLines = diffLines;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const original_text_1 = require("./original-text");
+const safe_io_1 = require("./safe-io");
+const install_layout_1 = require("./install-layout");
+const update_1 = require("./update");
+/** Where plans are written, relative to the project. Everything in `.boop/` but config.json is gitignored. */
+exports.SKILL_EDITS_DIR = path.join('.boop', 'skill-edits');
+/**
+ * Find every skill edited in SKILL.md across the project's capabilities and
+ * write a plan for each to `.boop/skill-edits/<skill-name>.md`.
+ *
+ * A plan already written for the current project copy and boop copy is left
+ * alone, because it may hold decisions. One written for other text is backed
+ * up and rewritten. A skill boop has no stored hash for gets no plan.
+ */
+function writeSkillEditPlans(projectDir, manifest, options = {}) {
+    const outcomes = [];
+    for (const capability of manifest.capabilities) {
+        const plan = (0, update_1.planCapabilityUpdate)(projectDir, capability, manifest);
+        for (const action of plan?.actions ?? []) {
+            if (action.fileKind !== 'skill' || action.action !== 'skip')
+                continue;
+            const skill = path.basename(path.dirname(action.relativePath));
+            if (!action.storedHash) {
+                // Untracked; a copy identical to boop's holds nothing to split
+                if (action.currentHash && action.currentHash !== action.newHash) {
+                    outcomes.push({ kind: 'hand-split', skill, relativePath: action.relativePath, upstreamPath: action.upstreamPath });
+                }
+                continue;
+            }
+            if (action.drift !== 'project-only' && action.drift !== 'both-changed')
+                continue;
+            outcomes.push(writePlan(projectDir, capability, skill, action, plan.packageDir, options));
+        }
+    }
+    return outcomes;
+}
+function writePlan(projectDir, capability, skill, action, packageDir, options) {
+    const planRelPath = path.join(exports.SKILL_EDITS_DIR, `${skill}.md`);
+    const planPath = path.join(projectDir, planRelPath);
+    const hashes = { installed: action.storedHash, project: action.currentHash, boop: action.newHash };
+    const existing = readPlanHashes(planPath);
+    if (existing && existing.project === hashes.project && existing.boop === hashes.boop) {
+        return { kind: 'kept', skill, planPath: planRelPath };
+    }
+    const projectText = fs.readFileSync(path.join(projectDir, action.relativePath), 'utf-8');
+    const boopText = fs.readFileSync(boopCopyPath(packageDir, action.relativePath), 'utf-8');
+    const original = (0, original_text_1.findOriginalText)(projectDir, action.relativePath.split(path.sep).join('/'), hashes.installed, options);
+    const baseText = original.found ? original.content : boopText;
+    const baseLines = baseText.split('\n');
+    const projectLines = projectText.split('\n');
+    const edits = diffLines(baseLines, projectLines);
+    const boopChanged = original.found ? action.drift === 'both-changed' : null;
+    const data = {
+        skill,
+        capability,
+        path: action.relativePath.split(path.sep).join('/'),
+        original: original.found ? sourceFields(original.source) : { source: 'none' },
+        comparedWithoutOriginal: !original.found,
+        boopChanged,
+        hashes,
+        decisions: Object.fromEntries(edits.map((_, i) => [editId(i), { decision: null, kind: null, rule: null, reason: null }])),
+    };
+    const body = original.found
+        ? renderBody(data, edits, baseLines, projectLines, boopText.split('\n'))
+        : renderBody(data, edits, baseLines, projectLines, null);
+    fs.mkdirSync(path.dirname(planPath), { recursive: true });
+    const replacedStale = existing !== null;
+    if (replacedStale)
+        (0, safe_io_1.createBackup)(planPath);
+    fs.writeFileSync(planPath, gray_matter_1.default.stringify(body, data));
+    return {
+        kind: 'written',
+        skill,
+        planPath: planRelPath,
+        edits: edits.length,
+        boopChanged,
+        comparedWithoutOriginal: !original.found,
+        replacedStale,
+    };
+}
+/** The hashes an existing plan was written against, or null when there is no readable plan. */
+function readPlanHashes(planPath) {
+    if (!fs.existsSync(planPath))
+        return null;
+    try {
+        return (0, gray_matter_1.default)(fs.readFileSync(planPath, 'utf-8')).data.hashes ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+function boopCopyPath(packageDir, relativePath) {
+    // planCapabilityUpdate hashed this file, so its placement exists
+    return (0, install_layout_1.capabilityPlacementsFromDir)(packageDir).find(p => p.dest === relativePath).source;
+}
+function sourceFields(source) {
+    return source.kind === 'git'
+        ? { source: 'git', commit: source.commit }
+        : { source: 'npm', package: source.package, version: source.version };
+}
+function editId(index) {
+    return `edit-${index + 1}`;
+}
+/**
+ * The edits that turn `base` into `project`: each maximal run of lines that
+ * are not part of a longest common subsequence of the two.
+ */
+function diffLines(base, project) {
+    const edits = [];
+    let baseAt = 0;
+    let projectAt = 0;
+    for (const [i, j] of [...matchLines(base, project), [base.length, project.length]]) {
+        if (i > baseAt || j > projectAt) {
+            edits.push({ baseStart: baseAt, baseEnd: i, projectStart: projectAt, projectEnd: j });
+        }
+        baseAt = i + 1;
+        projectAt = j + 1;
+    }
+    return edits;
+}
+/** Index pairs of the lines two texts share, in order: a longest common subsequence. */
+function matchLines(a, b) {
+    // Most edits leave long runs at both ends untouched, which keeps the table small
+    let prefix = 0;
+    while (prefix < a.length && prefix < b.length && a[prefix] === b[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < a.length - prefix && suffix < b.length - prefix && a[a.length - 1 - suffix] === b[b.length - 1 - suffix])
+        suffix++;
+    const n = a.length - prefix - suffix;
+    const m = b.length - prefix - suffix;
+    // lcs[x][y]: length of the common subsequence of a's middle from x and b's middle from y
+    const width = m + 1;
+    const lcs = new Uint32Array((n + 1) * (m + 1));
+    for (let x = n - 1; x >= 0; x--) {
+        for (let y = m - 1; y >= 0; y--) {
+            lcs[x * width + y] = a[prefix + x] === b[prefix + y]
+                ? lcs[(x + 1) * width + y + 1] + 1
+                : Math.max(lcs[(x + 1) * width + y], lcs[x * width + y + 1]);
+        }
+    }
+    const pairs = [];
+    for (let k = 0; k < prefix; k++)
+        pairs.push([k, k]);
+    let x = 0;
+    let y = 0;
+    while (x < n && y < m) {
+        if (a[prefix + x] === b[prefix + y]) {
+            pairs.push([prefix + x, prefix + y]);
+            x++;
+            y++;
+        }
+        else if (lcs[(x + 1) * width + y] >= lcs[x * width + y + 1]) {
+            x++;
+        }
+        else {
+            y++;
+        }
+    }
+    for (let k = suffix; k > 0; k--)
+        pairs.push([a.length - k, b.length - k]);
+    return pairs;
+}
+/**
+ * What boop now ships in place of base lines [start, end): the smallest
+ * region around them bounded on each side by a line boop kept, so a change
+ * boop made just beside an edit is shown with it.
+ */
+function boopRegion(matches, upstreamLength, baseLength, start, end) {
+    let before = [-1, -1];
+    let after = [baseLength, upstreamLength];
+    for (const pair of matches) {
+        if (pair[0] < start)
+            before = pair;
+        else if (pair[0] >= end) {
+            after = pair;
+            break;
+        }
+    }
+    return { baseStart: before[0] + 1, baseEnd: after[0], upstreamStart: before[1] + 1, upstreamEnd: after[1] };
+}
+function renderBody(data, edits, base, project, upstream) {
+    const baseLabel = upstream ? 'The text boop installed' : 'boop ships now';
+    const out = [
+        `# Edits to ${data.path}`,
+        '',
+        upstream
+            ? `This project's copy differs from the text boop installed in ${edits.length} place${edits.length === 1 ? '' : 's'}. ` +
+                `Each is shown below with boop's own changes to the same text, so you can see where boop has since covered an edit.`
+            : `boop could not find the text it installed, in this project's git history or in the published versions of its package, ` +
+                `so this plan compares the project's copy with what boop ships now. That comparison cannot tell this project's edits ` +
+                `from boop's own changes: every difference below needs a decision, including ones boop made.`,
+        '',
+        `Record a decision for every edit under \`decisions\` in the frontmatter, following the ${update_1.TRIAGE_SKILL} skill: ` +
+            '`keep` with a `rule` and a `kind` (`adds`, `narrows` or `overrides`), `offer` with a `rule`, or `drop` with a `reason`.',
+    ];
+    const upstreamMatches = upstream ? matchLines(base, upstream) : [];
+    edits.forEach((edit, index) => {
+        out.push('', `## ${editId(index)}`, '', locationLine(edit, base, baseLabel));
+        out.push('', `**${baseLabel}:**`, '', ...textBlock(base.slice(edit.baseStart, edit.baseEnd), 'this project added the text below'));
+        out.push('', "**This project's copy:**", '', ...textBlock(project.slice(edit.projectStart, edit.projectEnd), 'this project removed the text above'));
+        if (upstream) {
+            const region = boopRegion(upstreamMatches, upstream.length, base.length, edit.baseStart, edit.baseEnd);
+            const before = base.slice(region.baseStart, region.baseEnd);
+            const after = upstream.slice(region.upstreamStart, region.upstreamEnd);
+            out.push('', '**boop now ships:**', '');
+            if (before.join('\n') === after.join('\n')) {
+                out.push('_boop has not changed this text._');
+            }
+            else {
+                if (region.baseStart !== edit.baseStart || region.baseEnd !== edit.baseEnd) {
+                    out.push(`_boop's change reaches past this edit. This is what boop now ships in place of ${lineRange(region.baseStart, region.baseEnd)} of the installed text:_`, '');
+                }
+                out.push(...textBlock(after, 'boop removed this text'));
+            }
+        }
+    });
+    return out.join('\n') + '\n';
+}
+function locationLine(edit, base, baseLabel) {
+    const label = baseLabel.charAt(0).toLowerCase() + baseLabel.slice(1);
+    const where = edit.baseEnd > edit.baseStart
+        ? `${capitalize(lineRange(edit.baseStart, edit.baseEnd))} of ${label}.`
+        : edit.baseStart === 0 ? `At the start of ${label}.` : `After line ${edit.baseStart} of ${label}.`;
+    const preceding = base.slice(0, edit.baseStart).reverse().find(line => line.trim() !== '');
+    return preceding ? `${where} It follows:\n\n> ${preceding.trim()}` : where;
+}
+/** Lines [start, end), numbered from 1 */
+function lineRange(start, end) {
+    return end - start === 1 ? `line ${start + 1}` : `lines ${start + 1}–${end}`;
+}
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+/** Lines in a code fence longer than any backtick run inside them, or a note when there are none. */
+function textBlock(lines, whenEmpty) {
+    if (lines.every(line => line === '')) {
+        return lines.length === 0 ? [`_(none: ${whenEmpty})_`] : ['_(blank lines only)_'];
+    }
+    const longestRun = Math.max(0, ...lines.flatMap(line => (line.match(/`+/g) ?? []).map(run => run.length)));
+    const fence = '`'.repeat(Math.max(3, longestRun + 1));
+    return [fence, ...lines, fence];
+}

package/dist/lib/stale-scripts.d.ts

@@ -8,8 +8,9 @@
  * Jest never recycles, and a long suite dies as that process's heap grows.
  *
  * `boop update` cannot simply fix those projects. Scripts are merged only when
- * absent (see `merge-scripts` in lib/execute.ts), which is the right default —
- * clobbering a script somebody customised would be worse than leaving it stale.
+ * absent (see lib/script-merge.ts, which both `boop add` and `boop update` use),
+ * which is the right default — clobbering a script somebody customised would be
+ * worse than leaving it stale.
  * So the old command survives the update, and because a CLI `--runInBand` is the
  * first and unconditional branch of Jest's `shouldRunInBand()`, it overrides the
  * new config entirely. That is the state worth warning about: the project now has

package/dist/lib/stale-scripts.js

@@ -9,8 +9,9 @@
  * Jest never recycles, and a long suite dies as that process's heap grows.
  *
  * `boop update` cannot simply fix those projects. Scripts are merged only when
- * absent (see `merge-scripts` in lib/execute.ts), which is the right default —
- * clobbering a script somebody customised would be worse than leaving it stale.
+ * absent (see lib/script-merge.ts, which both `boop add` and `boop update` use),
+ * which is the right default — clobbering a script somebody customised would be
+ * worse than leaving it stale.
  * So the old command survives the update, and because a CLI `--runInBand` is the
  * first and unconditional branch of Jest's `shouldRunInBand()`, it overrides the
  * new config entirely. That is the state worth warning about: the project now has

package/dist/lib/update.d.ts

@@ -5,12 +5,19 @@
  * local modifications, then selectively updates from the capability package.
  */
 import { BoopManifest } from './project';
+import { ScriptUpdateAction } from './script-merge';
 export type FileState = 'match' | 'modified' | 'missing';
+/**
+ * How a locally modified file stands against the base (what boop shipped last)
+ * and upstream (what boop ships now). Only 'both-changed' is a conflict.
+ */
+export type Drift = 'project-only' | 'both-changed' | 'already-upstream';
+export type FileKind = 'skill' | 'reference' | 'code';
 export interface FileUpdateAction {
     /** Relative path from project root */
     relativePath: string;
     /** What will happen to this file */
-    action: 'overwrite' | 'skip' | 'add' | 'deprecate' | 'migrate';
+    action: 'overwrite' | 'skip' | 'add' | 'deprecate' | 'migrate' | 'record-hash';
     /** Why this action was chosen */
     reason: string;
     /** Stored hash from config */
@@ -19,8 +26,23 @@ export interface FileUpdateAction {
     currentHash?: string;
     /** New hash from package */
     newHash?: string;
-    /** For migrate actions: the old file path being replaced */
+    /** For migrate actions, and a folder file held back by an edited old one: the old file path being replaced */
     oldPath?: string;
+    /** For an edited old single-file skill: the skill folder that replaces it */
+    replacedBy?: string;
+    /** For a file whose hash differs from its stored base: how it stands against upstream */
+    drift?: Drift;
+    /** What sort of file this is, from its destination path */
+    fileKind?: FileKind;
+    /** What whoever ran the update should do about this file, when the report lists it */
+    instruction?: string;
+    /** boop's current copy of the file, when the instruction points at it */
+    upstreamPath?: string;
+}
+export interface FileInstruction {
+    relativePath: string;
+    instruction: string;
+    upstreamPath?: string;
 }
 export interface UpdatePlan {
     capability: string;
@@ -32,6 +54,8 @@ export interface UpdatePlan {
     newVersion: string;
     /** Per-file actions */
     actions: FileUpdateAction[];
+    /** What happens to each npm script the capability declares */
+    scriptActions: ScriptUpdateAction[];
     /** Number of files unchanged in both package and locally */
     unchangedCount: number;
     /** True if already up to date */
@@ -50,9 +74,19 @@ export interface UpdateResult {
     pruned: string[];
     /** Files migrated from old flat format to new folder format */
     migrated: string[];
+    /** npm scripts the capability declares that this update wrote into package.json */
+    scriptsAdded: ScriptUpdateAction[];
+    /** npm scripts left as the project has them, because it has its own command */
+    scriptsKept: ScriptUpdateAction[];
     /** Count of files unchanged in both package and locally */
     unchangedCount: number;
+    /** What to do about the files this update skipped or replaced, where the report says anything */
+    instructions: FileInstruction[];
 }
+/** The skill that splits a drifted SKILL.md — keep in step with the folder name boop-rm2l.8 gives it */
+export declare const TRIAGE_SKILL = "boop-skills-edit-triage";
+/** What to do about skills edited in SKILL.md, for a report that counts them */
+export declare const SKILL_EDITS_INSTRUCTION = "Move each skill's edits into the PROJECT.md beside it: run `boop migrate-skill-edits` and follow the boop-skills-edit-triage skill.";
 /**
  * Compare a file's current hash against a stored hash.
  */
@@ -71,6 +105,15 @@ export declare function executeUpdatePlan(plan: UpdatePlan, options?: {
     restore?: boolean;
     prune?: boolean;
 }): UpdateResult;
+/**
+ * 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.
+ */
+export declare function countSkillEdits(targetDir: string, capabilityName: string, projectManifest: BoopManifest): {
+    edited: number;
+    changesWaiting: number;
+} | null;
 /**
  * Format an update result as a human-readable summary line.
  */