@boopkit/cli 0.8.0 → 0.8.1

package/dist/commands/update.js

@@ -40,14 +40,18 @@ const child_process_1 = require("child_process");
 const project_1 = require("../lib/project");
 const capability_1 = require("../lib/capability");
 const update_1 = require("../lib/update");
+const moves_1 = require("../lib/moves");
+const capability_2 = require("../lib/capability");
+const preflight_1 = require("../lib/preflight");
+const execute_1 = require("../lib/execute");
 const scaffold_1 = require("../lib/scaffold");
 const stale_scripts_1 = require("../lib/stale-scripts");
 function runUpdate(capabilityName, options) {
     const targetDir = process.cwd();
     // Must be in a boop project
-    const manifest = (0, project_1.readProjectManifest)(targetDir);
+    let manifest = (0, project_1.readProjectManifest)(targetDir);
     if (!manifest) {
-        console.error(`\x1b[31mERR\x1b[0m Not a boop project (no .boop/config.json). Run \`boop init\` first.`);
+        console.error(`\x1b[31mERR\x1b[0m Not a boop project (no .boop/config.json). Run \`boop init\` in an empty folder, or \`boop add <capability>\` in an existing project, first.`);
         process.exitCode = 1;
         return;
     }
@@ -76,10 +80,44 @@ function runUpdate(capabilityName, options) {
             }
         }
     }
-    // Plan all updates
+    // Step 2: the move pass, against the freshly installed packages. A path a
+    // capability stopped shipping because another ships it now is settled before
+    // either capability is planned (specs/skill-moves.spec.md).
+    let movePlan = (0, moves_1.planMoves)(targetDir, manifest, capsToUpdate);
+    const capabilitiesAdded = [];
+    let moveResults = new Map();
+    if (!options.dryRun) {
+        // Step 3: add each capability split out of an installed one, then settle the moves again with it installed
+        if (movePlan.splitsToAdd.length > 0) {
+            const unaddable = {};
+            for (const split of movePlan.splitsToAdd) {
+                const reason = addSplitCapability(targetDir, split.capability, (0, moves_1.arrivingPaths)(movePlan.moves, split.capability), options);
+                if (reason) {
+                    unaddable[split.capability] = reason;
+                }
+                else {
+                    capabilitiesAdded.push(split);
+                }
+            }
+            manifest = (0, project_1.readProjectManifest)(targetDir);
+            movePlan = (0, moves_1.planMoves)(targetDir, manifest, [...capsToUpdate, ...capabilitiesAdded.map(a => a.capability)], { unaddable });
+        }
+        // Step 4: renames, hash transfers and removals, with the manifest written once
+        moveResults = (0, moves_1.executeMoves)(targetDir, movePlan.moves);
+        manifest = (0, project_1.readProjectManifest)(targetDir);
+    }
+    // Step 5: plan each capability against the manifest the moves wrote. What a
+    // move did not carry out (a hold, a deprecation) belongs to the leaving
+    // capability's plan; in a dry run, every move does, and the receiving
+    // capability leaves the arriving paths to it.
     const plans = [];
