@boopkit/cli 0.6.13 → 0.6.15

package/dist/lib/scaffold.js

@@ -41,8 +41,13 @@ exports.getTemplatesDir = getTemplatesDir;
 exports.profileHasTemplates = profileHasTemplates;
 exports.scaffoldKernel = scaffoldKernel;
 exports.hashFile = hashFile;
+exports.hashContent = hashContent;
 exports.copyCapabilityFiles = copyCapabilityFiles;
 exports.linkSkillsToClaude = linkSkillsToClaude;
+exports.installedSkillNames = installedSkillNames;
+exports.createSkillProjectFiles = createSkillProjectFiles;
+exports.hasOfferedRules = hasOfferedRules;
+exports.readSkillProjectTemplate = readSkillProjectTemplate;
 exports.getBoopkitVersion = getBoopkitVersion;
 exports.formatUnpinnedDependencyWarning = formatUnpinnedDependencyWarning;
 exports.mergePackageJson = mergePackageJson;
@@ -56,6 +61,7 @@ const config_1 = require("./config");
 const capability_1 = require("./capability");
 const safe_io_1 = require("./safe-io");
 const install_layout_1 = require("./install-layout");
+const project_1 = require("./project");
 /**
  * Render a single Handlebars template string with variables.
  *
@@ -135,7 +141,13 @@ function scaffoldKernel(targetDir, variables, overwrite = false, templatesDir =
  * Compute SHA-256 hash of a file's content.
  */
 function hashFile(filePath) {
-    const content = fs.readFileSync(filePath);
+    return hashContent(fs.readFileSync(filePath));
+}
+/**
+ * The hash `hashFile` records, for content that is not on disk — a past version
+ * read from git, or a file inside a downloaded package.
+ */
+function hashContent(content) {
     const hash = crypto.createHash('sha256').update(content).digest('hex');
     return `sha256:${hash}`;
 }
@@ -243,6 +255,127 @@ function linkSkillsToClaude(targetDir, only) {
     }
     return linked;
 }
