@boopkit/cli 0.1.0

package/dist/commands/status.d.ts

@@ -0,0 +1,40 @@
+import { BoopManifest } from '../lib/project';
+export interface CapabilityStatusEnvVar {
+    required?: string;
+    set: boolean;
+}
+export interface CapabilityStatus {
+    status: 'configured' | 'setup' | 'pending';
+    type?: string;
+    env?: Record<string, CapabilityStatusEnvVar>;
+    completedSteps?: string[];
+    nextSteps?: string[];
+    optionalSteps?: string[];
+    reachable?: boolean;
+}
+export interface StatusData {
+    name: string;
+    profile: string;
+    capabilities: Record<string, CapabilityStatus>;
+}
+export declare function formatStatus(manifest: BoopManifest): string;
+/**
+ * Compute live status for each capability by cross-referencing
+ * .boop/config.json env declarations with actual .env values.
+ */
+export declare function getStatusData(manifest: BoopManifest, dir: string): StatusData;
+export { parseDbHostPort, checkTcpReachable } from '../lib/db-status';
+/**
+ * Enrich capabilities that have setupChecks with live-detected status.
+ * Mutates data.capabilities in place.
+ */
+export declare function enrichWithSetupChecks(data: StatusData, envValues: Map<string, string>, projectDir: string, projectName: string): Promise<void>;
+/**
+ * Format StatusData into a human-readable display string.
+ * Capabilities are grouped by type (e.g. application, development).
+ */
+export declare function formatEnhancedStatus(data: StatusData): string;
+export interface StatusOptions {
+    json?: boolean;
+}
+export declare function runStatus(options?: StatusOptions): Promise<void>;

package/dist/commands/status.js

