@boopkit/cli 0.8.0 → 0.8.2

package/dist/lib/moves.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The move pass of `boop update`: files a capability stopped shipping because
+ * another capability ships them now (specs/skill-moves.spec.md).
+ *
+ * The capability the files leave declares where they went, in `file_moves`, and
+ * names any capability split out of it in `split_into`. The pass reads those
+ * declarations from every installed capability, settles each moved path the
+ * project holds a stored hash for, and runs before any capability is planned:
+ * a move is a rename on disk plus a transfer of stored hashes, and everything
+ * after that is the receiving capability's ordinary update.
+ */
+import { BoopManifest } from './project';
+import { FileInstruction, FileUpdateAction } from './update';
+export interface FileMoveDeclaration {
+    capability: string;
+    /** Where the files land; the key when absent */
+    path?: string;
+}
+export type MoveState = 'will-move' | 'waiting-for-capability' | 'waiting-for-package' | 'kept-for-project-content' | 'split-will-add';
+/**
+ * What the pass decided for one declared key the project holds paths under.
+ *
+ * - `move`: rename on disk and transfer the hashes (cases 1 to 4 and 10).
+ * - `remove`: delete the old skill folder, which holds nothing of the project's (cases 5 and 7).
+ * - `merge`: the receiving capability already installed the new folder; delete the old one,
+ *   carrying its `PROJECT.md` across when that holds rules (case 9).
+ * - `hold`: change nothing, and say what would let the move happen (cases 6, 8, 9, and a split that cannot be added).
+ * - `deprecate`: a file outside a skill folder, whose receiving capability the project does not install.
+ */
+export interface PlannedMove {
+    fromCapability: string;
+    /** The declared key; a folder ends in `/` */
+    from: string;
+    toCapability: string;
+    to: string;
+    isSkillFolder: boolean;
+    outcome: 'move' | 'remove' | 'merge' | 'hold' | 'deprecate';
+    state: MoveState;
+    /** True when the old folder's PROJECT.md holds more than the template */
+    projectFileCarried?: boolean;
+    /** For a hold: what would let the move happen */
+    instruction?: string;
+    /** The stored paths under the key, and their hashes */
+    storedHashes: Record<string, string>;
+}
+export interface MovePassPlan {
+    moves: PlannedMove[];
+    /** Capabilities split out of an installed one, which the update adds before moving files into them */
+    splitsToAdd: {
+        capability: string;
+        splitFrom: string;
+    }[];
+}
+export interface MoveResult {
+    /** The capability the files left */
+    capability: string;
+    moved: {
+        from: string;
+        to: string;
+        toCapability: string;
+    }[];
+    removed: string[];
+    instructions: FileInstruction[];
+}
+/**
+ * Settle every declared move the project holds paths for. Writes nothing.
+ *
+ * `updating` is the capabilities this update was asked for: a move runs when
+ * either end of it is among them. `unaddable` names split capabilities the
+ * update tried and failed to add, with the reason, so their moves wait.
+ */
+export declare function planMoves(targetDir: string, manifest: BoopManifest, updating: string[], options?: {
+    unaddable?: Record<string, string>;
+}): MovePassPlan;
+/**
+ * The actions a planned move adds to the leaving capability's plan: one per
+ * stored path for a move, removal or deprecation, and one for the whole key
+ * for a hold, which changes nothing and carries the instruction.
+ */
+export declare function moveActions(move: PlannedMove): FileUpdateAction[];
+/**
+ * Carry out every planned `move`, `remove` and `merge`, and write the manifest
+ * once afterwards. A hold or deprecation is left to the leaving capability's
+ * plan. Returns what happened, by the capability the files left.
+ */
+export declare function executeMoves(targetDir: string, moves: PlannedMove[]): Map<string, MoveResult>;
+/** The paths that arrive in each capability by a planned move, for the add and plan that must leave them out */
+export declare function arrivingPaths(moves: PlannedMove[], capability: string): string[];