-    for (const cap of capsToUpdate) {
-        const plan = (0, update_1.planCapabilityUpdate)(targetDir, cap, manifest);
+    for (const cap of [...capsToUpdate, ...capabilitiesAdded.map(a => a.capability)]) {
+        const pending = movePlan.moves.filter(m => m.fromCapability === cap
+            && (options.dryRun || m.outcome === 'hold' || m.outcome === 'deprecate'));
+        const plan = (0, update_1.planCapabilityUpdate)(targetDir, cap, manifest, {
+            moves: pending.flatMap(moves_1.moveActions),
+            arriving: options.dryRun ? (0, moves_1.arrivingPaths)(movePlan.moves, cap) : [],
+        });
         if (plan) {
             plans.push(plan);
         }
@@ -101,6 +139,9 @@ function runUpdate(capabilityName, options) {
             console.log(JSON.stringify({ capabilities: plans, staleScripts: stale }, null, 2));
             return;
         }
+        for (const split of movePlan.splitsToAdd) {
+            console.log(`\nwould add capability ${split.capability} (split from ${split.splitFrom})`);
+        }
         for (const plan of plans) {
             console.log(`\n${plan.capability}:`);
             // Recording a hash for a file that already holds what boop ships changes nothing the project can see
@@ -115,8 +156,9 @@ function runUpdate(capabilityName, options) {
                 const icon = action.action === 'overwrite' ? '\x1b[32m↑\x1b[0m'
                     : action.action === 'skip' ? '\x1b[33m◐\x1b[0m'
                         : action.action === 'add' ? '\x1b[32m+\x1b[0m'
-                            : action.action === 'migrate' ? '\x1b[36m↗\x1b[0m'
-                                : '\x1b[90m⚠\x1b[0m';
+                            : action.action === 'migrate' || action.action === 'move' ? '\x1b[36m↗\x1b[0m'
+                                : action.action === 'remove' ? '\x1b[31m✕\x1b[0m'
+                                    : '\x1b[90m⚠\x1b[0m';
                 const label = action.action === 'skip' && (action.drift || action.instruction) ? skipLabel(action) : action.reason;
                 console.log(`  ${icon} ${action.relativePath} — ${label}`);
                 if (action.instruction)
@@ -136,28 +178,31 @@ function runUpdate(capabilityName, options) {
     for (const plan of plans) {
         if (plan.upToDate) {
             results.push({
-                capability: plan.capability,
-                overwritten: [],
-                skipped: [],
-                added: [],
-                deprecated: [],
-                forcedOverwrite: [],
-                skippedDeleted: [],
-                pruned: [],
-                migrated: [],
-                scriptsAdded: [],
+                ...emptyResult(plan.capability),
                 scriptsKept: plan.scriptActions.filter(a => a.action === 'keep'),
                 unchangedCount: plan.unchangedCount,
-                instructions: [],
             });
             continue;
         }
         const result = (0, update_1.executeUpdatePlan)(plan, { force: options.force, restore: options.restore, prune: options.prune });
         results.push(result);
     }
+    // Each executed move is reported under the capability the files left
+    for (const moveResult of moveResults.values()) {
+        let result = results.find(r => r.capability === moveResult.capability);
+        if (!result) {
+            result = emptyResult(moveResult.capability);
+            results.push(result);
+        }
+        result.moved.push(...moveResult.moved);
+        result.removed.push(...moveResult.removed);
+        result.instructions.push(...moveResult.instructions);
+    }
     // Refresh .claude/skills/ symlinks for any new skill folders added by this update,
-    // and put back any PROJECT.md the project has deleted
+    // put back any PROJECT.md the project has deleted, and bring each capability's
+    // stored env settings in line with what its package declares now
     if (!options.dryRun) {
+        (0, update_1.refreshCapabilityEnv)(targetDir, plans.map(p => p.capability));
         (0, scaffold_1.linkSkillsToClaude)(targetDir);
         (0, scaffold_1.createSkillProjectFiles)(targetDir);
     }
@@ -173,17 +218,25 @@ function runUpdate(capabilityName, options) {
     if (options.json) {
         console.log(JSON.stringify({
             capabilities: results,
+            capabilitiesAdded,
             staleScripts: remainingStale,
             fixedScripts,
         }, null, 2));
         return;
     }
     console.log(`\n${'─'.repeat(40)}`);
-    results.forEach((result, i) => {
+    for (const added of capabilitiesAdded) {
+        console.log(`added capability ${added.capability} (split from ${added.splitFrom})`);
+    }
+    results.forEach((result) => {
         const summary = (0, update_1.formatUpdateSummary)(result);
         console.log(`${result.capability}: ${summary}`);
-        const actionFor = (f) => plans[i].actions.find(a => a.relativePath === f);
+        const plan = plans.find(p => p.capability === result.capability);
+        const actionFor = (f) => plan?.actions.find(a => a.relativePath === f);
         const instructionFor = (f) => result.instructions.find(entry => entry.relativePath === f)?.instruction;
+        for (const line of moveLines(result, movePlan)) {
+            console.log(line);
+        }
         // Show details for non-trivial updates
         for (const f of result.migrated || []) {
             console.log(`  \x1b[36m↗\x1b[0m ${f} (migrated to folder)`);
@@ -217,9 +270,13 @@ function runUpdate(capabilityName, options) {
             console.log(`  \x1b[32m+\x1b[0m ${f} (new)`);
         }
         for (const f of result.deprecated) {
+            const movedTo = actionFor(f)?.toCapability;
             if (result.pruned?.includes(f)) {
                 console.log(`  \x1b[31m✕\x1b[0m ${f} (pruned, backup saved)`);
             }
+            else if (movedTo) {
+                console.log(`  \x1b[33m⚠\x1b[0m ${f} (deprecated — now ships in ${movedTo}, which this project does not install; use --prune to delete)`);
+            }
             else {
                 console.log(`  \x1b[33m⚠\x1b[0m ${f} (deprecated — removed from package, use --prune to delete)`);
             }
@@ -235,6 +292,81 @@ function runUpdate(capabilityName, options) {
         console.log(`\n${(0, stale_scripts_1.formatStaleScriptWarning)(remainingStale)}`);
     }
 }
+/**
+ * The report's lines for the moves the update carried out from one capability:
+ * each folder or file moved, with where it went, and each skill folder removed
+ * because the capability that ships it now is not installed here.
+ */
+function moveLines(result, movePlan) {
+    const lines = [];
+    const instructionFor = (f) => result.instructions.find(entry => entry.relativePath === f)?.instruction;
+    for (const moved of result.moved) {
+        const planned = movePlan.moves.find(m => m.fromCapability === result.capability && m.from === moved.from);
+        const carried = planned?.projectFileCarried ? '; PROJECT.md carried across' : '';
+        lines.push(`  \x1b[36m↗\x1b[0m ${moved.from} → ${moved.to} (${moved.toCapability}${carried})`);
+        const instruction = instructionFor(moved.from);
+        if (instruction)
+            lines.push(instructionLine(instruction));
+    }
+    for (const removed of result.removed) {
+        const planned = movePlan.moves.find(m => m.fromCapability === result.capability && m.from === removed);
+        const toCapability = planned?.toCapability;
+        const name = path.basename(planned?.to ?? removed);
+        lines.push(`  \x1b[31m✕\x1b[0m ${removed} (removed: now ships in ${toCapability} as ${name}, which this project does not install; \`boop add ${toCapability}\` brings it back)`);
+    }
+    return lines;
+}
+/**
+ * Install a capability split out of an installed one, and add it as `boop add`
+ * would, except that the paths arriving by move are not copied: the move
+ * decides what happens to them. Returns why it could not be added, or null.
+ */
+function addSplitCapability(targetDir, capability, arriving, options) {
+    if (!(0, capability_1.getPackageDir)(capability, [targetDir])) {
+        if (options.skipNpm) {
+            return `its package is not installed, and --skip-npm kept boop from installing it`;
+        }
+        const packageName = (0, capability_2.getCatalogEntry)(capability)?.package ?? `@boopkit/cap-${capability}`;
+        const spec = options.tag ? `${packageName}@${options.tag}` : packageName;
+        try {
+            (0, child_process_1.execSync)(`npm install ${spec}`, { cwd: targetDir, stdio: options.json ? 'pipe' : 'inherit' });
+        }
+        catch {
+            return `npm install ${spec} failed`;
+        }
+    }
+    try {
+        const { manifest } = (0, preflight_1.planAdd)(targetDir, capability, { excludePaths: arriving });
+        (0, execute_1.executeManifest)(manifest, { install: !options.skipNpm });
+        return null;
+    }
+    catch (err) {
+        if (err instanceof preflight_1.PreflightError) {
+            return err.checks.filter(c => !c.passed).map(c => c.message).join('; ');
+        }
+        throw err;
+    }
+}
+function emptyResult(capability) {
+    return {
+        capability,
+        overwritten: [],
+        skipped: [],
+        added: [],
+        deprecated: [],
+        forcedOverwrite: [],
+        skippedDeleted: [],
+        pruned: [],
+        migrated: [],
+        scriptsAdded: [],
+        scriptsKept: [],
+        unchangedCount: 0,
+        instructions: [],
+        moved: [],
+        removed: [],
+        movesWaiting: [],
+    };
+}
 /**
  * How the report shows the npm scripts a capability declares: an added one reads
  * like a new file, and a kept one shows the command the capability ships, so a
@@ -265,6 +397,10 @@ function isEditDoingItsJob(action) {
 }
 /** What the report says happened to a file the update skipped */
 function skipLabel(action) {
+    if (action?.movedTo) {
+        const as = action.movedTo.endsWith('/') ? ` as ${path.basename(action.movedTo)}` : '';
+        return `moved to ${action.toCapability}${as}, waiting`;
+    }
     if (action?.drift === 'project-only')
         return 'edited here, skipped';
     if (action?.drift === 'both-changed') {

package/dist/lib/capability.js

@@ -105,8 +105,11 @@ function getCapabilityFromPackage(name, searchPaths) {
     const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
     if (!pkgJson.boopkit?.capability)
         return null;
+    // A capability ships as the package it sits in, so its package.json name is
+    // the package when capability.json does not say. Five skill capabilities
+    // never said, and `boop add` then never made them a project dependency.
     const capJson = JSON.parse(fs.readFileSync(capJsonPath, 'utf-8'));
-    return capJson;
+    return { ...capJson, package: capJson.package ?? pkgJson.name };
 }
 /**
  * Scan node_modules/@boopkit/cap-* to find a package whose capability.json

package/dist/lib/execute.js

@@ -62,7 +62,7 @@ function executeManifest(manifest, options = {}) {
     // Back up each mutable target file once before executing any tasks
     const backedUp = new Set();
     for (const task of manifest.tasks) {
-        if (task.op === 'copy-files' || task.op === 'run-command')
+        if (task.op === 'copy-files' || task.op === 'run-command' || task.op === 'install-package')
             continue;
         if (task.target && fs.existsSync(task.target) && !backedUp.has(task.target)) {
             (0, safe_io_1.createBackup)(task.target);
@@ -99,8 +99,25 @@ function executeManifest(manifest, options = {}) {
 function executeTask(task, manifest) {
     const { targetDir, capability: capabilityName } = manifest;
     switch (task.op) {
+        case 'create-package-json': {
+            const data = task.data;
+            fs.writeFileSync(task.target, (0, scaffold_1.renderBasePackageJson)(data.projectName), 'utf-8');
+            break;
+        }
+        case 'create-manifest': {
+            const data = task.data;
+            (0, project_1.writeProjectManifest)(targetDir, data.manifest);
+            break;
+        }
+        case 'install-package': {
+            const data = task.data;
+            console.error(`Running ${data.command}...`);
+            (0, child_process_1.execSync)(data.command, { cwd: targetDir, stdio: 'pipe' });
+            break;
+        }
         case 'copy-files': {
-            (0, scaffold_1.copyCapabilityFiles)(targetDir, capabilityName);
+            const data = task.data;
+            (0, scaffold_1.copyCapabilityFiles)(targetDir, capabilityName, undefined, data.exclude);
             (0, scaffold_1.linkSkillsToClaude)(targetDir);
             (0, scaffold_1.createSkillProjectFiles)(targetDir);
             break;

package/dist/lib/install-layout.d.ts

@@ -52,6 +52,11 @@ export declare function describePlacementOwner(placement: Placement): string;
  * has no need of npm module resolution (and must not require a build).
  */
 export declare function capabilityPlacementsFromDir(pkgDir: string): Placement[];
+/**
+ * Whether a project-relative path is one of `paths`, or lies inside one that
+ * names a folder (ends in `/`).
+ */
+export declare function isUnderAny(relPath: string, paths: string[]): boolean;
 /**
  * Every file a capability ships and where it lands in a project.
  *

package/dist/lib/install-layout.js

@@ -53,6 +53,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PlacementCollisionError = void 0;
 exports.describePlacementOwner = describePlacementOwner;
 exports.capabilityPlacementsFromDir = capabilityPlacementsFromDir;
+exports.isUnderAny = isUnderAny;
 exports.capabilityPlacements = capabilityPlacements;
 exports.profilePlacements = profilePlacements;
 exports.skillDirectoryPlacements = skillDirectoryPlacements;
@@ -160,6 +161,13 @@ function capabilityPlacementsFromDir(pkgDir) {
     }
     return placements;
 }
+/**
+ * Whether a project-relative path is one of `paths`, or lies inside one that
+ * names a folder (ends in `/`).
+ */
+function isUnderAny(relPath, paths) {
+    return paths.some(p => p.endsWith('/') ? relPath.startsWith(p) : relPath === p);
+}
 function isCapabilityPackage(pkgDir) {
     const pkgJsonPath = path.join(pkgDir, 'package.json');
     if (!fs.existsSync(pkgJsonPath))

package/dist/lib/manifest.d.ts

@@ -7,7 +7,7 @@
  * Phase 2 (execute) walks the manifest, performing each operation and
  * updating task status.
  */
-export type ManifestOp = 'copy-files' | 'merge-deps' | 'merge-scripts' | 'link-package' | 'inject-hook' | 'inject-css' | 'set-env' | 'update-manifest' | 'run-command';
+export type ManifestOp = 'create-package-json' | 'create-manifest' | 'install-package' | 'copy-files' | 'merge-deps' | 'merge-scripts' | 'link-package' | 'inject-hook' | 'inject-css' | 'set-env' | 'update-manifest' | 'run-command';
 export type TaskStatus = 'pending' | 'done' | 'failed' | 'skipped';
 export interface ManifestTask {
     op: ManifestOp;

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[];