@boopkit/cli 0.6.8 → 0.6.10

package/dist/lib/install-layout.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * The single answer to "where does a file land when it is installed".
+ *
+ * `boop add` copies a capability's files into a project and `boop init` copies a
+ * profile's reference pages; before this module the mapping from source file to
+ * destination path was written out twice — once read-only inside `planAdd`, once
+ * while copying inside `copyFromPackage` — so the two could disagree about what a
+ * project receives and nothing would notice. Everything here is a pure read: it
+ * looks at a package or profile directory and returns `Placement[]`. It never
+ * writes, never needs a `targetDir`, and never touches `.boop/`.
+ *
+ * Three consumers depend on it: `copyFromPackage` (src/lib/scaffold.ts),
+ * `planAdd` (src/lib/preflight.ts) and `tools/generate-installed-layout.ts`,
+ * which materialises the installed layout inside the boop repository itself.
+ * Adding a fourth answer to this question is the defect this module exists to
+ * prevent.
+ */
+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.PlacementCollisionError = void 0;
+exports.describePlacementOwner = describePlacementOwner;
+exports.capabilityPlacementsFromDir = capabilityPlacementsFromDir;
+exports.capabilityPlacements = capabilityPlacements;
+exports.profilePlacements = profilePlacements;
+exports.skillDirectoryPlacements = skillDirectoryPlacements;
+exports.findPlacementCollisions = findPlacementCollisions;
+exports.assertNoPlacementCollisions = assertNoPlacementCollisions;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const capability_1 = require("./capability");
+class PlacementCollisionError extends Error {
+    constructor(collisions) {
+        super(`Placement collision:\n${collisions.map(describeCollision).join('\n')}`);
+        this.name = 'PlacementCollisionError';
+        this.collisions = collisions;
+    }
+}
+exports.PlacementCollisionError = PlacementCollisionError;
+/** How a collision names each side: the owner, and for hand-authored files, that nothing ships it. */
+function describePlacementOwner(placement) {
+    return placement.ownerKind === 'hand-authored'
+        ? `${placement.owner} (hand-authored, no owner)`
+        : placement.owner;
+}
+function describeCollision(collision) {
+    const owners = collision.placements.map(describePlacementOwner).join(' and ');
+    return `  ${collision.dest} — claimed by ${owners}`;
+}
+function toPosix(relPath) {
+    return relPath.split(path.sep).join('/');
+}
+/** Every file under `dir`, absolute, depth-first, sorted for a stable placement order. */
+function walkFiles(dir) {
+    const found = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory() || (entry.isSymbolicLink() && fs.statSync(full).isDirectory())) {
+            found.push(...walkFiles(full));
+        }
+        else {
+            found.push(full);
+        }
+    }
+    return found;
+}
+/**
+ * `<skillsDir>/<skill-name>/**` → `skills/<skill-name>/**`.
+ * Only directories are skills; a loose file beside them ships nothing.
+ */
+function skillPlacements(skillsDir, owner, ownerKind) {
+    if (!fs.existsSync(skillsDir))
+        return [];
+    const placements = [];
+    for (const entry of fs.readdirSync(skillsDir).sort()) {
+        const skillDir = path.join(skillsDir, entry);
+        if (!fs.statSync(skillDir).isDirectory())
+            continue;
+        for (const source of walkFiles(skillDir)) {
+            placements.push({
+                owner,
+                ownerKind,
+                source,
+                dest: `skills/${entry}/${toPosix(path.relative(skillDir, source))}`,
+                kind: 'skill',
+            });
+        }
+    }
+    return placements;
+}
+/**
+ * `<scaffoldDir>/**` → `<destPrefix>**`, preserving the tree.
+ * The scaffold directory mirrors the target project's own layout.
+ */
+function scaffoldPlacements(scaffoldDir, owner, ownerKind, destPrefix = '') {
+    if (!fs.existsSync(scaffoldDir))
+        return [];
+    return walkFiles(scaffoldDir).map(source => ({
+        owner,
+        ownerKind,
+        source,
+        dest: destPrefix + toPosix(path.relative(scaffoldDir, source)),
+        kind: 'scaffold',
+    }));
+}
+/**
+ * Placements for an already-resolved capability package directory.
+ *
+ * `capabilityPlacements` delegates here once it has resolved a name to a package;
+ * the generator calls it directly because it walks `packages/cap-*` on disk and
+ * has no need of npm module resolution (and must not require a build).
+ */
+function capabilityPlacementsFromDir(pkgDir) {
+    const pkgJsonPath = path.join(pkgDir, 'package.json');
+    if (!fs.existsSync(pkgJsonPath))
+        return [];
+    const boopkit = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).boopkit;
+    if (!boopkit)
+        return [];
+    const owner = path.basename(pkgDir);
+    const placements = [];
+    if (boopkit.skillsDir) {
+        placements.push(...skillPlacements(path.join(pkgDir, boopkit.skillsDir), owner, 'capability'));
+    }
+    if (boopkit.scaffoldDir) {
+        placements.push(...scaffoldPlacements(path.join(pkgDir, boopkit.scaffoldDir), owner, 'capability'));
+    }
+    return placements;
+}
+function isCapabilityPackage(pkgDir) {
+    const pkgJsonPath = path.join(pkgDir, 'package.json');
+    if (!fs.existsSync(pkgJsonPath))
+        return false;
+    return JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).boopkit?.capability === true;
+}
+/**
+ * Every file a capability ships and where it lands in a project.
+ *
+ * Resolves the capability the way `boop add` does — the installed package first,
+ * then the `capabilities/` source tree that only test fixtures still use.
+ */
+function capabilityPlacements(capabilityName, searchPaths) {
+    const pkgDir = (0, capability_1.getPackageDir)(capabilityName, searchPaths);
+    if (pkgDir && isCapabilityPackage(pkgDir)) {
+        return capabilityPlacementsFromDir(pkgDir);
+    }
+    const capDir = path.join((0, config_1.getBoopRoot)(), 'capabilities', capabilityName);
+    if (!fs.existsSync(capDir))
+        return [];
+    const owner = `cap-${capabilityName}`;
+    return [
+        ...skillPlacements(path.join(capDir, 'skills'), owner, 'capability'),
+        ...scaffoldPlacements(path.join(capDir, 'files'), owner, 'capability'),
+    ];
+}
+/**
+ * Every file a profile ships and where it lands, mirroring `boop init`
+ * (src/commands/init.ts) — today that is the profile's reference pages.
+ */
+function profilePlacements(profileName, repoRoot) {
+    const profileDir = path.join(repoRoot ?? (0, config_1.getBoopRoot)(), 'profiles', profileName);
+    return scaffoldPlacements(path.join(profileDir, 'reference'), profileName, 'profile', 'reference/');
+}
+/**
+ * The directory-level view of a skill's placements: one entry per skill folder.
+ *
+ * The mirror materialises a skill as a single link to its folder rather than a
+ * link per file, and this derives that view from the same placement list rather
+ * than re-deriving `skills/<name>` from a package layout a second time.
+ */
+function skillDirectoryPlacements(placements) {
+    // Keyed by folder *and* source, so two capabilities shipping the same skill
+    // name stay two placements and the collision check can still see them.
+    const folders = new Map();
+    for (const placement of placements) {
+        if (placement.kind !== 'skill')
+            continue;
+        const [, skillName] = placement.dest.split('/');
+        const dest = `skills/${skillName}`;
+        // The file's path within its skill folder is the same suffix in source and dest,
+        // so trimming it from the source yields the folder the link must point at.
+        const withinSkill = placement.dest.slice(dest.length + 1);
+        const source = placement.source.slice(0, placement.source.length - withinSkill.length - 1);
+        folders.set(`${dest}\u0000${source}`, { ...placement, source, dest });
+    }
+    return [...folders.values()];
+}
+/** Every destination claimed by two or more different source files. */
+function findPlacementCollisions(placements) {
+    const byDest = new Map();
+    for (const placement of placements) {
+        const claimants = byDest.get(placement.dest) ?? [];
+        claimants.push(placement);
+        byDest.set(placement.dest, claimants);
+    }
+    const collisions = [];
+    for (const [dest, claimants] of byDest) {
+        const sources = new Set(claimants.map(p => p.source));
+        if (sources.size > 1)
+            collisions.push({ dest, placements: claimants });
+    }
+    return collisions.sort((a, b) => a.dest.localeCompare(b.dest));
+}
+/**
+ * Throw if any destination is claimed twice.
+ *
+ * The install path would not throw — `safeCopyDir` applies `onConflict: 'skip'`
+ * per file, so a second claimant silently half-merges into the first. That is
+ * fine to warn about while installing one capability into a project and fatal
+ * when writing a mirror of the whole library, which is why this is a separate
+ * assertion rather than something `planAdd` inherits.
+ */
+function assertNoPlacementCollisions(placements) {
+    const collisions = findPlacementCollisions(placements);
+    if (collisions.length > 0)
+        throw new PlacementCollisionError(collisions);
+}

