@boopkit/cli 0.6.13 → 0.6.14

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

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ */
+import { FindOriginalTextOptions } from './original-text';
+import { BoopManifest } from './project';
+/** Where plans are written, relative to the project. Everything in `.boop/` but config.json is gitignored. */
+export declare const SKILL_EDITS_DIR: string;
+/** One continuous change between a base text and the project's copy, as line ranges. */
+export interface Edit {
+    /** Lines [baseStart, baseEnd) of the base text that the project replaced */
+    baseStart: number;
+    baseEnd: number;
+    /** Lines [projectStart, projectEnd) of the project's copy that replace them */
+    projectStart: number;
+    projectEnd: number;
+}
+/** A blank decision, for the agent following the triage skill to fill in. */
+export interface EditDecision {
+    /** keep | offer | drop */
+    decision: null;
+    /** For a kept edit: adds | narrows | overrides */
+    kind: null;
+    /** For a kept or offered edit: the edit rewritten as a rule that stands alone */
+    rule: null;
+    /** For a dropped edit: why */
+    reason: null;
+}
+export interface SkillEditPlanData {
+    skill: string;
+    capability: string;
+    path: string;
+    original: {
+        source: 'none';
+    } | ({
+        source: 'git';
+        commit: string;
+    }) | ({
+        source: 'npm';
+        package: string;
+        version: string;
+    });
+    /** True when the original could not be found, so every difference from boop's copy needs a decision */
+    comparedWithoutOriginal: boolean;
+    /** Whether boop has changed the skill since the project installed it; unknown without the original */
+    boopChanged: boolean | null;
+    /** As they were when the plan was written, so applying it can refuse a plan made for other text */
+    hashes: {
+        installed: string;
+        project: string;
+        boop: string;
+    };
+    decisions: Record<string, EditDecision>;
+}
+export type SkillEditOutcome = {
+    kind: 'written';
+    skill: string;
+    planPath: string;
+    edits: number;
+    boopChanged: boolean | null;
+    comparedWithoutOriginal: boolean;
+    replacedStale: boolean;
+} | {
+    kind: 'kept';
+    skill: string;
+    planPath: string;
+} | {
+    kind: 'hand-split';
+    skill: string;
+    relativePath: string;
+    upstreamPath?: string;
+};
+/**
+ * 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.
+ */
+export declare function writeSkillEditPlans(projectDir: string, manifest: BoopManifest, options?: FindOriginalTextOptions): SkillEditOutcome[];
+/**
+ * The edits that turn `base` into `project`: each maximal run of lines that
+ * are not part of a longest common subsequence of the two.
+ */
+export declare function diffLines(base: string[], project: string[]): Edit[];

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/update.d.ts

@@ -6,11 +6,17 @@
  */
 import { BoopManifest } from './project';
 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 +25,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;
@@ -52,7 +73,13 @@ export interface UpdateResult {
     migrated: string[];
     /** 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 +98,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.
  */