@@ -0,0 +1,303 @@
+"use strict";
+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.checkTcpReachable = exports.parseDbHostPort = void 0;
+exports.formatStatus = formatStatus;
+exports.getStatusData = getStatusData;
+exports.enrichWithSetupChecks = enrichWithSetupChecks;
+exports.formatEnhancedStatus = formatEnhancedStatus;
+exports.runStatus = runStatus;
+const path = __importStar(require("path"));
+const project_1 = require("../lib/project");
+const env_1 = require("../lib/env");
+const capability_1 = require("../lib/capability");
+const interpolate_1 = require("../lib/interpolate");
+const db_status_1 = require("../lib/db-status");
+function formatStatus(manifest) {
+    const caps = manifest.capabilities.length > 0
+        ? manifest.capabilities.join(', ')
+        : 'none';
+    const created = manifest.createdAt.split('T')[0];
+    return [
+        `Project:        ${manifest.name}`,
+        `Profile:        ${manifest.profile}`,
+        `Created:        ${created}`,
+        `Boop Version:   ${manifest.boopVersion}`,
+        `Capabilities:   ${caps}`,
+    ].join('\n');
+}
+/**
+ * Compute live status for each capability by cross-referencing
+ * .boop/config.json env declarations with actual .env values.
+ */
+function getStatusData(manifest, dir) {
+    const envPath = path.join(dir, '.env');
+    const setKeys = (0, env_1.readEnvKeys)(envPath);
+    const capabilities = {};
+    for (const capName of manifest.capabilities) {
+        const capConfig = manifest.capabilityConfig?.[capName];
+        const capMeta = (0, capability_1.getCapability)(capName);
+        const capType = capMeta?.type;
+        // Resolve env declarations: prefer manifest capabilityConfig, fall back to capability definition
+        let envEntries;
+        if (capConfig?.env && Object.keys(capConfig.env).length > 0) {
+            envEntries = capConfig.env;
+            // Merge defaults from capability metadata — manifest doesn't persist them
+            if (capMeta?.env) {
+                for (const e of capMeta.env) {
+                    if (envEntries[e.name] && e.default != null && envEntries[e.name].default == null) {
+                        envEntries[e.name].default = e.default;
+                    }
+                }
+            }
+        }
+        else if (capMeta?.env && capMeta.env.length > 0) {
+            // capabilityConfig missing (e.g. from boop init) — synthesize from capability metadata
+            envEntries = {};
+            for (const e of capMeta.env) {
+                envEntries[e.name] = { required: e.required, default: e.default };
+            }
+        }
+        if (!envEntries) {
+            capabilities[capName] = { status: 'configured', type: capType };
+            continue;
+        }
+        const envStatus = {};
+        const nextSteps = [];
+        const optionalSteps = [];
+        let allRequiredSet = true;
+        for (const [varName, decl] of Object.entries(envEntries)) {
+            const hasLiteralDefault = decl.default != null && !decl.default.includes('${');
+            const isSet = setKeys.has(varName) || hasLiteralDefault;
+            envStatus[varName] = { required: decl.required, set: isSet };
+            if (!isSet) {
+                const isRequired = decl.required && decl.required !== 'false';
+                if (isRequired) {
+                    allRequiredSet = false;
+                    // Look for a setupCheck hint for this env var
+                    const envCheck = capMeta?.postInstall?.setupChecks?.find(c => c.type === 'env-set');
+                    const hint = envCheck?.hint ? ` (${envCheck.hint})` : '';
+                    nextSteps.push(`Set ${varName} in .env${hint}`);
+                }
+                else {
+                    optionalSteps.push(`${varName} not set (optional)`);
+                }
+            }
+        }
+        if (allRequiredSet) {
+            // Env vars are set — check if capability has setup checks or postInstall steps
+            const capDef = (0, capability_1.getCapability)(capName);
+            const hasSetupChecks = capDef?.postInstall?.setupChecks?.length;
+            const hasPostInstall = capDef?.postInstall && (capDef.postInstall.steps?.length || capDef.postInstall.verify);
+            if (hasSetupChecks || hasPostInstall) {
+                // Mark as 'setup' — dynamic checks will populate steps during enrichment
+                capabilities[capName] = { status: 'setup', type: capType, env: envStatus, optionalSteps: optionalSteps.length > 0 ? optionalSteps : undefined };
+            }
+            else {
+                capabilities[capName] = { status: 'configured', type: capType, optionalSteps: optionalSteps.length > 0 ? optionalSteps : undefined };
+            }
+        }
+        else {
+            // Enrich next steps with postInstall guidance from capability definition
+            const capDef = (0, capability_1.getCapability)(capName);
+            if (capDef?.postInstall) {
+                const vars = { projectName: manifest.name, capabilityName: capName };
+                const pi = capDef.postInstall;
+                if (pi.prerequisites) {
+                    for (const prereq of pi.prerequisites) {
+                        nextSteps.push((0, interpolate_1.interpolate)(prereq, vars));
+                    }
+                }
+                if (pi.steps) {
+                    for (const step of pi.steps) {
+                        // Skip steps that duplicate the basic "Set X in .env" entries
+                        const interpolated = (0, interpolate_1.interpolate)(step, vars);
+                        const isDuplicate = nextSteps.some((existing) => existing.startsWith('Set ') && interpolated.includes(existing.split(' ')[1]));
+                        if (!isDuplicate) {
+                            nextSteps.push(interpolated);
+                        }
+                    }
+                }
+                if (pi.verify) {
+                    nextSteps.push(`Verify: ${(0, interpolate_1.interpolate)(pi.verify, vars)}`);
+                }
+            }
+            capabilities[capName] = { status: 'pending', type: capType, env: envStatus, nextSteps };
+        }
+    }
+    return { name: manifest.name, profile: manifest.profile, capabilities };
+}
+// Re-export for backward compatibility in tests
+var db_status_2 = require("../lib/db-status");
+Object.defineProperty(exports, "parseDbHostPort", { enumerable: true, get: function () { return db_status_2.parseDbHostPort; } });
+Object.defineProperty(exports, "checkTcpReachable", { enumerable: true, get: function () { return db_status_2.checkTcpReachable; } });
+/**
+ * Enrich capabilities that have setupChecks with live-detected status.
+ * Mutates data.capabilities in place.
+ */
+async function enrichWithSetupChecks(data, envValues, projectDir, projectName) {
+    for (const [capName, cap] of Object.entries(data.capabilities)) {
+        if (cap.status !== 'setup')
+            continue;
+        const capDef = (0, capability_1.getCapability)(capName);
+        const checks = capDef?.postInstall?.setupChecks;
+        if (!checks?.length)
+            continue;
+        // Interpolate labels and hints
+        const vars = { projectName, capabilityName: capName };
+        const interpolatedChecks = checks.map(c => ({
+            type: c.type,
+            label: (0, interpolate_1.interpolate)(c.label, vars),
+            hint: c.hint ? (0, interpolate_1.interpolate)(c.hint, vars) : undefined,
+        }));
+        const steps = await (0, db_status_1.runSetupChecks)(interpolatedChecks, envValues, projectDir, projectName);
+        const completedSteps = steps.filter(s => s.done).map(s => s.label);
+        const nextSteps = steps.filter(s => !s.done).map(s => s.hint ? `${s.label}: ${s.hint}` : s.label);
+        if (nextSteps.length === 0) {
+            cap.status = 'configured';
+            cap.reachable = true;
+            cap.completedSteps = undefined;
+            cap.nextSteps = undefined;
+        }
+        else {
+            cap.completedSteps = completedSteps.length > 0 ? completedSteps : undefined;
+            cap.nextSteps = nextSteps;
+            const serviceStep = steps.find(s => s.label.includes('running') || s.label.includes('service'));
+            if (serviceStep && !serviceStep.done) {
+                cap.reachable = false;
+            }
+        }
+    }
+}
+function formatCapabilityLine(capName, cap) {
+    const lines = [];
+    if (cap.status === 'configured' && cap.reachable !== false) {
+        const reachLabel = cap.reachable === true ? ' (reachable)' : '';
+        lines.push(`    \x1b[32m\u2713\x1b[0m \x1b[32m${capName.padEnd(12)}\x1b[0m configured${reachLabel}`);
+        if (cap.optionalSteps) {
+            for (const step of cap.optionalSteps) {
+                lines.push(`                    \x1b[2m· ${step}\x1b[0m`);
+            }
+        }
+    }
+    else if (cap.status === 'configured' && cap.reachable === false) {
+        lines.push(`    \x1b[33m\u26a0\x1b[0m \x1b[33m${capName.padEnd(12)}\x1b[0m configured but unreachable`);
+        if (cap.nextSteps) {
+            for (const step of cap.nextSteps) {
+                lines.push(`                    → ${step}`);
+            }
+        }
+    }
+    else if (cap.status === 'setup') {
+        lines.push(`    \x1b[36m◐\x1b[0m \x1b[36m${capName.padEnd(12)}\x1b[0m setup incomplete`);
+        if (cap.completedSteps) {
+            for (const step of cap.completedSteps) {
+                lines.push(`                    \x1b[2m✓ ${step}\x1b[0m`);
+            }
+        }
+        if (cap.nextSteps) {
+            for (const step of cap.nextSteps) {
+                lines.push(`                    → ${step}`);
+            }
+        }
+    }
+    else {
+        const unsetVars = cap.env
+            ? Object.entries(cap.env).filter(([, v]) => !v.set).map(([k]) => k)
+            : [];
+        const summary = unsetVars.length > 0 ? `${unsetVars[0]} not set` : 'pending';
+        lines.push(`    \x1b[33m\u26a0\x1b[0m \x1b[33m${capName.padEnd(12)}\x1b[0m ${summary}`);
+        if (cap.nextSteps) {
+            for (const step of cap.nextSteps) {
+                lines.push(`                    → ${step}`);
+            }
+        }
+    }
+    return lines;
+}
+/**
+ * Format StatusData into a human-readable display string.
+ * Capabilities are grouped by type (e.g. application, development).
+ */
+function formatEnhancedStatus(data) {
+    const lines = [`${data.name} status:`];
+    // Group capabilities by type
+    const groups = new Map();
+    for (const [capName, cap] of Object.entries(data.capabilities)) {
+        const type = cap.type || 'other';
+        if (!groups.has(type)) {
+            groups.set(type, []);
+        }
+        groups.get(type).push([capName, cap]);
+    }
+    for (const [type, caps] of groups) {
+        lines.push(`  ${type}:`);
+        for (const [capName, cap] of caps) {
+            lines.push(...formatCapabilityLine(capName, cap));
+        }
+    }
+    return lines.join('\n');
+}
+async function runStatus(options) {
+    const dir = process.cwd();
+    let manifest;
+    try {
+        manifest = (0, project_1.readProjectManifest)(dir);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            console.error('Error: .boop/config.json is corrupt (invalid JSON). Delete it and run `boop init` to recreate.');
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    if (!manifest) {
+        console.error('Not a boop project (no .boop/config.json found). Run `boop init` to create one.');
+        process.exitCode = 1;
+        return;
+    }
+    const data = getStatusData(manifest, dir);
+    // Enrich capabilities that have setupChecks with live status
+    const envPath = path.join(dir, '.env');
+    const envValues = (0, env_1.readEnvValues)(envPath);
+    await enrichWithSetupChecks(data, envValues, dir, manifest.name);
+    if (options?.json) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    else {
+        console.log(formatEnhancedStatus(data));
+    }
+}

package/dist/commands/status.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/status.test.js

@@ -0,0 +1,118 @@
+"use strict";
+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 });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const status_1 = require("../commands/status");
+describe('formatStatus', () => {
+    it('formats manifest fields into a readable status string', () => {
+        const manifest = {
+            name: 'my-saas',
+            profile: 'web-app',
+            boopVersion: '0.1.0',
+            capabilities: ['database', 'api', 'web'],
+            createdAt: '2026-03-19T00:00:00Z',
+        };
+        const output = (0, status_1.formatStatus)(manifest);
+        expect(output).toContain('my-saas');
+        expect(output).toContain('web-app');
+        expect(output).toContain('0.1.0');
+        expect(output).toContain('database');
+        expect(output).toContain('api');
+        expect(output).toContain('web');
+        expect(output).toContain('2026-03-19');
+    });
+    it('handles empty capabilities list', () => {
+        const manifest = {
+            name: 'bare-project',
+            profile: 'web-app',
+            boopVersion: '0.1.0',
+            capabilities: [],
+            createdAt: '2026-03-20T00:00:00Z',
+        };
+        const output = (0, status_1.formatStatus)(manifest);
+        expect(output).toContain('bare-project');
+        expect(output).toContain('none');
+    });
+});
+describe('status command integration', () => {
+    let tmpDir;
+    let originalCwd;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'boop-status-'));
+        originalCwd = process.cwd();
+        process.chdir(tmpDir);
+    });
+    afterEach(() => {
+        process.chdir(originalCwd);
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('prints status when .boop.json exists', () => {
+        const manifest = {
+            name: 'test-project',
+            profile: 'web-app',
+            boopVersion: '0.1.0',
+            capabilities: ['api', 'database'],
+            createdAt: '2026-03-19T12:00:00Z',
+        };
+        fs.writeFileSync(path.join(tmpDir, '.boop.json'), JSON.stringify(manifest));
+        const consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+        const { runStatus } = require('../commands/status');
+        runStatus();
+        expect(consoleSpy).toHaveBeenCalled();
+        const output = consoleSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+        expect(output).toContain('test-project');
+        expect(output).toContain('web-app');
+        consoleSpy.mockRestore();
+    });
+    it('prints error when not in a boop project', () => {
+        const consoleErrorSpy = jest
+            .spyOn(console, 'error')
+            .mockImplementation();
+        const processExitSpy = jest
+            .spyOn(process, 'exit')
+            .mockImplementation(() => undefined);
+        const { runStatus } = require('../commands/status');
+        runStatus();
+        expect(consoleErrorSpy).toHaveBeenCalled();
+        const output = consoleErrorSpy.mock.calls
+            .map((c) => c.join(' '))
+            .join('\n');
+        expect(output).toMatch(/not.*boop project/i);
+        consoleErrorSpy.mockRestore();
+        processExitSpy.mockRestore();
+    });
+});

