@boopkit/cli 0.7.1 → 0.8.1

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;

package/dist/lib/preflight.js

@@ -61,21 +61,46 @@ exports.PreflightError = PreflightError;
  *
  * Throws PreflightError if any check fails.
  */
-function planAdd(targetDir, capabilityName) {
+function planAdd(targetDir, capabilityName, options = {}) {
     const checks = [];
     const tasks = [];
     const warnings = [];
+    const creates = [];
     const boopRoot = (0, config_1.getBoopRoot)();
+    const searchPaths = options.searchPaths ?? [targetDir];
+    const pkgJsonPath = path.join(targetDir, 'package.json');
+    const hasPackageJson = fs.existsSync(pkgJsonPath);
     // --- Pre-flight checks ---
-    // 1. Validate project
-    const projectManifest = (0, project_1.readProjectManifest)(targetDir);
-    if (!projectManifest) {
-        checks.push({ name: 'project-exists', passed: false, message: 'Not a boop project (no .boop/config.json)' });
-        throw new PreflightError('Pre-flight failed', checks);
+    // 1. Validate project. A project boop did not scaffold has no config yet;
+    // the add creates one, so this is the first capability it records.
+    const existingManifest = (0, project_1.readProjectManifest)(targetDir);
+    const projectManifest = existingManifest ?? (0, project_1.manifestForUnscaffoldedProject)(targetDir);
+    if (existingManifest) {
+        checks.push({ name: 'project-exists', passed: true });
+    }
+    else {
+        checks.push({ name: 'project-exists', passed: true, message: 'No .boop/config.json — it will be created' });
+        if (!hasPackageJson) {
+            creates.push('package.json');
+            tasks.push({
+                op: 'create-package-json',
+                target: pkgJsonPath,
+                detail: 'Create a minimal package.json, which records capability packages',
+                status: 'pending',
+                data: { projectName: projectManifest.name },
+            });
+        }
+        creates.push('.boop/config.json');
+        tasks.push({
+            op: 'create-manifest',
+            target: path.join(targetDir, '.boop', 'config.json'),
+            detail: `Create .boop/config.json for ${projectManifest.name} (profile: ${projectManifest.profile})`,
+            status: 'pending',
+            data: { manifest: projectManifest },
+        });
     }
-    checks.push({ name: 'project-exists', passed: true });
     // 2. Resolve capability (search project's node_modules first, then CLI root)
-    const cap = (0, capability_1.getCapability)(capabilityName, [targetDir]);
+    const cap = (0, capability_1.getCapability)(capabilityName, searchPaths);
     if (!cap) {
         checks.push({ name: 'capability-exists', passed: false, message: `Capability "${capabilityName}" not found` });
         throw new PreflightError('Pre-flight failed', checks);
@@ -101,11 +126,13 @@ function planAdd(targetDir, capabilityName) {
         checks.push({ name: 'requires-satisfied', passed: true });
     }
     // 5. Enumerate files that would be copied — check for conflicts.
-    const pkgDir = (0, capability_1.getPackageDir)(capabilityName, [targetDir]);
+    const pkgDir = (0, capability_1.getPackageDir)(capabilityName, searchPaths);
     const capDir = pkgDir ?? path.join(boopRoot, 'capabilities', capabilityName);
     // The placement list is the same one `copyCapabilityFiles` copies from, so
     // this cannot disagree with what `boop add` actually writes.
-    const filesToCopy = (0, install_layout_1.capabilityPlacements)(capabilityName, [targetDir]).map(p => p.dest);
+    const excludePaths = options.excludePaths ?? [];
+    const filesToCopy = (0, install_layout_1.capabilityPlacements)(capabilityName, searchPaths).map(p => p.dest)
+        .filter(dest => !(0, install_layout_1.isUnderAny)(dest, excludePaths));
     const fileConflicts = filesToCopy.filter(dest => fs.existsSync(path.join(targetDir, dest)));
     // File conflicts are warnings (skip behavior), not failures
     if (fileConflicts.length > 0) {
@@ -165,9 +192,8 @@ function planAdd(targetDir, capabilityName) {
     }
     // 6. Check for script conflicts
     if (cap.scripts) {
-        const pkgPath = path.join(targetDir, 'package.json');
-        if (fs.existsSync(pkgPath)) {
-            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        if (hasPackageJson) {
+            const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
             const existingScripts = pkg.scripts || {};
             const conflicts = [];
             for (const scriptName of Object.keys(cap.scripts)) {
@@ -193,6 +219,17 @@ function planAdd(targetDir, capabilityName) {
         throw new PreflightError(`Pre-flight failed: ${failedChecks.map(c => c.message).join('; ')}`, checks);
     }
     // --- Build task manifest ---
+    // Task: install the capability package. It follows the files a bare project
+    // lacks, so npm records it in boop's package.json rather than making its own.
+    if (options.installCommand) {
+        tasks.push({
+            op: 'install-package',
+            target: targetDir,
+            detail: options.installCommand,
+            status: 'pending',
+            data: { command: options.installCommand },
+        });
+    }
     // Task: copy files
     if (filesToCopy.length > 0) {
         tasks.push({
@@ -201,7 +238,7 @@ function planAdd(targetDir, capabilityName) {
             target: targetDir,
             detail: `Copy ${filesToCopy.length} file(s) from ${capabilityName}`,
             status: 'pending',
-            data: { files: filesToCopy, conflicts: fileConflicts },
+            data: { files: filesToCopy, conflicts: fileConflicts, exclude: excludePaths },
         });
     }
     // Task: merge dependencies
@@ -320,8 +357,7 @@ function planAdd(targetDir, capabilityName) {
     });
     // Task: rebuild CSS if we injected styles and the project has tailwind:build
     const hasInjectCss = tasks.some(t => t.op === 'inject-css');
-    if (hasInjectCss) {
-        const pkgJsonPath = path.join(targetDir, 'package.json');
+    if (hasInjectCss && hasPackageJson) {
         const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
         if (pkgJson.scripts?.['tailwind:build']) {
             tasks.push({
@@ -340,5 +376,5 @@ function planAdd(targetDir, capabilityName) {
         preflight: { passed: true, checks },
         tasks,
     };
-    return { manifest, cap, projectManifest, filesToCopy, warnings };
+    return { manifest, cap, projectManifest, filesToCopy, warnings, creates };
 }

package/dist/lib/project.d.ts

@@ -8,6 +8,15 @@ export interface CapabilityMeta {
     installedAt: string;
     version?: string;
     fileHashes: Record<string, string>;
+    /**
+     * For a file that arrived by a move from another capability: where boop
+     * installed it before, so the original text can still be found. Dropped once
+     * this capability writes the file's hash itself.
+     */
+    movedFrom?: Record<string, {
+        capability: string;
+        path: string;
+    }>;
 }
 export interface BoopManifest {
     name: string;
@@ -30,6 +39,14 @@ export declare function readProjectManifest(dir: string): BoopManifest | null;
  * Creates the .boop/ directory if it does not exist.
  */
 export declare function writeProjectManifest(dir: string, manifest: BoopManifest): void;
+/**
+ * The manifest `boop add` creates for a project boop did not scaffold, such as
+ * an app made by another tool. It is named like `boop init` names a project,
+ * unless the project's own package.json already gives it a name, and records
+ * the `development` profile, which is what a repository that brings in boop's
+ * development capabilities without its scaffold uses.
+ */
+export declare function manifestForUnscaffoldedProject(dir: string): BoopManifest;
 /**
  * Check if a directory contains a boop project (.boop/config.json exists).
  */

package/dist/lib/project.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readProjectManifest = readProjectManifest;
 exports.writeProjectManifest = writeProjectManifest;
+exports.manifestForUnscaffoldedProject = manifestForUnscaffoldedProject;
 exports.isBoopProject = isBoopProject;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -63,6 +64,31 @@ function writeProjectManifest(dir, manifest) {
     const manifestPath = path.join(boopDir, 'config.json');
     fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
 }
+/**
+ * The manifest `boop add` creates for a project boop did not scaffold, such as
+ * an app made by another tool. It is named like `boop init` names a project,
+ * unless the project's own package.json already gives it a name, and records
+ * the `development` profile, which is what a repository that brings in boop's
+ * development capabilities without its scaffold uses.
+ */
+function manifestForUnscaffoldedProject(dir) {
+    return {
+        name: packageJsonName(dir) ?? path.basename(dir),
+        profile: 'development',
+        boopVersion: '0.1.0',
+        capabilities: [],
+        createdAt: new Date().toISOString(),
+    };
+}
+function packageJsonName(dir) {
+    try {
+        const { name } = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+        return typeof name === 'string' && name.length > 0 ? name : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Check if a directory contains a boop project (.boop/config.json exists).
  */