+/**
+ * The names of the skill folders under `<targetDir>/skills/` that boop installed.
+ *
+ * A project's `skills/` is not all boop's: a project writes skills of its own
+ * beside the ones its capabilities ship, and those folders are already entirely
+ * the project's file. Two records say which are boop's, and the union is taken
+ * because neither is complete on its own:
+ *
+ * - the `fileHashes` a capability stored in `.boop/config.json`, which is the
+ *   record of what was actually copied into this project;
+ * - the skill placements of an installed capability that has no stored hashes —
+ *   a manifest written before `capabilityMeta` existed, or one whose hash
+ *   storage was skipped.
+ *
+ * Returns null when the directory holds no `.boop/config.json`, i.e. nothing
+ * here is a boop project and no folder can be attributed either way.
+ */
+function installedSkillNames(targetDir, searchPaths) {
+    const manifest = (0, project_1.readProjectManifest)(targetDir);
+    if (!manifest)
+        return null;
+    const names = new Set();
+    const addDest = (dest) => {
+        // Stored destinations are POSIX, but tolerate a manifest written on Windows.
+        const [top, skillName] = dest.split(/[\\/]/);
+        if (top === 'skills' && skillName)
+            names.add(skillName);
+    };
+    const meta = manifest.capabilityMeta ?? {};
+    for (const entry of Object.values(meta)) {
+        for (const dest of Object.keys(entry?.fileHashes ?? {}))
+            addDest(dest);
+    }
+    // Walking a package's files is the expensive half, so it runs only for a
+    // capability whose hashes are missing — where it is the only record left.
+    for (const capability of manifest.capabilities ?? []) {
+        if (Object.keys(meta[capability]?.fileHashes ?? {}).length > 0)
+            continue;
+        for (const placement of (0, install_layout_1.capabilityPlacements)(capability, searchPaths ?? [targetDir])) {
+            if (placement.kind === 'skill')
+                addDest(placement.dest);
+        }
+    }
+    return names;
+}
+/**
+ * Give every boop-installed skill folder under `<targetDir>/skills/` that lacks
+ * one a `PROJECT.md`, where the project records how it applies the skill. Each
+ * boop `SKILL.md` opens by pointing at it; the file being present is the
+ * backstop for an agent that skipped the pointer.
+ *
+ * Only a folder boop installed gets one. A skill the project wrote itself is
+ * already the project's file outright, so a `PROJECT.md` beside it separates
+ * nothing — and because this runs on every init, add and update, a project
+ * could never delete the stub it left there.
+ *
+ * For the same reason it takes back a stub an earlier boop wrote beside a
+ * project-owned skill, but only while the file's bytes are still exactly the
+ * template's: anything the project typed into a `PROJECT.md` keeps it.
+ *
+ * The file is the project's: boop never hashes it, so `boop update` can never
+ * report it, and an existing one is never opened for writing.
+ *
+ * Returns the relative paths of the files created and of the stubs removed.
+ */
+function createSkillProjectFiles(targetDir, searchPaths) {
+    const skillsDir = path.join(targetDir, 'skills');
+    if (!fs.existsSync(skillsDir))
+        return { created: [], removed: [] };
+    const installed = installedSkillNames(targetDir, searchPaths);
+    if (installed === null)
+        return { created: [], removed: [] };
+    const template = readSkillProjectTemplate();
+    const created = [];
+    const removed = [];
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        // A symlinked skill folder is someone else's. In the boop repository each one
+        // points into a capability package, from which a PROJECT.md would ship to every project.
+        if (!entry.isDirectory())
+            continue;
+        const filePath = path.join(skillsDir, entry.name, 'PROJECT.md');
+        const relPath = path.join('skills', entry.name, 'PROJECT.md');
+        const existing = fs.lstatSync(filePath, { throwIfNoEntry: false });
+        if (!installed.has(entry.name)) {
+            if (existing?.isFile() && fs.readFileSync(filePath, 'utf-8') === template) {
+                fs.unlinkSync(filePath);
+                removed.push(relPath);
+            }
+            continue;
+        }
+        if (existing)
+            continue;
+        fs.writeFileSync(filePath, template, { flag: 'wx' });
+        created.push(relPath);
+    }
+    return { created, removed };
+}
+/**
+ * Whether a skill's PROJECT.md has rules under "Offered to boop" — anything in
+ * that section beyond the template's own explanation of it.
+ */
+function hasOfferedRules(projectFilePath) {
+    if (!fs.existsSync(projectFilePath))
+        return false;
+    const section = offeredToBoopSection(fs.readFileSync(projectFilePath, 'utf-8'));
+    if (section === null)
+        return false;
+    const explanation = new Set((offeredToBoopSection(readSkillProjectTemplate()) ?? '').split('\n').map(line => line.trim()));
+    return section.split('\n').some(line => line.trim() !== '' && !explanation.has(line.trim()));
+}
+function offeredToBoopSection(text) {
+    const heading = /^##[ \t]+Offered to boop[ \t]*$/m.exec(text);
+    if (!heading)
+        return null;
+    const rest = text.slice(heading.index + heading[0].length);
+    const nextHeading = rest.search(/^#{1,2}[ \t]/m);
+    return nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+}
+function readSkillProjectTemplate() {
+    return fs.readFileSync(path.join((0, config_1.getBoopRoot)(), 'src', 'templates', 'skill-project', 'PROJECT.md'), 'utf-8');
+}
 /**
  * Copy capability files from the capabilities/ source tree (test fixtures only).
  */

package/dist/lib/script-merge.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Merge the npm scripts a capability declares into a project's package.json
+ * during `boop update`.
+ *
+ * The case this exists for (boop-ldou): a capability ships a new command as two
+ * things — a file under `scaffold/`, and a `scripts` entry in `capability.json`.
+ * `boop add` merges those scripts at install time (see `merge-scripts` in
+ * lib/execute.ts), but `boop update` only ever copied files, so an upgraded
+ * project received `src/scripts/migrate-credentials.ts` and no way to run it by
+ * name. Every document, post-install note and status hint that said
+ * `npm run credentials:migrate` was right for a freshly scaffolded project and
+ * wrong for every upgraded one — precisely the projects a migration tool is for.
+ *
+ * The merge is additive, like `boop add`'s: a script is written only when the
+ * project has no script of that name. A name the project already uses is left
+ * exactly as it stands, because a command somebody customised is theirs, and
+ * clobbering it would be worse than leaving it alone — the same restraint
+ * `rewriteStaleRunnerScripts` shows when a command has changed underneath it.
+ * What boop does do is say so, so a kept command that no longer matches what the
+ * capability ships is visible rather than silent.
+ */
+import { CapabilityScript } from './config';
+export interface ScriptUpdateAction {
+    /** The script's key in package.json, e.g. `credentials:migrate`. */
+    name: string;
+    /** The command the capability declares. */
+    command: string;
+    /** `add` writes it; `keep` leaves the project's own command in place. */
+    action: 'add' | 'keep';
+    /** Why this action was chosen. */
+    reason: string;
+    /** The command the project has today, when there is one. */
+    currentCommand?: string;
+}
+/**
+ * Pure: given what a capability declares and what the project's package.json
+ * holds, decide what happens to each script.
+ *
+ * A script whose command already matches what the capability ships is not
+ * returned at all — there is nothing to do and nothing worth reporting.
+ */
+export declare function planScriptUpdates(declared: Record<string, CapabilityScript> | undefined, projectScripts: Record<string, string> | undefined): ScriptUpdateAction[];
+/**
+ * Write the `add` actions into the project's package.json, and return the ones
+ * actually written.
+ *
+ * Re-reads the file rather than trusting the plan: an action is applied only
+ * while the name is still free, so a script written between planning and here
+ * survives. A missing or unreadable package.json is not an error — scaffold
+ * files have already been delivered by the time this runs, and failing the whole
+ * update over the script merge would be worse than reporting nothing.
+ */
+export declare function applyScriptUpdates(targetDir: string, actions: ScriptUpdateAction[]): ScriptUpdateAction[];
+/** The project's package.json scripts, or undefined when there is no readable one. */
+export declare function readProjectScripts(targetDir: string): Record<string, string> | undefined;

package/dist/lib/script-merge.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Merge the npm scripts a capability declares into a project's package.json
+ * during `boop update`.
+ *
+ * The case this exists for (boop-ldou): a capability ships a new command as two
+ * things — a file under `scaffold/`, and a `scripts` entry in `capability.json`.
+ * `boop add` merges those scripts at install time (see `merge-scripts` in
+ * lib/execute.ts), but `boop update` only ever copied files, so an upgraded
+ * project received `src/scripts/migrate-credentials.ts` and no way to run it by
+ * name. Every document, post-install note and status hint that said
+ * `npm run credentials:migrate` was right for a freshly scaffolded project and
+ * wrong for every upgraded one — precisely the projects a migration tool is for.
+ *
+ * The merge is additive, like `boop add`'s: a script is written only when the
+ * project has no script of that name. A name the project already uses is left
+ * exactly as it stands, because a command somebody customised is theirs, and
+ * clobbering it would be worse than leaving it alone — the same restraint
+ * `rewriteStaleRunnerScripts` shows when a command has changed underneath it.
+ * What boop does do is say so, so a kept command that no longer matches what the
+ * capability ships is visible rather than silent.
+ */
+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.planScriptUpdates = planScriptUpdates;
+exports.applyScriptUpdates = applyScriptUpdates;
+exports.readProjectScripts = readProjectScripts;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Pure: given what a capability declares and what the project's package.json
+ * holds, decide what happens to each script.
+ *
+ * A script whose command already matches what the capability ships is not
+ * returned at all — there is nothing to do and nothing worth reporting.
+ */
+function planScriptUpdates(declared, projectScripts) {
+    if (!declared)
+        return [];
+    const actions = [];
+    for (const [name, script] of Object.entries(declared)) {
+        const command = typeof script === 'string' ? script : script?.cmd;
+        if (!command)
+            continue;
+        const currentCommand = projectScripts?.[name];
+        if (currentCommand === undefined) {
+            actions.push({ name, command, action: 'add', reason: 'New script from capability' });
+            continue;
+        }
+        if (currentCommand === command)
+            continue;
+        actions.push({
+            name,
+            command,
+            action: 'keep',
+            reason: 'Project has its own command for this script',
+            currentCommand,
+        });
+    }
+    return actions;
+}
+/**
+ * Write the `add` actions into the project's package.json, and return the ones
+ * actually written.
+ *
+ * Re-reads the file rather than trusting the plan: an action is applied only
+ * while the name is still free, so a script written between planning and here
+ * survives. A missing or unreadable package.json is not an error — scaffold
+ * files have already been delivered by the time this runs, and failing the whole
+ * update over the script merge would be worse than reporting nothing.
+ */
+function applyScriptUpdates(targetDir, actions) {
+    const additions = actions.filter(a => a.action === 'add');
+    if (additions.length === 0)
+        return [];
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return [];
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+    if (!pkg.scripts)
+        pkg.scripts = {};
+    const applied = [];
+    for (const action of additions) {
+        if (action.name in pkg.scripts)
+            continue;
+        pkg.scripts[action.name] = action.command;
+        applied.push(action);
+    }
+    if (applied.length > 0) {
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+    }
+    return applied;
+}
+/** The project's package.json scripts, or undefined when there is no readable one. */
+function readProjectScripts(targetDir) {
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return undefined;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return pkg.scripts;
+    }
+    catch {
+        return undefined;
+    }
+}

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[];