package/dist/lib/moves.js

@@ -0,0 +1,381 @@
+"use strict";
+/**
+ * The move pass of `boop update`: files a capability stopped shipping because
+ * another capability ships them now (specs/skill-moves.spec.md).
+ *
+ * The capability the files leave declares where they went, in `file_moves`, and
+ * names any capability split out of it in `split_into`. The pass reads those
+ * declarations from every installed capability, settles each moved path the
+ * project holds a stored hash for, and runs before any capability is planned:
+ * a move is a rename on disk plus a transfer of stored hashes, and everything
+ * after that is the receiving capability's ordinary update.
+ */
+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.planMoves = planMoves;
+exports.moveActions = moveActions;
+exports.executeMoves = executeMoves;
+exports.arrivingPaths = arrivingPaths;
+const fs = __importStar(require("fs"));
+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");
+const update_1 = require("./update");
+/**
+ * Settle every declared move the project holds paths for. Writes nothing.
+ *
+ * `updating` is the capabilities this update was asked for: a move runs when
+ * either end of it is among them. `unaddable` names split capabilities the
+ * update tried and failed to add, with the reason, so their moves wait.
+ */
+function planMoves(targetDir, manifest, updating, options = {}) {
+    const moves = [];
+    const splitsToAdd = [];
+    const template = (0, scaffold_1.readSkillProjectTemplate)();
+    for (const fromCapability of manifest.capabilities) {
+        const declarations = readDeclarations(fromCapability, targetDir);
+        if (!declarations)
+            continue;
+        const storedHashes = manifest.capabilityMeta?.[fromCapability]?.fileHashes ?? {};
+        for (const [from, declaration] of Object.entries(declarations.fileMoves)) {
+            const covered = Object.entries(storedHashes).filter(([p]) => isUnder(p, from));
+            if (covered.length === 0)
+                continue;
+            const isFolder = from.endsWith('/');
+            const destination = resolveDestination(targetDir, declaration.capability, declaration.path ?? from);
+            const toCapability = destination.capability;
+            const to = destination.path;
+            if (![fromCapability, declaration.capability, toCapability].some(c => updating.includes(c)))
+                continue;
+            const move = {
+                fromCapability,
+                from,
+                toCapability,
+                to,
+                isSkillFolder: isFolder && isSkillFolderPath(from),
+                outcome: 'move',
+                state: 'will-move',
+                storedHashes: Object.fromEntries(covered),
+            };
+            const oldProjectFile = path.join(targetDir, from, 'PROJECT.md');
+            const newProjectFile = path.join(targetDir, to, 'PROJECT.md');
+            const isSplit = toCapability === declaration.capability && declarations.splitInto.includes(toCapability);
+            if (manifest.capabilities.includes(toCapability)) {
+                if (!destination.ships) {
+                    hold(move, 'waiting-for-package', `${toCapability}'s installed package does not ship ${to} yet. Run \`boop update ${toCapability}\` to carry it across.`);
+                }
+                else if (isFolder && alreadyInstalled(targetDir, manifest, toCapability, to)) {
+                    const oldEdited = covered.some(([p, hash]) => fs.existsSync(path.join(targetDir, p)) && (0, scaffold_1.hashFile)(path.join(targetDir, p)) !== hash);
+                    const oldRules = holdsRules(oldProjectFile, template);
+                    if (!oldEdited && !(oldRules && holdsRules(newProjectFile, template))) {
+                        move.outcome = 'merge';
+                        move.projectFileCarried = oldRules;
+                    }
+                    else {
+                        hold(move, 'kept-for-project-content', `${toCapability} already installed this skill as ${trimSlash(to)}. Move this project's rules from ${trimSlash(from)} into ${path.join(to, 'PROJECT.md')}, following the ${update_1.TRIAGE_SKILL} skill, with boop's copy at ${path.join(to, 'SKILL.md')}, then delete ${trimSlash(from)}.`);
+                    }
+                }
+                else if (!isFolder && to !== from && fs.existsSync(path.join(targetDir, to))) {
+                    // The spec has no case for a renamed file whose new path is taken; never write over it.
+                    hold(move, 'kept-for-project-content', `${to} already exists, so boop did not move ${from} onto it. Keep whichever this project needs, delete the other, and run \`boop update\`.`);
+                }
+                else {
+                    move.projectFileCarried = isFolder && holdsRules(oldProjectFile, template);
+                }
+            }
+            else if (isSplit) {
+                const reason = options.unaddable?.[toCapability];
+                if (reason) {
+                    hold(move, 'waiting-for-capability', `${toCapability} was split from ${fromCapability}, and boop could not add it: ${reason}. Run \`boop add ${toCapability}\`, and the next update carries ${trimSlash(from)} across.`);
+                }
+                else {
+                    move.state = 'split-will-add';
+                    move.projectFileCarried = isFolder && holdsRules(oldProjectFile, template);
+                    if (!splitsToAdd.some(s => s.capability === toCapability)) {
+                        splitsToAdd.push({ capability: toCapability, splitFrom: fromCapability });
+                    }
+                }
+            }
+            else if (!move.isSkillFolder) {
+                // A code file or reference page belongs to the project once it is there (file safety)
+                move.outcome = 'deprecate';
+            }
+            else if (carriesProjectContent(targetDir, from, move.storedHashes, template)) {
+                hold(move, 'kept-for-project-content', `Kept because it holds this project's rules. Run \`boop add ${toCapability}\` and \`boop update\` to carry it across, or delete the folder if this project does not need it.`);
+            }
+            else {
+                move.outcome = 'remove';
+            }
+            moves.push(move);
+        }
+    }
+    return { moves, splitsToAdd };
+}
+/**
+ * The actions a planned move adds to the leaving capability's plan: one per
+ * stored path for a move, removal or deprecation, and one for the whole key
+ * for a hold, which changes nothing and carries the instruction.
+ */
+function moveActions(move) {
+    const shared = { toCapability: move.toCapability };
+    if (move.outcome === 'hold') {
+        return [{
+                ...shared,
+                relativePath: trimSlash(move.from),
+                action: 'skip',
+                reason: `Moved to ${move.toCapability}, waiting`,
+                movedTo: move.to,
+                instruction: move.instruction,
+            }];
+    }
+    return Object.entries(move.storedHashes).map(([relativePath, storedHash]) => {
+        const movedTo = newPathFor(relativePath, move.from, move.to);
+        switch (move.outcome) {
+            case 'deprecate':
+                return {
+                    ...shared,
+                    relativePath,
+                    action: 'deprecate',
+                    reason: `Moved to ${move.toCapability}, which this project does not install; leaving in place`,
+                    storedHash,
+                    movedTo,
+                };
+            case 'move':
+                return {
+                    ...shared,
+                    relativePath,
+                    action: 'move',
+                    reason: `Moved to ${move.toCapability} as ${movedTo}`,
+                    storedHash,
+                    movedTo,
+                    projectFileCarried: move.isSkillFolder ? move.projectFileCarried : undefined,
+                };
+            default:
+                return {
+                    ...shared,
+                    relativePath,
+                    action: 'remove',
+                    reason: move.outcome === 'merge'
+                        ? `${move.toCapability} already installed ${movedTo}`
+                        : `Now ships in ${move.toCapability}, which this project does not install`,
+                    storedHash,
+                    movedTo,
+                };
+        }
+    });
+}
+/**
+ * Carry out every planned `move`, `remove` and `merge`, and write the manifest
+ * once afterwards. A hold or deprecation is left to the leaving capability's
+ * plan. Returns what happened, by the capability the files left.
+ */
+function executeMoves(targetDir, moves) {
+    const results = new Map();
+    const manifest = (0, project_1.readProjectManifest)(targetDir);
+    if (!manifest)
+        return results;
+    manifest.capabilityMeta = manifest.capabilityMeta ?? {};
+    const meta = manifest.capabilityMeta;
+    const template = (0, scaffold_1.readSkillProjectTemplate)();
+    for (const move of moves) {
+        if (move.outcome !== 'move' && move.outcome !== 'remove' && move.outcome !== 'merge')
+            continue;
+        let result = results.get(move.fromCapability);
+        if (!result) {
+            result = { capability: move.fromCapability, moved: [], removed: [], instructions: [] };
+            results.set(move.fromCapability, result);
+        }
+        const fromHashes = meta[move.fromCapability]?.fileHashes ?? {};
+        const oldAbs = path.join(targetDir, move.from);
+        const newAbs = path.join(targetDir, move.to);
+        const existedOnDisk = fs.existsSync(oldAbs);
+        if (move.outcome === 'move') {
+            if (existedOnDisk && move.from !== move.to) {
+                fs.mkdirSync(path.dirname(trimSlash(newAbs)), { recursive: true });
+                fs.renameSync(trimSlash(oldAbs), trimSlash(newAbs));
+            }
+            const receiving = meta[move.toCapability] ?? { installedAt: new Date().toISOString(), fileHashes: {} };
+            meta[move.toCapability] = receiving;
+            receiving.movedFrom = receiving.movedFrom ?? {};
+            for (const [oldPath, hash] of Object.entries(move.storedHashes)) {
+                const newPath = newPathFor(oldPath, move.from, move.to);
+                delete fromHashes[oldPath];
+                // A hash the receiving capability recorded itself is a newer base than the one moving in
+                if (!(newPath in receiving.fileHashes)) {
+                    receiving.fileHashes[newPath] = hash;
+                    receiving.movedFrom[newPath] = { capability: move.fromCapability, path: oldPath };
+                }
+            }
+            if (Object.keys(receiving.movedFrom).length === 0)
+                delete receiving.movedFrom;
+        }
+        else {
+            if (move.outcome === 'merge' && move.projectFileCarried) {
+                fs.mkdirSync(newAbs, { recursive: true });
+                fs.renameSync(path.join(oldAbs, 'PROJECT.md'), path.join(newAbs, 'PROJECT.md'));
+            }
+            for (const oldPath of Object.keys(move.storedHashes)) {
+                fs.rmSync(path.join(targetDir, oldPath), { force: true });
+                delete fromHashes[oldPath];
+            }
+            if (move.from.endsWith('/'))
+                removeFolderIfEmpty(trimSlash(oldAbs), template);
+        }
+        if (move.outcome === 'remove') {
+            if (existedOnDisk)
+                result.removed.push(move.from);
+            continue;
+        }
+        result.moved.push({ from: move.from, to: move.to, toCapability: move.toCapability });
+        const oldName = path.basename(trimSlash(move.from));
+        const newName = path.basename(trimSlash(move.to));
+        if (move.isSkillFolder && oldName !== newName) {
+            result.instructions.push({
+                relativePath: move.from,
+                instruction: `Search this project's own files for ${oldName} and change each mention to ${newName}.`,
+            });
+        }
+    }
+    (0, project_1.writeProjectManifest)(targetDir, manifest);
+    return results;
+}
+/** The paths that arrive in each capability by a planned move, for the add and plan that must leave them out */
+function arrivingPaths(moves, capability) {
+    return moves
+        .filter(m => m.toCapability === capability && m.outcome !== 'hold' && m.outcome !== 'deprecate')
+        .map(m => m.to);
+}
+function isUnder(relPath, key) {
+    return (0, install_layout_1.isUnderAny)(relPath, [key]);
+}
+function hold(move, state, instruction) {
+    move.outcome = 'hold';
+    move.state = state;
+    move.instruction = instruction;
+}
+function readDeclarations(capability, targetDir) {
+    const pkgDir = (0, capability_1.getPackageDir)(capability, [targetDir]);
+    if (!pkgDir)
+        return null;
+    const capJsonPath = path.join(pkgDir, 'capability.json');
+    if (!fs.existsSync(capJsonPath))
+        return null;
+    const capJson = JSON.parse(fs.readFileSync(capJsonPath, 'utf-8'));
+    if (!capJson.file_moves)
+        return null;
+    return { fileMoves: capJson.file_moves, splitInto: capJson.split_into ?? [] };
+}
+/**
+ * Where a moved path ships now. When the named capability's package does not
+ * ship it but declares a move of its own for it, the path moved again before
+ * this project updated, so follow it.
+ */
+function resolveDestination(targetDir, capability, toPath) {
+    const seen = new Set();
+    let current = { capability, path: toPath };
+    while (!seen.has(current.capability)) {
+        seen.add(current.capability);
+        const pkgDir = (0, capability_1.getPackageDir)(current.capability, [targetDir]);
+        if (!pkgDir)
+            break;
+        const dests = (0, install_layout_1.capabilityPlacementsFromDir)(pkgDir).map(p => p.dest);
+        if (dests.some(d => isUnder(d, current.path)))
+            return { ...current, ships: true };
+        const onward = Object.entries(readDeclarations(current.capability, targetDir)?.fileMoves ?? {})
+            .find(([key]) => isUnder(current.path, key));
+        if (!onward)
+            break;
+        const [key, declaration] = onward;
+        current = { capability: declaration.capability, path: newPathFor(current.path, key, declaration.path ?? key) };
+    }
+    return { ...current, ships: false };
+}
+/** Whether the receiving capability has already put the new folder in this project */
+function alreadyInstalled(targetDir, manifest, capability, folder) {
+    const hashes = manifest.capabilityMeta?.[capability]?.fileHashes ?? {};
+    return Object.keys(hashes).some(p => isUnder(p, folder)) || fs.existsSync(path.join(targetDir, folder));
+}
+/**
+ * Whether an old skill folder carries anything of the project's: a tracked
+ * file that differs from its stored hash, a PROJECT.md that holds rules, or a
+ * file boop did not install.
+ */
+function carriesProjectContent(targetDir, folder, storedHashes, template) {
+    for (const [p, hash] of Object.entries(storedHashes)) {
+        const abs = path.join(targetDir, p);
+        if (fs.existsSync(abs) && (0, scaffold_1.hashFile)(abs) !== hash)
+            return true;
+    }
+    const projectFile = path.join(folder, 'PROJECT.md');
+    if (holdsRules(path.join(targetDir, projectFile), template))
+        return true;
+    return filesUnder(path.join(targetDir, folder)).some(abs => {
+        const rel = path.relative(targetDir, abs);
+        return rel !== projectFile && !(rel in storedHashes);
+    });
+}
+function holdsRules(projectFilePath, template) {
+    return fs.existsSync(projectFilePath) && fs.readFileSync(projectFilePath, 'utf-8') !== template;
+}
+/** Delete a skill folder once nothing is left in it but a template PROJECT.md */
+function removeFolderIfEmpty(folderAbs, template) {
+    if (!fs.existsSync(folderAbs))
+        return;
+    const projectFile = path.join(folderAbs, 'PROJECT.md');
+    const left = filesUnder(folderAbs);
+    if (left.every(f => f === projectFile && fs.readFileSync(f, 'utf-8') === template)) {
+        fs.rmSync(folderAbs, { recursive: true, force: true });
+    }
+}
+function filesUnder(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+        const abs = path.join(dir, entry.name);
+        return entry.isDirectory() ? filesUnder(abs) : [abs];
+    });
+}
+function newPathFor(relPath, from, to) {
+    return from.endsWith('/') ? to + relPath.slice(from.length) : to;
+}
+function isSkillFolderPath(folder) {
+    const segments = folder.split('/');
+    return segments.length === 3 && segments[0] === 'skills' && segments[2] === '';
+}
+function trimSlash(p) {
+    return p.endsWith('/') ? p.slice(0, -1) : p;
+}

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

