@boopkit/cli 0.6.13 → 0.6.15

package/dist/lib/apply-skill-edits.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * 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.
+ */
+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.RULE_HEADINGS = exports.POINTER_BLOCK = void 0;
+exports.applySkillEditPlans = applySkillEditPlans;
+exports.opensWithPointer = opensWithPointer;
+exports.addRule = addRule;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const capability_1 = require("./capability");
+const install_layout_1 = require("./install-layout");
+const project_1 = require("./project");
+const scaffold_1 = require("./scaffold");
+const skill_edits_1 = require("./skill-edits");
+const update_1 = require("./update");
+/**
+ * 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.
+ */
+exports.POINTER_BLOCK = [
+    '> **Read `PROJECT.md`, beside this file, first.**',
+    '> It records how this project applies the guidance below, and where it deliberately differs.',
+    '> Where the two conflict, `PROJECT.md` wins.',
+    '> Record project-specific rules there, never in this file.',
+].join('\n');
+/** The PROJECT.md heading each kind of rule goes under */
+exports.RULE_HEADINGS = {
+    adds: 'Adds',
+    narrows: 'Narrows',
+    overrides: 'Overrides',
+    offer: 'Offered to boop',
+};
+/**
+ * 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.
+ */
+async function applySkillEditPlans(projectDir, manifest, deps) {
+    const outcomes = [];
+    for (const planPath of listPlans(projectDir)) {
+        const checked = checkPlan(projectDir, manifest, planPath);
+        if ('reasons' in checked) {
+            outcomes.push({ kind: 'refused', planPath, reasons: checked.reasons });
+            continue;
+        }
+        if (checked.drops.length > 0) {
+            if (!deps.interactive) {
+                outcomes.push({ kind: 'needs-person', planPath, drops: checked.drops });
+                continue;
+            }
+            const declined = [];
+            for (const drop of checked.drops) {
+                const yes = await deps.confirm(`Drop ${drop.edit} from ${checked.skillPath}? The reason given: ${drop.reason}`);
+                if (!yes)
+                    declined.push(drop);
+            }
+            if (declined.length > 0) {
+                outcomes.push({ kind: 'declined', planPath, declined });
+                continue;
+            }
+        }
+        outcomes.push(applyPlan(projectDir, manifest, checked));
+        // Written per plan, so a later prompt that is interrupted cannot leave a restored skill without its hash
+        (0, project_1.writeProjectManifest)(projectDir, manifest);
+    }
+    const recordedHashes = recordMatchingSkillHashes(projectDir, manifest);
+    if (recordedHashes.length > 0) {
+        (0, project_1.writeProjectManifest)(projectDir, manifest);
+    }
+    return { outcomes, recordedHashes };
+}
+function listPlans(projectDir) {
+    const dir = path.join(projectDir, skill_edits_1.SKILL_EDITS_DIR);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .filter(name => name.endsWith('.md'))
+        .sort()
+        .map(name => path.join(skill_edits_1.SKILL_EDITS_DIR, name));
+}
+function checkPlan(projectDir, manifest, planPath) {
+    const rewrite = 'Run `boop migrate-skill-edits` to write a new plan for the current text, and decide it again.';
+    let plan;
+    try {
+        // An empty options object keeps gray-matter from answering from its cache
+        plan = (0, gray_matter_1.default)(fs.readFileSync(path.join(projectDir, planPath), 'utf-8'), {});
+    }
+    catch (err) {
+        return { reasons: [`Its frontmatter does not parse: ${err.message.split('\n')[0]}. Fix the YAML and run again.`] };
+    }
+    const data = plan.data;
+    const skillPath = typeof data.path === 'string' ? data.path : '';
+    if (!/^skills\/[^/]+\/SKILL\.md$/.test(skillPath) || typeof data.capability !== 'string'
+        || typeof data.hashes?.project !== 'string' || typeof data.hashes?.boop !== 'string'
+        || typeof data.decisions !== 'object' || data.decisions === null) {
+        return { reasons: [`Its frontmatter is missing the path, capability, hashes or decisions the command wrote. ${rewrite}`] };
+    }
+    const reasons = [];
+    const rules = [];
+    const drops = [];
+    const editIds = editHeadings(plan.content);
+    const decisions = data.decisions;
+    for (const id of editIds) {
+        const entry = decisions[id];
+        const decision = entry?.decision;
+        const rule = nonBlank(entry?.rule);
+        const reason = nonBlank(entry?.reason);
+        if (decision === null || decision === undefined) {
+            reasons.push(`${id} has no decision. Record keep, offer or drop, following the triage skill.`);
+        }
+        else if (decision === 'keep') {
+            if (!rule)
+                reasons.push(`${id} is kept but has no rule. Write the edit as a rule that stands on its own.`);
+            if (!isKeepKind(entry.kind))
+                reasons.push(`${id} is kept but its kind is not adds, narrows or overrides.`);
+            if (rule && isKeepKind(entry.kind))
+                rules.push({ edit: id, heading: exports.RULE_HEADINGS[entry.kind], rule, ...(reason && { reason }) });
+        }
+        else if (decision === 'offer') {
+            if (rule)
+                rules.push({ edit: id, heading: exports.RULE_HEADINGS.offer, rule, ...(reason && { reason }) });
+            else
+                reasons.push(`${id} is offered to boop but has no rule. Write the edit as a rule for any project.`);
+        }
+        else if (decision === 'drop') {
+            if (reason)
+                drops.push({ edit: id, reason });
+            else
+                reasons.push(`${id} is dropped but has no reason. Say why, in one sentence, for the person who confirms it.`);
+        }
+        else {
+            reasons.push(`${id} has the decision "${String(decision)}", which is not keep, offer or drop.`);
+        }
+    }
+    for (const id of Object.keys(decisions)) {
+        if (!editIds.includes(id))
+            reasons.push(`${id} is not an edit in this plan. Remove it from decisions.`);
+    }
+    const skillFile = path.join(projectDir, skillPath);
+    if (!fs.existsSync(skillFile)) {
+        reasons.push(`${skillPath} no longer exists. ${rewrite}`);
+    }
+    else if ((0, scaffold_1.hashContent)(fs.readFileSync(skillFile)) !== data.hashes.project) {
+        reasons.push(`${skillPath} has changed since this plan was written, so its decisions were made about other text. ${rewrite}`);
+    }
+    const boopCopyPath = manifest.capabilities.includes(data.capability) ? findBoopCopy(projectDir, data.capability, skillPath) : null;
+    if (!boopCopyPath) {
+        reasons.push(`boop has no copy of ${skillPath} in the ${data.capability} capability to restore. ${rewrite}`);
+        return { reasons };
+    }
+    const boopText = fs.readFileSync(boopCopyPath);
+    const boopHash = (0, scaffold_1.hashContent)(boopText);
+    if (boopHash !== data.hashes.boop) {
+        reasons.push(`boop's copy of ${skillPath} has changed since this plan was written, probably in a boop update. ${rewrite}`);
+    }
+    if (!opensWithPointer(boopText.toString('utf-8'))) {
+        reasons.push(`boop's copy of ${skillPath} does not open with the block that sends an agent to PROJECT.md, ` +
+            "so restoring it would leave this project's rules unread. Run `boop update` to get a release whose skills carry the block, then write the plan again.");
+    }
+    if (reasons.length > 0)
+        return { reasons };
+    return { planPath, capability: data.capability, skillPath, boopCopyPath, boopHash, rules, drops };
+}
+function applyPlan(projectDir, manifest, plan) {
+    const projectFile = path.join(path.dirname(plan.skillPath), 'PROJECT.md');
+    const projectFilePath = path.join(projectDir, projectFile);
+    let rules = fs.existsSync(projectFilePath) ? fs.readFileSync(projectFilePath, 'utf-8') : (0, scaffold_1.readSkillProjectTemplate)();
+    for (const rule of plan.rules)
+        rules = addRule(rules, rule.heading, rule.rule);
+    fs.writeFileSync(projectFilePath, rules);
+    // The edited copy is kept under .boop/, which a scaffolded project never commits; beside SKILL.md, `git add -A` would ship it
+    const skillFile = path.join(projectDir, plan.skillPath);
+    const backupPath = path.join(skill_edits_1.SKILL_EDITS_DIR, 'backups', path.basename(path.dirname(plan.skillPath)), 'SKILL.md');
+    fs.mkdirSync(path.join(projectDir, path.dirname(backupPath)), { recursive: true });
+    fs.copyFileSync(skillFile, path.join(projectDir, backupPath));
+    fs.copyFileSync(plan.boopCopyPath, skillFile);
+    // Recorded here, not left to the next update: a release in between would make the restored copy read as a conflict
+    const meta = manifest.capabilityMeta?.[plan.capability];
+    if (meta)
+        meta.fileHashes[plan.skillPath] = plan.boopHash;
+    fs.unlinkSync(path.join(projectDir, plan.planPath));
+    return {
+        kind: 'applied',
+        planPath: plan.planPath,
+        skillPath: plan.skillPath,
+        projectFile,
+        backupPath,
+        rules: plan.rules,
+        drops: plan.drops,
+    };
+}
+/** Move the stored hash forward for every skill that already holds what boop ships. */
+function recordMatchingSkillHashes(projectDir, manifest) {
+    const recorded = [];
+    for (const capability of manifest.capabilities) {
+        const meta = manifest.capabilityMeta?.[capability];
+        const plan = (0, update_1.planCapabilityUpdate)(projectDir, capability, manifest);
+        for (const action of plan?.actions ?? []) {
+            if (action.action !== 'record-hash' || action.fileKind !== 'skill' || !meta)
+                continue;
+            meta.fileHashes[action.relativePath] = action.newHash;
+            recorded.push(action.relativePath);
+        }
+    }
+    return recorded;
+}
+function findBoopCopy(projectDir, capability, skillPath) {
+    const packageDir = (0, capability_1.getPackageDir)(capability, [projectDir]);
+    if (!packageDir)
+        return null;
+    return (0, install_layout_1.capabilityPlacementsFromDir)(packageDir).find(p => p.dest.split(path.sep).join('/') === skillPath)?.source ?? null;
+}
+/** Whether a SKILL.md's body, below its frontmatter, opens with the pointer block. */
+function opensWithPointer(markdown) {
+    const body = markdown.replace(/\r\n/g, '\n').replace(/^---\n[\s\S]*?\n---[ \t]*(?:\n|$)/, '').replace(/^\s*\n/, '');
+    return body === exports.POINTER_BLOCK || body.startsWith(`${exports.POINTER_BLOCK}\n`);
+}
+/**
+ * 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.
+ */
+function addRule(text, heading, rule) {
+    const lines = text.split('\n');
+    const headings = markdownHeadings(lines);
+    const at = headings.findIndex(h => h.level === 2 && h.text === heading);
+    if (at === -1) {
+        return `${text.replace(/\s*$/, '')}\n\n## ${heading}\n\n${rule}\n`;
+    }
+    const next = headings.slice(at + 1).find(h => h.level <= 2);
+    const before = lines.slice(0, next ? next.index : lines.length).join('\n').replace(/\s*$/, '');
+    const after = next ? lines.slice(next.index).join('\n') : '';
+    return after ? `${before}\n\n${rule}\n\n${after}` : `${before}\n\n${rule}\n`;
+}
+/** The edit ids a plan's body heads a section with. */
+function editHeadings(body) {
+    return markdownHeadings(body.split('\n'))
+        .filter(h => h.level === 2 && /^edit-\d+$/.test(h.text))
+        .map(h => h.text);
+}
+/** ATX headings outside fenced code, where a `#` line is a comment rather than a heading. */
+function markdownHeadings(lines) {
+    const headings = [];
+    let fence = null;
+    lines.forEach((line, index) => {
+        const fenceMatch = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (fence) {
+            if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length && line.trim() === fenceMatch[1])
+                fence = null;
+            return;
+        }
+        if (fenceMatch) {
+            fence = fenceMatch[1];
+            return;
+        }
+        const heading = /^(#{1,6})[ \t]+(.*?)[ \t#]*$/.exec(line);
+        if (heading)
+            headings.push({ index, level: heading[1].length, text: heading[2] });
+    });
+    return headings;
+}
+function isKeepKind(kind) {
+    return kind === 'adds' || kind === 'narrows' || kind === 'overrides';
+}
+function nonBlank(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+}

