@boopkit/cli 0.8.0 → 0.8.2

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).
  */

package/dist/lib/scaffold.d.ts

@@ -31,6 +31,12 @@ export declare function renderTemplate(templateContent: string, variables: Templ
  */
 export declare function getTemplatesDir(profileName: string): string;
 export declare function profileHasTemplates(profileName: string): boolean;
+/**
+ * The minimal package.json the `base` profile ships, rendered for a project.
+ * boop records every capability as an npm package there, so a project without
+ * one (a native iOS app, say) gets this one before its first capability.
+ */
+export declare function renderBasePackageJson(projectName: string): string;
 /**
  * Copy and render every file in a templates directory (the kernel templates
  * by default) into a target directory. Creates directories as needed. Does
@@ -51,7 +57,7 @@ export declare function hashContent(content: Buffer): string;
  * Tries package resolution first (scaffold/ and skills/ dirs), falls back to source tree.
  * Returns list of copied file paths relative to targetDir, and file hashes.
  */
-export declare function copyCapabilityFiles(targetDir: string, capabilityName: string, searchPaths?: string[]): string[];
+export declare function copyCapabilityFiles(targetDir: string, capabilityName: string, searchPaths?: string[], excludePaths?: string[]): string[];
 /**
  * Symlink each skill folder under `<targetDir>/skills/` into
  * `<targetDir>/.claude/skills/` so Claude Code's built-in Skill tool
@@ -66,6 +72,11 @@ export declare function copyCapabilityFiles(targetDir: string, capabilityName: s
  * `boop init` link all of it; the boop repository mirrors the whole library
  * there and needs to offer only the part its manifest selects.
  *
+ * A link left pointing into `skills/` at a folder that no longer stands there
+ * (the project deleted the skill, or a capability stopped shipping it) is
+ * removed, so the links follow the folders. Only symlinks into `skills/` are
+ * pruned; a link the project made to anywhere else is never touched.
+ *
  * Idempotent. Returns the relative paths of symlinks created or already present.
  */
 export declare function linkSkillsToClaude(targetDir: string, only?: Iterable<string>): string[];

package/dist/lib/scaffold.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderTemplate = renderTemplate;
 exports.getTemplatesDir = getTemplatesDir;
 exports.profileHasTemplates = profileHasTemplates;
+exports.renderBasePackageJson = renderBasePackageJson;
 exports.scaffoldKernel = scaffoldKernel;
 exports.hashFile = hashFile;
 exports.hashContent = hashContent;
@@ -97,6 +98,15 @@ function profileHasTemplates(profileName) {
 function getProfileTemplatesDir(profileName) {
     return path.join((0, config_1.getBoopRoot)(), 'profiles', profileName, 'templates');
 }
+/**
+ * The minimal package.json the `base` profile ships, rendered for a project.
+ * boop records every capability as an npm package there, so a project without
+ * one (a native iOS app, say) gets this one before its first capability.
+ */
+function renderBasePackageJson(projectName) {
+    const template = fs.readFileSync(path.join(getProfileTemplatesDir('base'), 'package.json.hbs'), 'utf-8');
+    return renderTemplate(template, { projectName });
+}
 /**
  * Copy and render every file in a templates directory (the kernel templates
  * by default) into a target directory. Creates directories as needed. Does
@@ -156,7 +166,7 @@ function hashContent(content) {
  * Tries package resolution first (scaffold/ and skills/ dirs), falls back to source tree.
  * Returns list of copied file paths relative to targetDir, and file hashes.
  */
-function copyCapabilityFiles(targetDir, capabilityName, searchPaths) {
+function copyCapabilityFiles(targetDir, capabilityName, searchPaths, excludePaths = []) {
     // Default to the project itself, so this resolves the capability to the same
     // package `planAdd` did. Without it a capability that lives only under the
     // project resolved here to nothing, and `boop add` reported every file copied
@@ -168,7 +178,7 @@ 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);
+            return copyFromPackage(targetDir, capabilityName, pkgDir, excludePaths);
         }
     }
     // Fallback to source tree
@@ -200,8 +210,9 @@ function copyPlacements(targetDir, placements) {
 /**
  * Copy capability files from a package directory.
  */
-function copyFromPackage(targetDir, capabilityName, pkgDir) {
-    const { copied, fileHashes } = copyPlacements(targetDir, (0, install_layout_1.capabilityPlacementsFromDir)(pkgDir));
+function copyFromPackage(targetDir, capabilityName, pkgDir, excludePaths) {
+    const placements = (0, install_layout_1.capabilityPlacementsFromDir)(pkgDir).filter(p => !(0, install_layout_1.isUnderAny)(p.dest, excludePaths));
+    const { copied, fileHashes } = copyPlacements(targetDir, placements);
     // 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'));
@@ -223,10 +234,16 @@ function copyFromPackage(targetDir, capabilityName, pkgDir) {
  * `boop init` link all of it; the boop repository mirrors the whole library
  * there and needs to offer only the part its manifest selects.
  *
+ * A link left pointing into `skills/` at a folder that no longer stands there
+ * (the project deleted the skill, or a capability stopped shipping it) is
+ * removed, so the links follow the folders. Only symlinks into `skills/` are
+ * pruned; a link the project made to anywhere else is never touched.
+ *
  * Idempotent. Returns the relative paths of symlinks created or already present.
  */
 function linkSkillsToClaude(targetDir, only) {
     const skillsDir = path.join(targetDir, 'skills');
+    pruneDanglingSkillLinks(targetDir);
     if (!fs.existsSync(skillsDir))
         return [];
     const selected = only === undefined ? null : new Set(only);
@@ -255,6 +272,28 @@ function linkSkillsToClaude(targetDir, only) {
     }
     return linked;
 }
+/**
+ * Remove each symlink in `<targetDir>/.claude/skills/` that points into
+ * `<targetDir>/skills/` at an entry that no longer exists.
+ */
+function pruneDanglingSkillLinks(targetDir) {
+    const skillsDir = path.join(targetDir, 'skills');
+    const claudeSkillsDir = path.join(targetDir, '.claude', 'skills');
+    if (!fs.existsSync(claudeSkillsDir))
+        return;
+    for (const entry of fs.readdirSync(claudeSkillsDir, { withFileTypes: true })) {
+        if (!entry.isSymbolicLink())
+            continue;
+        const linkPath = path.join(claudeSkillsDir, entry.name);
+        const resolved = path.resolve(claudeSkillsDir, fs.readlinkSync(linkPath));
+        if (!resolved.startsWith(skillsDir + path.sep))
+            continue;
+        // lstat, so a skills/ entry that is itself a symlink counts as present.
+        if (fs.lstatSync(resolved, { throwIfNoEntry: false }))
+            continue;
+        fs.unlinkSync(linkPath);
+    }
+}
 /**
  * The names of the skill folders under `<targetDir>/skills/` that boop installed.
  *

package/dist/lib/stale-scripts.js

@@ -65,19 +65,56 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 /** Jest's in-band flag and its single-letter alias. */
 const IN_BAND_FLAGS = new Set(['--runInBand', '--runInBand=true', '-i']);
+/** Shell operators that end one command and start the next. */
+const COMMAND_SEPARATORS = new Set(['&&', '||', ';', '|']);
 /**
- * Does this command invoke Jest? Matched on the token's basename so that `jest`,
- * `npx jest` and `node_modules/.bin/jest` all count, while a command that merely
- * contains the same characters somewhere does not.
+ * Words that run the command after them, so the word that follows (once their
+ * own flags are skipped) is still in command position: `npx jest`, `exec jest`,
+ * `node --expose-gc node_modules/.bin/jest`.
  */
-function invokesJest(tokens) {
-    return tokens.some((token) => {
-        if (token.startsWith('-'))
-            return false;
-        const base = path.basename(token);
-        return base === 'jest' || base === 'jest.js';
+const LAUNCHERS = new Set(['npx', 'exec', 'node', 'cross-env']);
+/**
+ * Keys that cannot be run as scripts by convention. Projects keep explanatory
+ * prose there, and prose about Jest naturally mentions `jest` and `--runInBand`.
+ */
+function isCommentKey(name) {
+    return name.startsWith('_comment') || name.startsWith('//');
+}
+function isJest(token) {
+    const base = path.basename(token);
+    return base === 'jest' || base === 'jest.js';
+}
+/**
+ * Group a command's words by the chained command each belongs to. A separator
+ * glued to the end of a word (`tsc;`) still ends that command.
+ */
+function groupCommands(tokens) {
+    let current = 0;
+    return tokens.map((token) => {
+        if (COMMAND_SEPARATORS.has(token))
+            return current++;
+        const index = current;
+        if (token.endsWith(';'))
+            current++;
+        return index;
     });
 }
+/**
+ * Does this one command run Jest? Only the word in command position counts —
+ * after any `KEY=value` assignments, launchers and the launchers' own flags —
+ * so `jest`, `npx jest` and `node_modules/.bin/jest` match, while `echo jest`
+ * and a command that merely contains the same characters do not.
+ */
+function runsJest(tokens) {
+    for (const token of tokens) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token))
+            continue;
+        if (LAUNCHERS.has(token) || token.startsWith('-'))
+            continue;
+        return isJest(token);
+    }
+    return false;
+}
 /**
  * Pure: given a package.json `scripts` object, return the scripts whose command
  * forces in-band Jest execution and therefore defeats the shipped config.
@@ -87,18 +124,21 @@ function findStaleRunnerScripts(scripts) {
         return [];
     const findings = [];
     for (const [name, command] of Object.entries(scripts)) {
-        if (typeof command !== 'string')
+        if (typeof command !== 'string' || isCommentKey(name))
             continue;
         const tokens = command.split(/\s+/).filter(Boolean);
-        if (!invokesJest(tokens))
-            continue;
-        const flags = tokens.filter((t) => IN_BAND_FLAGS.has(t));
+        const group = groupCommands(tokens);
+        const jestGroups = new Set([...new Set(group)].filter((g) => runsJest(tokens
+            .filter((t, i) => group[i] === g && !COMMAND_SEPARATORS.has(t))
+            .map((t) => t.replace(/;$/, '')))));
+        const offending = (t, i) => jestGroups.has(group[i]) && IN_BAND_FLAGS.has(t);
+        const flags = tokens.filter(offending);
         if (flags.length === 0)
             continue;
         findings.push({
             name,
             command,
-            rewritten: tokens.filter((t) => !IN_BAND_FLAGS.has(t)).join(' '),
+            rewritten: tokens.filter((t, i) => !offending(t, i)).join(' '),
             flags,
         });
     }

package/dist/lib/update.d.ts

@@ -17,7 +17,7 @@ export interface FileUpdateAction {
     /** Relative path from project root */
     relativePath: string;
     /** What will happen to this file */
-    action: 'overwrite' | 'skip' | 'add' | 'deprecate' | 'migrate' | 'record-hash';
+    action: 'overwrite' | 'skip' | 'add' | 'deprecate' | 'migrate' | 'record-hash' | 'move' | 'remove';
     /** Why this action was chosen */
     reason: string;
     /** Stored hash from config */
@@ -38,6 +38,12 @@ export interface FileUpdateAction {
     instruction?: string;
     /** boop's current copy of the file, when the instruction points at it */
     upstreamPath?: string;
+    /** For a path another capability ships now: where it ships */
+    movedTo?: string;
+    /** For a path another capability ships now: that capability */
+    toCapability?: string;
+    /** For the move of a skill folder: whether its PROJECT.md held more than the template */
+    projectFileCarried?: boolean;
 }
 export interface FileInstruction {
     relativePath: string;
@@ -82,6 +88,16 @@ export interface UpdateResult {
     unchangedCount: number;
     /** What to do about the files this update skipped or replaced, where the report says anything */
     instructions: FileInstruction[];
+    /** Paths moved to another capability, by the move pass */
+    moved: {
+        from: string;
+        to: string;
+        toCapability: string;
+    }[];
+    /** Skill folders deleted because another capability ships them now and this project does not install it */
+    removed: string[];
+    /** Moved paths left where they are until the instruction for them is followed */
+    movesWaiting: string[];
 }
 /** The skill that splits a drifted SKILL.md — keep in step with the folder name boop-rm2l.8 gives it */
 export declare const TRIAGE_SKILL = "boop-skills-edit-triage";
@@ -91,11 +107,21 @@ export declare const SKILL_EDITS_INSTRUCTION = "Move each skill's edits into the
  * Compare a file's current hash against a stored hash.
  */
 export declare function compareFileHash(filePath: string, storedHash: string): FileState;
+export interface PlanOptions {
+    /**
+     * The move pass's actions for paths leaving this capability. Each replaces
+     * whatever this planner would plan for the paths it covers; a skip whose
+     * `relativePath` is a folder covers every stored path inside it.
+     */
+    moves?: FileUpdateAction[];
+    /** Paths arriving in this capability by a move not yet carried out, which the move lists instead */
+    arriving?: string[];
+}
 /**
  * Plan an update for a single capability. Returns null if the capability
  * is not installed or has no package.
  */
-export declare function planCapabilityUpdate(targetDir: string, capabilityName: string, projectManifest: BoopManifest): UpdatePlan | null;
+export declare function planCapabilityUpdate(targetDir: string, capabilityName: string, projectManifest: BoopManifest, options?: PlanOptions): UpdatePlan | null;
 /**
  * Execute an update plan, writing files and updating config.
  * If force is true, overwrites even locally modified files (with backup).
@@ -105,6 +131,14 @@ export declare function executeUpdatePlan(plan: UpdatePlan, options?: {
     restore?: boolean;
     prune?: boolean;
 }): UpdateResult;
+/**
+ * Rewrite each capability's stored env record (capabilityConfig[cap].env) from
+ * the env its installed package declares. A variable the package still declares
+ * keeps its `set` flag; one it no longer declares is dropped, and a capability
+ * that declares none loses its record. `boop status` prefers this record over
+ * the package, so a stale one would list a moved variable under both capabilities.
+ */
+export declare function refreshCapabilityEnv(targetDir: string, capabilities: string[]): void;
 /**
  * Count the skills a capability's project copy has edited in SKILL.md, and how
  * many of those boop has changed since — from the same comparison `boop update`