@boopkit/cli 0.1.0

package/dist/lib/scaffold.js

@@ -0,0 +1,548 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTemplate = renderTemplate;
+exports.scaffoldKernel = scaffoldKernel;
+exports.hashFile = hashFile;
+exports.copyCapabilityFiles = copyCapabilityFiles;
+exports.getBoopkitVersion = getBoopkitVersion;
+exports.mergePackageJson = mergePackageJson;
+exports.injectCssImports = injectCssImports;
+exports.collectHooks = collectHooks;
+exports.generateSkillsIndex = generateSkillsIndex;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const handlebars_1 = __importDefault(require("handlebars"));
+const config_1 = require("./config");
+const capability_1 = require("./capability");
+const safe_io_1 = require("./safe-io");
+/**
+ * Render a single Handlebars template string with variables.
+ *
+ * TRUST BOUNDARY: noEscape is intentional — template variables (hook code,
+ * import statements, etc.) contain raw code that must not be HTML-escaped.
+ * This is safe as long as all capability manifests are first-party/trusted.
+ * If third-party capabilities are ever supported, hook code from manifests
+ * must be sanitized or sandboxed before reaching this function. See also
+ * collectHooks(), which passes manifest hook code through as-is.
+ */
+function renderTemplate(templateContent, variables) {
+    const compiled = handlebars_1.default.compile(templateContent, { noEscape: true });
+    return compiled(variables);
+}
+/**
+ * Get the path to the kernel templates directory.
+ */
+function getTemplatesDir() {
+    return path.join((0, config_1.getBoopRoot)(), 'src', 'templates', 'kernel');
+}
+/**
+ * Copy and render all kernel templates into a target directory.
+ * Creates directories as needed. Does not overwrite existing files
+ * unless overwrite is true.
+ */
+function scaffoldKernel(targetDir, variables, overwrite = false) {
+    const templatesDir = getTemplatesDir();
+    const written = [];
+    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);
+            if (entry.isDirectory()) {
+                processDir(srcPath, path.join(destDir, entry.name));
+            }
+            else {
+                // Strip .hbs extension for output filename
+                const destName = entry.name.endsWith('.hbs')
+                    ? entry.name.slice(0, -4)
+                    : entry.name;
+                const destPath = path.join(destDir, destName);
+                if (!overwrite && fs.existsSync(destPath)) {
+                    continue;
+                }
+                const content = fs.readFileSync(srcPath, 'utf-8');
+                // Only render .hbs files through Handlebars
+                const rendered = entry.name.endsWith('.hbs')
+                    ? renderTemplate(content, variables)
+                    : content;
+                fs.writeFileSync(destPath, rendered, 'utf-8');
+                written.push(path.relative(targetDir, destPath));
+            }
+        }
+    }
+    processDir(templatesDir, targetDir);
+    return written;
+}
+/**
+ * Compute SHA-256 hash of a file's content.
+ */
+function hashFile(filePath) {
+    const content = fs.readFileSync(filePath);
+    const hash = crypto.createHash('sha256').update(content).digest('hex');
+    return `sha256:${hash}`;
+}
+/**
+ * Copy capability-specific files into a target project directory.
+ * 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) {
+    const pkgDir = (0, capability_1.getPackageDir)(capabilityName);
+    if (pkgDir) {
+        // Read package.json for boopkit config
+        const pkgJsonPath = path.join(pkgDir, 'package.json');
+        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        const boopkit = pkgJson.boopkit;
+        if (boopkit?.capability) {
+            return copyFromPackage(targetDir, capabilityName, pkgDir, boopkit);
+        }
+    }
+    // Fallback to source tree
+    return copyFromSourceTree(targetDir, capabilityName);
+}
+/**
+ * Copy capability files from a package directory.
+ */
+function copyFromPackage(targetDir, capabilityName, pkgDir, boopkit) {
+    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 destPath = path.join(destSkillsDir, entry);
+                copied.push(path.join('skills', entry));
+                if (fs.existsSync(destPath)) {
+                    fileHashes[path.join('skills', entry)] = hashFile(destPath);
+                }
+            }
+        }
+    }
+    // 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);
+                }
+            }
+        }
+    }
+    // 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'));
+        updateCapabilityHashes(targetDir, capabilityName, fileHashes, pkgJson.version);
+    }
+    return copied;
+}
+/**
+ * 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) {
+            copied.push(path.join('skills', entry));
+        }
+    }
+    // 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;
+}
+/**
+ * Update .boop/config.json with file hashes for a capability.
+ * Upgrades old format (capabilities as string[]) to new format (Record with hashes).
+ */
+function updateCapabilityHashes(targetDir, capabilityName, fileHashes, version) {
+    const configDir = path.join(targetDir, '.boop');
+    const configPath = path.join(configDir, 'config.json');
+    if (!fs.existsSync(configPath)) {
+        console.warn(`⚠ Skipping hash storage for ${capabilityName}: .boop/config.json not found`);
+        return;
+    }
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    // Migrate old format if needed: capabilities was string[], needs to support both
+    // We store hashes in a separate capabilityMeta field to avoid breaking the existing capabilities array
+    if (!config.capabilityMeta) {
+        config.capabilityMeta = {};
+    }
+    const meta = {
+        installedAt: new Date().toISOString(),
+        fileHashes,
+    };
+    if (version) {
+        meta.version = 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.
+ */
+/**
+ * Parse a dependency string like "express" or "@prisma/client@^6" into name + version.
+ */
+/**
+ * Read the version from a @boopkit/ package's package.json and return ^version.
+ * Falls back to '*' if the package.json cannot be read.
+ */
+function getBoopkitVersion(packageName) {
+    const pkgName = packageName.replace(/^@boopkit\//, '');
+    const pkgJsonPath = path.join((0, config_1.getBoopRoot)(), 'packages', pkgName, 'package.json');
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        return `^${pkg.version}`;
+    }
+    catch {
+        return '*';
+    }
+}
+function parseDep(dep) {
+    // Handle scoped packages: @scope/name@version
+    const match = dep.match(/^(@[^@/]+\/[^@]+)@(.+)$/) || dep.match(/^([^@]+)@(.+)$/);
+    if (match) {
+        return { name: match[1], version: match[2] };
+    }
+    return { name: dep, version: '*' };
+}
+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'));
+    if (dependencies) {
+        if (!pkg.dependencies)
+            pkg.dependencies = {};
+        for (const dep of dependencies) {
+            const { name, version } = parseDep(dep);
+            if (!(name in pkg.dependencies)) {
+                if (name.startsWith('@boopkit/')) {
+                    pkg.dependencies[name] = getBoopkitVersion(name);
+                }
+                else {
+                    pkg.dependencies[name] = version;
+                }
+            }
+        }
+    }
+    if (devDependencies) {
+        if (!pkg.devDependencies)
+            pkg.devDependencies = {};
+        for (const dep of devDependencies) {
+            const { name, version } = parseDep(dep);
+            if (!(name in pkg.devDependencies)) {
+                pkg.devDependencies[name] = version;
+            }
+        }
+    }
+    if (packages) {
+        if (!pkg.dependencies)
+            pkg.dependencies = {};
+        for (const [name, version] of Object.entries(packages)) {
+            if (!(name in pkg.dependencies)) {
+                pkg.dependencies[name] = version;
+            }
+        }
+    }
+    if (!options?.skipBackup)
+        (0, safe_io_1.createBackup)(pkgPath);
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Scan the styles/ directory for CSS partials and inject @import lines
+ * into styles/styles.css after the last existing @import line.
+ */
+function injectCssImports(targetDir, cssCapMap, options) {
+    const stylesDir = path.join(targetDir, 'styles');
+    const stylesFile = path.join(stylesDir, 'styles.css');
+    if (!fs.existsSync(stylesFile))
+        return;
+    const partials = fs.readdirSync(stylesDir)
+        .filter(f => f.endsWith('.css') && f !== 'styles.css')
+        .sort();
+    if (partials.length === 0)
+        return;
+    const content = fs.readFileSync(stylesFile, 'utf-8');
+    const importLines = partials.map(f => {
+        const capName = cssCapMap?.[f];
+        const annotation = capName ? `/* @boopkit/cap-${capName} */\n` : '';
+        return `${annotation}@import "./${f}";`;
+    }).join('\n');
+    // Find the last @import line and insert after it
+    const lines = content.split('\n');
+    let lastImportIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trimStart().startsWith('@import ')) {
+            lastImportIdx = i;
+        }
+    }
+    if (lastImportIdx === -1)
+        return;
+    lines.splice(lastImportIdx + 1, 0, importLines);
+    if (!options?.skipBackup)
+        (0, safe_io_1.createBackup)(stylesFile);
+    fs.writeFileSync(stylesFile, lines.join('\n'), 'utf-8');
+}
+/**
+ * Collect hooks from installed capabilities, group by phase, sort by order,
+ * and render into strings suitable for injection into server.ts.hbs.
+ *
+ * TRUST BOUNDARY: Hook code from capability manifests is injected verbatim
+ * into the generated server file — no escaping, validation, or sandboxing.
+ * This is safe while all capabilities are first-party. Before supporting
+ * third-party capabilities, hook code must be validated or sandboxed to
+ * prevent arbitrary code injection into scaffolded projects.
+ */
+function collectHooks(capabilities) {
+    const phases = {
+        imports: [],
+        init: [],
+        preRoutes: [],
+        postRoutes: [],
+    };
+    for (let i = 0; i < capabilities.length; i++) {
+        const cap = capabilities[i];
+        for (const hook of cap.hooks) {
+            phases[hook.phase].push({
+                capName: cap.name,
+                order: hook.order ?? 50,
+                code: hook.code,
+                description: hook.description,
+                installIdx: i,
+            });
+        }
+    }
+    // Sort non-import phases by order, then by install index for tie-breaking
+    for (const phase of ['init', 'preRoutes', 'postRoutes']) {
+        phases[phase].sort((a, b) => a.order - b.order || a.installIdx - b.installIdx);
+    }
+    // Sort imports alphabetically by code
+    phases.imports.sort((a, b) => a.code.localeCompare(b.code));
+    function renderImports() {
+        const marker = '// @boopkit:imports';
+        const entries = phases.imports;
+        if (entries.length === 0)
+            return marker;
+        // Group imports by capability name, preserving first-seen order
+        const groups = new Map();
+        for (const entry of entries) {
+            const lines = entry.code.split('\n').filter(l => l.length > 0);
+            if (!groups.has(entry.capName)) {
+                groups.set(entry.capName, { lines: [], description: entry.description });
+            }
+            groups.get(entry.capName).lines.push(...lines);
+        }
+        const blocks = [];
+        for (const [capName, group] of groups) {
+            const desc = group.description ? ` ${group.description}` : '';
+            blocks.push(`/** @boopkit/cap-${capName}${desc} */\n${group.lines.join('\n')}`);
+        }
+        return blocks.join('\n\n') + '\n' + marker;
+    }
+    function renderPhase(phase) {
+        const marker = `// @boopkit:${phase}`;
+        const entries = phases[phase];
+        if (entries.length === 0)
+            return marker;
+        const rendered = entries.map(entry => {
+            const lines = entry.code.split('\n').filter(l => l.length > 0);
+            const desc = entry.description ? ` ${entry.description}` : '';
+            const comment = `/** @boopkit/cap-${entry.capName} [${entry.order}]${desc} */`;
+            return `${comment}\n${lines.join('\n')}`;
+        }).join('\n\n');
+        return rendered + '\n' + marker;
+    }
+    return {
+        hookImports: renderImports(),
+        hookInit: renderPhase('init'),
+        hookPreRoutes: renderPhase('preRoutes'),
+        hookPostRoutes: renderPhase('postRoutes'),
+    };
+}
+/**
+ * Preamble for generated skills/index.md.
+ * Edit here to change the header text in every generated project.
+ */
+const SKILLS_INDEX_PREAMBLE = [
+    '# About Skills',
+    '## Writing new skills',
+    'When writing a new skill, create a markdown file in this directory using the pattern `<topic>.skill.md`.',
+    'Each skill is a concise set of concrete steps that an AI agent can take to achieve a specific goal or perform a specific task.',
+    'Preface the skill with "When you ... " to help the agent understand when to use it.',
+    '',
+    '## Current skills',
+];
+/**
+ * Category display names for skill file prefixes.
+ * Unknown prefixes get title-cased automatically.
+ */
+const SKILL_CATEGORIES = {
+    code: 'Code',
+    design: 'Design',
+    product: 'Product',
+    proj: 'Project',
+    reqs: 'Requirements and Docs',
+    skills: 'Skills',
+    test: 'Testing',
+    web: 'Web',
+    world: 'World',
+};
+/**
+ * Extract the H1 title and first content line from a skill markdown file.
+ */
+function parseSkillFile(content) {
+    const lines = content.split('\n');
+    let title = '';
+    let description = '';
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!title && trimmed.startsWith('# ')) {
+            title = trimmed.slice(2).trim();
+            continue;
+        }
+        if (title && !description && trimmed.length > 0 && !trimmed.startsWith('#')) {
+            description = trimmed;
+            break;
+        }
+    }
+    return { title: title || 'Untitled', description };
+}
+/**
+ * Generate skills/index.md from the .skill.md files present in the project.
+ * Overwrites any existing index.md.
+ */
+function generateSkillsIndex(targetDir) {
+    const skillsDir = path.join(targetDir, 'skills');
+    if (!fs.existsSync(skillsDir))
+        return;
+    const files = fs.readdirSync(skillsDir)
+        .filter(f => f.endsWith('.skill.md'))
+        .sort();
+    if (files.length === 0)
+        return;
+    const entries = [];
+    for (const filename of files) {
+        const content = fs.readFileSync(path.join(skillsDir, filename), 'utf-8');
+        const { title, description } = parseSkillFile(content);
+        const category = filename.split('.')[0];
+        entries.push({ filename, title, description, category });
+    }
+    // Group by category
+    const grouped = new Map();
+    for (const entry of entries) {
+        const list = grouped.get(entry.category) || [];
+        list.push(entry);
+        grouped.set(entry.category, list);
+    }
+    // Sort categories by display name
+    const sortedCategories = [...grouped.keys()].sort((a, b) => {
+        const nameA = SKILL_CATEGORIES[a] || a;
+        const nameB = SKILL_CATEGORIES[b] || b;
+        return nameA.localeCompare(nameB);
+    });
+    const lines = [...SKILLS_INDEX_PREAMBLE];
+    for (const category of sortedCategories) {
+        const displayName = SKILL_CATEGORIES[category]
+            || category.charAt(0).toUpperCase() + category.slice(1);
+        lines.push(`### ${displayName}`);
+        for (const skill of grouped.get(category)) {
+            const desc = skill.description ? ` - ${skill.description}` : '';
+            lines.push(`- [**${skill.title}**](${skill.filename})${desc}`);
+        }
+        lines.push('');
+    }
+    fs.writeFileSync(path.join(skillsDir, 'index.md'), lines.join('\n'), 'utf-8');
+}