package/dist/lib/execute.js

@@ -50,6 +50,7 @@ const project_1 = require("./project");
 const env_1 = require("./env");
 const rewire_1 = require("./rewire");
 const safe_io_1 = require("./safe-io");
+const script_merge_1 = require("./script-merge");
 /**
  * Execute all tasks in a manifest. Returns the result with per-task status.
  */
@@ -101,6 +102,7 @@ function executeTask(task, manifest) {
         case 'copy-files': {
             (0, scaffold_1.copyCapabilityFiles)(targetDir, capabilityName);
             (0, scaffold_1.linkSkillsToClaude)(targetDir);
+            (0, scaffold_1.createSkillProjectFiles)(targetDir);
             break;
         }
         case 'merge-deps': {
@@ -109,19 +111,9 @@ function executeTask(task, manifest) {
             break;
         }
         case 'merge-scripts': {
+            // One answer to "does this script go in", shared with `boop update`
             const data = task.data;
-            const pkgPath = path.join(targetDir, 'package.json');
-            if (fs.existsSync(pkgPath)) {
-                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-                if (!pkg.scripts)
-                    pkg.scripts = {};
-                for (const [scriptName, scriptDef] of Object.entries(data.scripts)) {
-                    if (!(scriptName in pkg.scripts)) {
-                        pkg.scripts[scriptName] = scriptDef.cmd;
-                    }
-                }
-                fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
-            }
+            (0, script_merge_1.applyScriptUpdates)(targetDir, (0, script_merge_1.planScriptUpdates)(data.scripts, (0, script_merge_1.readProjectScripts)(targetDir)));
             break;
         }
         case 'link-package': {

package/dist/lib/original-text.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Recover the exact text boop installed for a tracked file.
+ *
+ * `.boop/config.json` keeps a hash per installed file but not the text, and the
+ * capability version it records cannot stand in for it: when `boop update`
+ * skips an edited file it keeps that file's old hash but records the new
+ * version, so after one skipped update the two describe different releases.
+ * The hash names the original exactly, whichever release it came from, so the
+ * lookup searches for content with that hash — first in the project's own git
+ * history of the file, then in the capability's published versions on npm.
+ */
+export type OriginalTextSource = {
+    kind: 'git';
+    commit: string;
+} | {
+    kind: 'npm';
+    package: string;
+    version: string;
+};
+export type OriginalText = {
+    found: true;
+    content: string;
+    source: OriginalTextSource;
+} | {
+    found: false;
+};
+/** Where published capability packages come from. The default is the npm CLI, so the user's registry and auth apply. */
+export interface PackageRegistry {
+    /** Every published version, oldest first. */
+    listVersions(packageName: string): string[];
+    /** Unpack one version into `workDir` and return the package directory. */
+    unpack(packageName: string, version: string, workDir: string): string;
+}
+export interface FindOriginalTextOptions {
+    registry?: PackageRegistry;
+}
+/**
+ * Find the content whose hash is `storedHash` for the file at `relPath`
+ * (POSIX, relative to `projectDir`). Never throws: a failure in either source
+ * is a miss for that source, and a miss in both is `{ found: false }`.
+ */
+export declare function findOriginalText(projectDir: string, relPath: string, storedHash: string, options?: FindOriginalTextOptions): OriginalText;
+export declare const npmRegistry: PackageRegistry;

package/dist/lib/original-text.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * Recover the exact text boop installed for a tracked file.
+ *
+ * `.boop/config.json` keeps a hash per installed file but not the text, and the
+ * capability version it records cannot stand in for it: when `boop update`
+ * skips an edited file it keeps that file's old hash but records the new
+ * version, so after one skipped update the two describe different releases.
+ * The hash names the original exactly, whichever release it came from, so the
+ * lookup searches for content with that hash — first in the project's own git
+ * history of the file, then in the capability's published versions on npm.
+ */
+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.npmRegistry = void 0;
+exports.findOriginalText = findOriginalText;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const capability_1 = require("./capability");
+const install_layout_1 = require("./install-layout");
+const project_1 = require("./project");
+const scaffold_1 = require("./scaffold");
+/**
+ * Find the content whose hash is `storedHash` for the file at `relPath`
+ * (POSIX, relative to `projectDir`). Never throws: a failure in either source
+ * is a miss for that source, and a miss in both is `{ found: false }`.
+ */
+function findOriginalText(projectDir, relPath, storedHash, options = {}) {
+    return (findInGitHistory(projectDir, relPath, storedHash) ??
+        findInPublishedVersions(projectDir, relPath, storedHash, options.registry ?? exports.npmRegistry));
+}
+function findInGitHistory(projectDir, relPath, storedHash) {
+    let commits;
+    try {
+        commits = git(projectDir, 'rev-list', 'HEAD', '--', relPath).toString('utf-8').split('\n').filter(Boolean);
+    }
+    catch {
+        return null;
+    }
+    for (const commit of commits) {
+        let content;
+        try {
+            // `./` makes the path relative to projectDir, which may sit below the repository root.
+            content = git(projectDir, 'show', `${commit}:./${relPath}`);
+        }
+        catch {
+            continue; // the commit that deleted the file
+        }
+        if ((0, scaffold_1.hashContent)(content) === storedHash) {
+            return { found: true, content: content.toString('utf-8'), source: { kind: 'git', commit } };
+        }
+    }
+    return null;
+}
+function git(cwd, ...args) {
+    return (0, child_process_1.execFileSync)('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
+}
+function findInPublishedVersions(projectDir, relPath, storedHash, registry) {
+    const capability = owningCapability(projectDir, relPath);
+    if (!capability)
+        return { found: false };
+    const packageName = packageNameFor(capability, projectDir);
+    const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'boop-original-text-'));
+    try {
+        for (const version of registry.listVersions(packageName).slice().reverse()) {
+            const pkgDir = registry.unpack(packageName, version, path.join(workDir, version));
+            const placement = (0, install_layout_1.capabilityPlacementsFromDir)(pkgDir).find(p => p.dest === relPath);
+            if (!placement)
+                continue;
+            const content = fs.readFileSync(placement.source);
+            if ((0, scaffold_1.hashContent)(content) === storedHash) {
+                return { found: true, content: content.toString('utf-8'), source: { kind: 'npm', package: packageName, version } };
+            }
+        }
+    }
+    catch {
+        // An unreachable registry or a broken tarball is a miss, not a failure: the caller has a fallback.
+    }
+    finally {
+        fs.rmSync(workDir, { recursive: true, force: true });
+    }
+    return { found: false };
+}
+function owningCapability(projectDir, relPath) {
+    let manifest;
+    try {
+        manifest = (0, project_1.readProjectManifest)(projectDir);
+    }
+    catch {
+        return null;
+    }
+    const entry = Object.entries(manifest?.capabilityMeta ?? {}).find(([, meta]) => relPath in (meta.fileHashes ?? {}));
+    return entry ? entry[0] : null;
+}
+function packageNameFor(capability, projectDir) {
+    // The installed package knows its own name; `users-and-accounts` ships as @boopkit/cap-users.
+    const pkgDir = (0, capability_1.getPackageDir)(capability, [projectDir]);
+    if (pkgDir) {
+        try {
+            const { name } = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8'));
+            if (typeof name === 'string')
+                return name;
+        }
+        catch {
+            // fall through to the conventional name
+        }
+    }
+    return `@boopkit/cap-${capability}`;
+}
+exports.npmRegistry = {
+    listVersions(packageName) {
+        const out = (0, child_process_1.execFileSync)('npm', ['view', packageName, 'versions', '--json'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        // npm prints a bare string, not an array, for a package with one version.
+        const versions = JSON.parse(out);
+        return Array.isArray(versions) ? versions : [versions];
+    },
+    unpack(packageName, version, workDir) {
+        fs.mkdirSync(workDir, { recursive: true });
+        const out = (0, child_process_1.execFileSync)('npm', ['pack', `${packageName}@${version}`, '--pack-destination', workDir, '--json'], {
+            cwd: workDir,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const [{ filename }] = JSON.parse(out);
+        (0, child_process_1.execFileSync)('tar', ['-xzf', path.join(workDir, filename), '-C', workDir], { stdio: 'ignore' });
+        return path.join(workDir, 'package');
+    },
+};

package/dist/lib/scaffold.d.ts

@@ -41,6 +41,11 @@ export declare function scaffoldKernel(targetDir: string, variables: TemplateVar
  * Compute SHA-256 hash of a file's content.
  */
 export declare function hashFile(filePath: string): string;
+/**
+ * The hash `hashFile` records, for content that is not on disk — a past version
+ * read from git, or a file inside a downloaded package.
+ */
+export declare function hashContent(content: Buffer): string;
 /**
  * Copy capability-specific files into a target project directory.
  * Tries package resolution first (scaffold/ and skills/ dirs), falls back to source tree.
@@ -64,6 +69,54 @@ export declare function copyCapabilityFiles(targetDir: string, capabilityName: s
  * Idempotent. Returns the relative paths of symlinks created or already present.
  */
 export declare function linkSkillsToClaude(targetDir: string, only?: Iterable<string>): string[];
+/**
+ * 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.
+ */
+export declare function installedSkillNames(targetDir: string, searchPaths?: string[]): Set<string> | null;
+/**
+ * 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.
+ */
+export declare function createSkillProjectFiles(targetDir: string, searchPaths?: string[]): {
+    created: string[];
+    removed: string[];
+};
+/**
+ * Whether a skill's PROJECT.md has rules under "Offered to boop" — anything in
+ * that section beyond the template's own explanation of it.
+ */
+export declare function hasOfferedRules(projectFilePath: string): boolean;
+export declare function readSkillProjectTemplate(): string;
 /**
  * Merge dependencies into an existing package.json.
  * Does not overwrite existing dependency versions.