@@ -8,6 +8,8 @@
  * 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.
+ * A file that arrived by a move from another capability is also searched for
+ * under the path it had there, in history and in that capability's versions.
  */
 export type OriginalTextSource = {
     kind: 'git';

package/dist/lib/original-text.js

@@ -9,6 +9,8 @@
  * 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.
+ * A file that arrived by a move from another capability is also searched for
+ * under the path it had there, in history and in that capability's versions.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -60,8 +62,17 @@ const scaffold_1 = require("./scaffold");
  * is a miss for that source, and a miss in both is `{ found: false }`.
  */
 function findOriginalText(projectDir, relPath, storedHash, options = {}) {
+    const registry = options.registry ?? exports.npmRegistry;
+    const owner = owningCapability(projectDir, relPath);
+    // A file that arrived by a move was installed under another path, by another capability
+    const movedFrom = owner?.movedFrom?.[relPath];
     return (findInGitHistory(projectDir, relPath, storedHash) ??
-        findInPublishedVersions(projectDir, relPath, storedHash, options.registry ?? exports.npmRegistry));
+        (owner ? findInPublishedVersions(projectDir, owner.capability, relPath, storedHash, registry) : null) ??
+        (movedFrom
+            ? findInGitHistory(projectDir, movedFrom.path, storedHash) ??
+                findInPublishedVersions(projectDir, movedFrom.capability, movedFrom.path, storedHash, registry)
+            : null) ??
+        { found: false });
 }
 function findInGitHistory(projectDir, relPath, storedHash) {
     let commits;
@@ -89,10 +100,7 @@ function findInGitHistory(projectDir, relPath, storedHash) {
 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 };
+function findInPublishedVersions(projectDir, capability, relPath, storedHash, registry) {
     const packageName = packageNameFor(capability, projectDir);
     const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'boop-original-text-'));
     try {
@@ -113,7 +121,7 @@ function findInPublishedVersions(projectDir, relPath, storedHash, registry) {
     finally {
         fs.rmSync(workDir, { recursive: true, force: true });
     }
-    return { found: false };
+    return null;
 }
 function owningCapability(projectDir, relPath) {
     let manifest;
@@ -124,7 +132,7 @@ function owningCapability(projectDir, relPath) {
         return null;
     }
     const entry = Object.entries(manifest?.capabilityMeta ?? {}).find(([, meta]) => relPath in (meta.fileHashes ?? {}));
-    return entry ? entry[0] : null;
+    return entry ? { ...entry[1], capability: entry[0] } : null;
 }
 function packageNameFor(capability, projectDir) {
     // The installed package knows its own name; `users-and-accounts` ships as @boopkit/cap-users.

package/dist/lib/preflight.d.ts

@@ -21,6 +21,19 @@ export interface PlanAddResult {
     filesToCopy: string[];
     /** Warnings generated during pre-flight (non-fatal) */
     warnings: string[];
+    /** Files the add creates because the project lacks them (relative paths) */
+    creates: string[];
+}
+export interface PlanAddOptions {
+    /** Where to resolve the capability package; defaults to the project alone */
+    searchPaths?: string[];
+    /** Command that installs the capability package into the project, run before anything reads it there */
+    installCommand?: string;
+    /**
+     * Paths not to copy, because they arrive by a move (a folder ends in `/`).
+     * `boop update` passes them when it adds a capability split out of another.
+     */
+    excludePaths?: string[];
 }
 /**
  * Plan a `boop add` operation. Reads filesystem, validates everything,
@@ -28,4 +41,4 @@ export interface PlanAddResult {
  *
  * Throws PreflightError if any check fails.
  */
-export declare function planAdd(targetDir: string, capabilityName: string): PlanAddResult;
+export declare function planAdd(targetDir: string, capabilityName: string, options?: PlanAddOptions): PlanAddResult;