package/dist/commands/update.d.ts

@@ -0,0 +1,8 @@
+export interface UpdateOptions {
+    dryRun?: boolean;
+    force?: boolean;
+    restore?: boolean;
+    prune?: boolean;
+    json?: boolean;
+}
+export declare function runUpdate(capabilityName: string | undefined, options: UpdateOptions): void;

package/dist/commands/update.js

@@ -0,0 +1,204 @@
+"use strict";
+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.runUpdate = runUpdate;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const project_1 = require("../lib/project");
+const capability_1 = require("../lib/capability");
+const update_1 = require("../lib/update");
+function runUpdate(capabilityName, options) {
+    const targetDir = process.cwd();
+    // Must be in a boop project
+    const 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.`);
+        process.exitCode = 1;
+        return;
+    }
+    // Determine which capabilities to update
+    const capsToUpdate = capabilityName
+        ? [capabilityName]
+        : manifest.capabilities;
+    // Validate specified capability is installed
+    if (capabilityName && !manifest.capabilities.includes(capabilityName)) {
+        console.error(`\x1b[31mERR\x1b[0m Capability "${capabilityName}" is not installed. Installed: ${manifest.capabilities.join(', ')}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Plan all updates
+    const plans = [];
+    for (const cap of capsToUpdate) {
+        const plan = (0, update_1.planCapabilityUpdate)(targetDir, cap, manifest);
+        if (plan) {
+            plans.push(plan);
+        }
+    }
+    if (plans.length === 0) {
+        const diagnosticMessage = diagnoseMissingPlans(capsToUpdate, capabilityName);
+        if (options.json) {
+            console.log(JSON.stringify({ capabilities: [], message: diagnosticMessage }, null, 2));
+        }
+        else {
+            console.log(diagnosticMessage);
+        }
+        return;
+    }
+    // Dry run: show plans and exit
+    if (options.dryRun) {
+        if (options.json) {
+            console.log(JSON.stringify({ capabilities: plans }, null, 2));
+            return;
+        }
+        for (const plan of plans) {
+            console.log(`\n${plan.capability}:`);
+            if (plan.upToDate) {
+                console.log('  Already up to date');
+                continue;
+            }
+            for (const action of plan.actions) {
+                const icon = action.action === 'overwrite' ? '\x1b[32m↑\x1b[0m'
+                    : action.action === 'skip' ? '\x1b[33m◐\x1b[0m'
+                        : action.action === 'add' ? '\x1b[32m+\x1b[0m'
+                            : '\x1b[90m⚠\x1b[0m';
+                console.log(`  ${icon} ${action.relativePath} — ${action.reason}`);
+            }
+        }
+        return;
+    }
+    // Execute updates
+    const results = [];
+    for (const plan of plans) {
+        if (plan.upToDate) {
+            results.push({
+                capability: plan.capability,
+                overwritten: [],
+                skipped: [],
+                added: [],
+                deprecated: [],
+                forcedOverwrite: [],
+                skippedDeleted: [],
+                pruned: [],
+                unchangedCount: plan.unchangedCount,
+            });
+            continue;
+        }
+        const result = (0, update_1.executeUpdatePlan)(plan, { force: options.force, restore: options.restore, prune: options.prune });
+        results.push(result);
+    }
+    // Output
+    if (options.json) {
+        console.log(JSON.stringify({ capabilities: results }, null, 2));
+        return;
+    }
+    console.log(`\n${'─'.repeat(40)}`);
+    for (const result of results) {
+        const summary = (0, update_1.formatUpdateSummary)(result);
+        console.log(`${result.capability}: ${summary}`);
+        // Show details for non-trivial updates
+        for (const f of result.overwritten) {
+            if (result.forcedOverwrite.includes(f)) {
+                console.log(`  \x1b[33m⚠\x1b[0m ${f} (force-overwritten, backup saved)`);
+            }
+            else {
+                console.log(`  \x1b[32m↑\x1b[0m ${f}`);
+            }
+        }
+        for (const f of result.skipped) {
+            if (result.skippedDeleted?.includes(f)) {
+                console.log(`  \x1b[36mℹ\x1b[0m ${f} (locally deleted, skipped — use --restore to re-add)`);
+            }
+            else {
+                console.log(`  \x1b[33m◐\x1b[0m ${f} (locally modified, skipped)`);
+            }
+        }
+        for (const f of result.added) {
+            console.log(`  \x1b[32m+\x1b[0m ${f} (new)`);
+        }
+        for (const f of result.deprecated) {
+            if (result.pruned?.includes(f)) {
+                console.log(`  \x1b[31m✕\x1b[0m ${f} (pruned, backup saved)`);
+            }
+            else {
+                console.log(`  \x1b[33m⚠\x1b[0m ${f} (deprecated — removed from package, use --prune to delete)`);
+            }
+        }
+    }
+}
+/**
+ * Diagnose why no update plans were generated and return a specific message.
+ */
+function diagnoseMissingPlans(capsToUpdate, requestedCap) {
+    if (capsToUpdate.length === 0) {
+        return 'No capabilities installed. Run `boop add <capability>` to install one.';
+    }
+    // Check each capability and collect reasons
+    const noPackage = [];
+    const noBoopkit = [];
+    for (const cap of capsToUpdate) {
+        const pkgDir = (0, capability_1.getPackageDir)(cap);
+        if (!pkgDir) {
+            noPackage.push(cap);
+            continue;
+        }
+        const pkgJsonPath = path.join(pkgDir, 'package.json');
+        if (!fs.existsSync(pkgJsonPath)) {
+            noPackage.push(cap);
+            continue;
+        }
+        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        if (!pkgJson.boopkit?.capability) {
+            noBoopkit.push(cap);
+        }
+    }
+    if (requestedCap) {
+        // Single capability was requested
+        if (noPackage.includes(requestedCap)) {
+            return `Capability "${requestedCap}" is installed but has no package. It may be a local-only capability without updatable scaffold files.`;
+        }
+        if (noBoopkit.includes(requestedCap)) {
+            return `Capability "${requestedCap}" has a package but no boopkit scaffold configuration. Nothing to update.`;
+        }
+        return `No updates available for "${requestedCap}".`;
+    }
+    // All capabilities requested
+    if (noPackage.length === capsToUpdate.length) {
+        return 'All installed capabilities are local-only (no packages found). Nothing to update.';
+    }
+    if (noBoopkit.length + noPackage.length === capsToUpdate.length) {
+        return 'No installed capabilities have updatable scaffold files.';
+    }
+    return 'No capabilities to update.';
+}