package/dist/lib/preflight.js

@@ -45,6 +45,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const config_1 = require("./config");
 const capability_1 = require("./capability");
+const install_layout_1 = require("./install-layout");
 const project_1 = require("./project");
 class PreflightError extends Error {
     constructor(message, checks) {
@@ -99,42 +100,13 @@ function planAdd(targetDir, capabilityName) {
         }
         checks.push({ name: 'requires-satisfied', passed: true });
     }
-    // 5. Enumerate files that would be copied — check for conflicts
-    // Resolve from package (scaffold/ and skills/) or source tree (files/ and skills/)
+    // 5. Enumerate files that would be copied — check for conflicts.
     const pkgDir = (0, capability_1.getPackageDir)(capabilityName, [targetDir]);
-    const pkgJsonPath = pkgDir ? path.join(pkgDir, 'package.json') : null;
-    const pkgJson = pkgJsonPath && fs.existsSync(pkgJsonPath)
-        ? JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'))
-        : null;
-    const boopkit = pkgJson?.boopkit;
-    const capDir = boopkit
-        ? pkgDir
-        : path.join(boopRoot, 'capabilities', capabilityName);
-    const filesToCopy = [];
-    const fileConflicts = [];
-    // Skills files
-    const skillsDir = boopkit?.skillsDir
-        ? path.join(capDir, boopkit.skillsDir)
-        : path.join(capDir, 'skills');
-    if (fs.existsSync(skillsDir)) {
-        for (const entry of fs.readdirSync(skillsDir)) {
-            const destPath = path.join(targetDir, 'skills', entry);
-            const relPath = path.join('skills', entry);
-            filesToCopy.push(relPath);
-            if (fs.existsSync(destPath)) {
-                fileConflicts.push(relPath);
-            }
-        }
-    }
-    // Capability files from scaffold/ (package) or files/ (source tree)
-    if (cap.files) {
-        const filesDir = boopkit?.scaffoldDir
-            ? path.join(capDir, boopkit.scaffoldDir)
-            : path.join(capDir, 'files');
-        if (fs.existsSync(filesDir)) {
-            enumerateDir(filesDir, targetDir, filesToCopy, fileConflicts);
-        }
-    }
+    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 fileConflicts = filesToCopy.filter(dest => fs.existsSync(path.join(targetDir, dest)));
     // File conflicts are warnings (skip behavior), not failures
     if (fileConflicts.length > 0) {
         checks.push({
@@ -370,25 +342,3 @@ function planAdd(targetDir, capabilityName) {
     };
     return { manifest, cap, projectManifest, filesToCopy, warnings };
 }
-/**
- * Recursively enumerate files in srcDir and check for conflicts in destDir.
- * Pure read — does not write.
- */
-function enumerateDir(srcDir, destBase, filesToCopy, fileConflicts, baseDir) {
-    const root = baseDir ?? srcDir;
-    const entries = fs.readdirSync(srcDir, { withFileTypes: true });
-    for (const entry of entries) {
-        const srcPath = path.join(srcDir, entry.name);
-        if (entry.isDirectory()) {
-            enumerateDir(srcPath, destBase, filesToCopy, fileConflicts, root);
-        }
-        else {
-            const rel = path.relative(root, srcPath);
-            const destPath = path.join(destBase, rel);
-            filesToCopy.push(rel);
-            if (fs.existsSync(destPath)) {
-                fileConflicts.push(rel);
-            }
-        }
-    }
-}

package/dist/lib/scaffold.d.ts

@@ -45,9 +45,14 @@ export declare function copyCapabilityFiles(targetDir: string, capabilityName: s
  * `.claude/skills/<other>` entries (Claude Code plugins, user-authored skills)
  * are preserved.
  *
+ * Pass `only` to link a subset of what stands in `skills/`. A project's own
+ * `skills/` holds exactly what its capabilities installed, so `boop add` and
+ * `boop init` link all of it; the boop repository mirrors the whole library
+ * there and needs to offer only the part its manifest selects.
+ *
  * Idempotent. Returns the relative paths of symlinks created or already present.
  */
-export declare function linkSkillsToClaude(targetDir: string): string[];
+export declare function linkSkillsToClaude(targetDir: string, only?: Iterable<string>): string[];
 /**
  * Merge dependencies into an existing package.json.
  * Does not overwrite existing dependency versions.
@@ -64,6 +69,12 @@ export declare function linkSkillsToClaude(targetDir: string): string[];
  * 4. '*' (last resort)
  */
 export declare function getBoopkitVersion(packageName: string): string;
+/**
+ * The warning shown when a dependency lands in a project's package.json with no
+ * version range. Written to be actionable by an agent reading it in a
+ * transcript with no other context.
+ */
+export declare function formatUnpinnedDependencyWarning(names: string[]): string;
 export declare function mergePackageJson(targetDir: string, dependencies?: string[], devDependencies?: string[], packages?: Record<string, string>, options?: {
     skipBackup?: boolean;
 }): void;

package/dist/lib/scaffold.js

@@ -42,6 +42,7 @@ exports.hashFile = hashFile;
 exports.copyCapabilityFiles = copyCapabilityFiles;
 exports.linkSkillsToClaude = linkSkillsToClaude;
 exports.getBoopkitVersion = getBoopkitVersion;
+exports.formatUnpinnedDependencyWarning = formatUnpinnedDependencyWarning;
 exports.mergePackageJson = mergePackageJson;
 exports.injectCssImports = injectCssImports;
 exports.collectHooks = collectHooks;
@@ -52,6 +53,7 @@ const handlebars_1 = __importDefault(require("handlebars"));
 const config_1 = require("./config");
 const capability_1 = require("./capability");
 const safe_io_1 = require("./safe-io");
+const install_layout_1 = require("./install-layout");
 /**
  * Render a single Handlebars template string with variables.
  *
@@ -133,65 +135,40 @@ function copyCapabilityFiles(targetDir, capabilityName, searchPaths) {
         const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
         const boopkit = pkgJson.boopkit;
         if (boopkit?.capability) {
-            return copyFromPackage(targetDir, capabilityName, pkgDir, boopkit);
+            return copyFromPackage(targetDir, capabilityName, pkgDir);
         }
     }
     // Fallback to source tree
     return copyFromSourceTree(targetDir, capabilityName);
 }
-function walkDir(dir) {
-    const results = [];
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-        const fullPath = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-            results.push(...walkDir(fullPath));
-        }
-        else {
-            results.push(fullPath);
-        }
-    }
-    return results;
-}
 /**
- * Copy capability files from a package directory.
+ * Copy a capability's placements into the project, skipping anything already there.
+ *
+ * Returns the relative paths this capability owns in the project, and their
+ * hashes. A skill file is reported even when it was skipped — the skill folder
+ * is the capability's regardless of who wrote the bytes — while a skipped
+ * scaffold file is not, because it belongs to whatever put it there first.
  */
-function copyFromPackage(targetDir, capabilityName, pkgDir, boopkit) {
+function copyPlacements(targetDir, placements) {
     const copied = [];
     const fileHashes = {};
-    // Copy skills from package
-    if (boopkit.skillsDir) {
-        const skillsDir = path.join(pkgDir, boopkit.skillsDir);
-        if (fs.existsSync(skillsDir)) {
-            const destSkillsDir = path.join(targetDir, 'skills');
-            (0, safe_io_1.safeCopyDir)(skillsDir, destSkillsDir, { onConflict: 'skip' });
-            const entries = fs.readdirSync(skillsDir);
-            for (const entry of entries) {
-                const srcEntryPath = path.join(skillsDir, entry);
-                if (fs.statSync(srcEntryPath).isDirectory()) {
-                    const files = walkDir(path.join(destSkillsDir, entry));
-                    for (const filePath of files) {
-                        const rel = path.join('skills', entry, path.relative(path.join(destSkillsDir, entry), filePath));
-                        copied.push(rel);
-                        fileHashes[rel] = hashFile(filePath);
-                    }
-                }
-            }
-        }
-    }
-    // Copy scaffold files from package
-    if (boopkit.scaffoldDir) {
-        const scaffoldDir = path.join(pkgDir, boopkit.scaffoldDir);
-        if (fs.existsSync(scaffoldDir)) {
-            const scaffolded = scaffoldCapabilityFiles(targetDir, scaffoldDir);
-            copied.push(...scaffolded);
-            for (const rel of scaffolded) {
-                const destPath = path.join(targetDir, rel);
-                if (fs.existsSync(destPath)) {
-                    fileHashes[rel] = hashFile(destPath);
-                }
-            }
+    for (const placement of placements) {
+        const destPath = path.join(targetDir, placement.dest);
+        const result = (0, safe_io_1.safeCopyFile)(placement.source, destPath, { onConflict: 'skip' });
+        if (!result.copied && placement.kind !== 'skill')
+            continue;
+        copied.push(placement.dest);
+        if (fs.existsSync(destPath)) {
+            fileHashes[placement.dest] = hashFile(destPath);
         }
     }
+    return { copied, fileHashes };
+}
+/**
+ * Copy capability files from a package directory.
+ */
+function copyFromPackage(targetDir, capabilityName, pkgDir) {
+    const { copied, fileHashes } = copyPlacements(targetDir, (0, install_layout_1.capabilityPlacementsFromDir)(pkgDir));
     // Store file hashes and version in .boop/config.json
     if (Object.keys(fileHashes).length > 0) {
         const pkgJson = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8'));
@@ -208,17 +185,27 @@ function copyFromPackage(targetDir, capabilityName, pkgDir, boopkit) {
  * `.claude/skills/<other>` entries (Claude Code plugins, user-authored skills)
  * are preserved.
  *
+ * Pass `only` to link a subset of what stands in `skills/`. A project's own
+ * `skills/` holds exactly what its capabilities installed, so `boop add` and
+ * `boop init` link all of it; the boop repository mirrors the whole library
+ * there and needs to offer only the part its manifest selects.
+ *
  * Idempotent. Returns the relative paths of symlinks created or already present.
  */
-function linkSkillsToClaude(targetDir) {
+function linkSkillsToClaude(targetDir, only) {
     const skillsDir = path.join(targetDir, 'skills');
     if (!fs.existsSync(skillsDir))
         return [];
+    const selected = only === undefined ? null : new Set(only);
     const claudeSkillsDir = path.join(targetDir, '.claude', 'skills');
     fs.mkdirSync(claudeSkillsDir, { recursive: true });
     const linked = [];
     for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
-        if (!entry.isDirectory())
+        // isDirectory() uses lstat semantics, so a symlinked skill folder reads as
+        // neither — and the installed-layout mirror makes every mirrored skill one.
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        if (selected && !selected.has(entry.name))
             continue;
         const linkPath = path.join(claudeSkillsDir, entry.name);
         const target = path.join('..', '..', 'skills', entry.name);
@@ -239,37 +226,7 @@ function linkSkillsToClaude(targetDir) {
  * Copy capability files from the capabilities/ source tree (test fixtures only).
  */
 function copyFromSourceTree(targetDir, capabilityName) {
-    const capDir = path.join((0, config_1.getBoopRoot)(), 'capabilities', capabilityName);
-    if (!fs.existsSync(capDir)) {
-        return [];
-    }
-    const copied = [];
-    // Copy skills directory if present
-    const skillsDir = path.join(capDir, 'skills');
-    if (fs.existsSync(skillsDir)) {
-        const destSkillsDir = path.join(targetDir, 'skills');
-        (0, safe_io_1.safeCopyDir)(skillsDir, destSkillsDir, { onConflict: 'skip' });
-        const entries = fs.readdirSync(skillsDir);
-        for (const entry of entries) {
-            const srcEntryPath = path.join(skillsDir, entry);
-            if (fs.statSync(srcEntryPath).isDirectory()) {
-                const files = walkDir(path.join(destSkillsDir, entry));
-                for (const filePath of files) {
-                    copied.push(path.join('skills', entry, path.relative(path.join(destSkillsDir, entry), filePath)));
-                }
-            }
-        }
-    }
-    // Scaffold files declared in the capability manifest
-    const cap = (0, capability_1.getCapability)(capabilityName);
-    if (cap?.files) {
-        const filesDir = path.join(capDir, 'files');
-        if (fs.existsSync(filesDir)) {
-            const scaffolded = scaffoldCapabilityFiles(targetDir, filesDir);
-            copied.push(...scaffolded);
-        }
-    }
-    return copied;
+    return copyPlacements(targetDir, (0, install_layout_1.capabilityPlacements)(capabilityName)).copied;
 }
 /**
  * Update .boop/config.json with file hashes for a capability.
@@ -298,34 +255,6 @@ function updateCapabilityHashes(targetDir, capabilityName, fileHashes, version)
     config.capabilityMeta[capabilityName] = meta;
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
 }
-/**
- * Copy all files from a capability's files/ directory into the target project.
- * Preserves directory structure. Does not overwrite existing files.
- */
-function scaffoldCapabilityFiles(targetDir, filesDir) {
-    const copied = [];
-    function processDir(srcDir, destDir) {
-        if (!fs.existsSync(destDir)) {
-            fs.mkdirSync(destDir, { recursive: true });
-        }
-        const entries = fs.readdirSync(srcDir, { withFileTypes: true });
-        for (const entry of entries) {
-            const srcPath = path.join(srcDir, entry.name);
-            const destPath = path.join(destDir, entry.name);
-            if (entry.isDirectory()) {
-                processDir(srcPath, destPath);
-            }
-            else {
-                if (!fs.existsSync(destPath)) {
-                    fs.copyFileSync(srcPath, destPath);
-                    copied.push(path.relative(targetDir, destPath));
-                }
-            }
-        }
-    }
-    processDir(filesDir, targetDir);
-    return copied;
-}
 /**
  * Merge dependencies into an existing package.json.
  * Does not overwrite existing dependency versions.
@@ -377,6 +306,23 @@ function getBoopkitVersion(packageName) {
     }
     return '*';
 }
+/**
+ * Parse a dependency string like "express@^5" or "@prisma/client@^6" into
+ * name + version.
+ *
+ * A bare name still yields `'*'` rather than throwing. That fallback is for
+ * capabilities boop did not write — a third-party or locally authored manifest
+ * should scaffold rather than abort an install halfway through — but for a
+ * capability that ships with boop a bare name is a defect, not a shorthand.
+ * `'*'` hands a new project whatever major shipped most recently, which is how
+ * a scaffold ended up on TypeScript 6 while boop ran its own suite on 5.9.3.
+ *
+ * So the fallback stays and gets loud instead: `mergePackageJson` warns about
+ * every unpinned range it writes, and
+ * `tests/lib/capability-contracts.test.ts` fails when one of boop's own
+ * manifests or profiles declares a bare name, which is where the regression
+ * actually gets caught.
+ */
 function parseDep(dep) {
     // Handle scoped packages: @scope/name@version
     const match = dep.match(/^(@[^@/]+\/[^@]+)@(.+)$/) || dep.match(/^([^@]+)@(.+)$/);
@@ -385,12 +331,42 @@ function parseDep(dep) {
     }
     return { name: dep, version: '*' };
 }
+/**
+ * The warning shown when a dependency lands in a project's package.json with no
+ * version range. Written to be actionable by an agent reading it in a
+ * transcript with no other context.
+ */
+function formatUnpinnedDependencyWarning(names) {
+    if (names.length === 0)
+        return '';
+    const lines = [];
+    lines.push(`\x1b[33mWARN\x1b[0m ${names.length === 1 ? 'A dependency was' : `${names.length} dependencies were`} added with no version range:`);
+    for (const name of names) {
+        lines.push(`  ${name}: "*"`);
+    }
+    lines.push('');
+    lines.push('  "*" resolves to whatever major shipped most recently, so two projects');
+    lines.push('  scaffolded a month apart get different toolchains and neither matches the');
+    lines.push('  one boop tests against. Pin the declaration to a caret major — "express@^5"');
+    lines.push('  rather than "express" — in the capability.json or profile that declares it,');
+    lines.push('  then set the range by hand in this project\'s package.json.');
+    return lines.join('\n');
+}
 function mergePackageJson(targetDir, dependencies, devDependencies, packages, options) {
     const pkgPath = path.join(targetDir, 'package.json');
     if (!fs.existsSync(pkgPath)) {
         return;
     }
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    // Names written with no range. Collected on the way through rather than
+    // derived from the declarations, so it also catches getBoopkitVersion falling
+    // all the way through to its own '*'.
+    const unpinned = [];
+    const record = (name, version) => {
+        if (version === '*')
+            unpinned.push(name);
+        return version;
+    };
     if (dependencies) {
         if (!pkg.dependencies)
             pkg.dependencies = {};
@@ -398,10 +374,10 @@ function mergePackageJson(targetDir, dependencies, devDependencies, packages, op
             const { name, version } = parseDep(dep);
             if (!(name in pkg.dependencies)) {
                 if (name.startsWith('@boopkit/')) {
-                    pkg.dependencies[name] = getBoopkitVersion(name);
+                    pkg.dependencies[name] = record(name, getBoopkitVersion(name));
                 }
                 else {
-                    pkg.dependencies[name] = version;
+                    pkg.dependencies[name] = record(name, version);
                 }
             }
         }
@@ -412,7 +388,7 @@ function mergePackageJson(targetDir, dependencies, devDependencies, packages, op
         for (const dep of devDependencies) {
             const { name, version } = parseDep(dep);
             if (!(name in pkg.devDependencies)) {
-                pkg.devDependencies[name] = version;
+                pkg.devDependencies[name] = record(name, version);
             }
         }
     }
@@ -421,13 +397,16 @@ function mergePackageJson(targetDir, dependencies, devDependencies, packages, op
             pkg.dependencies = {};
         for (const [name, version] of Object.entries(packages)) {
             if (!(name in pkg.dependencies)) {
-                pkg.dependencies[name] = version;
+                pkg.dependencies[name] = record(name, version);
             }
         }
     }
     if (!options?.skipBackup)
         (0, safe_io_1.createBackup)(pkgPath);
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+    if (unpinned.length > 0) {
+        console.warn(formatUnpinnedDependencyWarning(unpinned));
+    }
 }
 /**
  * Scan the styles/ directory for CSS partials and inject @import lines