package/dist/lib/update.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Core logic for `boop update` — hash-based scaffold file updating.
+ *
+ * Compares installed scaffold files against their stored hashes to detect
+ * local modifications, then selectively updates from the capability package.
+ */
+import { BoopManifest } from './project';
+export type FileState = 'match' | 'modified' | 'missing';
+export interface FileUpdateAction {
+    /** Relative path from project root */
+    relativePath: string;
+    /** What will happen to this file */
+    action: 'overwrite' | 'skip' | 'add' | 'deprecate';
+    /** Why this action was chosen */
+    reason: string;
+    /** Stored hash from config */
+    storedHash?: string;
+    /** Current on-disk hash */
+    currentHash?: string;
+    /** New hash from package */
+    newHash?: string;
+}
+export interface UpdatePlan {
+    capability: string;
+    targetDir: string;
+    packageDir: string;
+    /** Current version from config (if any) */
+    currentVersion?: string;
+    /** New version from package */
+    newVersion: string;
+    /** Per-file actions */
+    actions: FileUpdateAction[];
+    /** Number of files unchanged in both package and locally */
+    unchangedCount: number;
+    /** True if already up to date */
+    upToDate: boolean;
+}
+export interface UpdateResult {
+    capability: string;
+    overwritten: string[];
+    skipped: string[];
+    added: string[];
+    deprecated: string[];
+    forcedOverwrite: string[];
+    /** Files skipped because they were locally deleted */
+    skippedDeleted: string[];
+    /** Files removed from disk via --prune */
+    pruned: string[];
+    /** Count of files unchanged in both package and locally */
+    unchangedCount: number;
+}
+/**
+ * Compare a file's current hash against a stored hash.
+ */
+export declare function compareFileHash(filePath: string, storedHash: string): FileState;
+/**
+ * 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;
+/**
+ * Execute an update plan, writing files and updating config.
+ * If force is true, overwrites even locally modified files (with backup).
+ */
+export declare function executeUpdatePlan(plan: UpdatePlan, options?: {
+    force?: boolean;
+    restore?: boolean;
+    prune?: boolean;
+}): UpdateResult;
+/**
+ * Format an update result as a human-readable summary line.
+ */
+export declare function formatUpdateSummary(result: UpdateResult): string;