@boopkit/cli 0.1.0

package/dist/lib/env.js

@@ -0,0 +1,116 @@
+"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.generateEnvFiles = generateEnvFiles;
+exports.readEnvKeys = readEnvKeys;
+exports.readEnvValues = readEnvValues;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const interpolate_1 = require("./interpolate");
+/**
+ * Generate or append to .env and .env.example files from capability env declarations.
+ * - Creates files if they don't exist
+ * - Appends new entries without duplicating existing ones
+ * - .env gets empty values (so the var is unset and capabilities degrade gracefully)
+ * - .env.example gets interpolated defaults (as documentation for the developer)
+ */
+function generateEnvFiles(dir, entries, projectName) {
+    const envPath = path.join(dir, '.env');
+    const examplePath = path.join(dir, '.env.example');
+    const existingEnv = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf-8') : '';
+    const existingExample = fs.existsSync(examplePath) ? fs.readFileSync(examplePath, 'utf-8') : '';
+    const newEnvLines = buildNewEntries(existingEnv, entries, projectName, false);
+    const newExampleLines = buildNewEntries(existingExample, entries, projectName, true);
+    fs.writeFileSync(envPath, existingEnv + newEnvLines, 'utf-8');
+    fs.writeFileSync(examplePath, existingExample + newExampleLines, 'utf-8');
+}
+function buildNewEntries(existingContent, entries, projectName, includeDefaults) {
+    const lines = [];
+    for (const entry of entries) {
+        // Skip if this env var already exists in the file
+        const pattern = new RegExp(`^${escapeRegex(entry.name)}=`, 'm');
+        if (pattern.test(existingContent)) {
+            continue;
+        }
+        const value = includeDefaults && entry.default
+            ? (0, interpolate_1.interpolate)(entry.default, { projectName, username: os.userInfo().username })
+            : '';
+        lines.push(`# ${entry.name} — ${entry.description} (${entry.capability} capability)`);
+        lines.push(`${entry.name}=${value}`);
+    }
+    return lines.length > 0 ? lines.join('\n') + '\n' : '';
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Read a .env file and return the set of variable names that have non-empty values.
+ * Returns an empty set if the file does not exist.
+ */
+function readEnvKeys(filePath) {
+    const values = readEnvValues(filePath);
+    return new Set(values.keys());
+}
+/**
+ * Read a .env file and return a map of variable names to their values.
+ * Only includes variables with non-empty values.
+ * Returns an empty map if the file does not exist.
+ */
+function readEnvValues(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return new Map();
+    }
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const entries = new Map();
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+        // Strip surrounding quotes (single or double)
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key && value) {
+            entries.set(key, value);
+        }
+    }
+    return entries;
+}

package/dist/lib/execute.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Execute phase for `boop add`.
+ *
+ * Walks a pre-flight manifest and performs each operation using the
+ * safe-io utilities. Each task is marked done/failed/skipped as it executes.
+ */
+import { AddManifest, ExecuteResult } from './manifest';
+/**
+ * Execute all tasks in a manifest. Returns the result with per-task status.
+ */
+export declare function executeManifest(manifest: AddManifest, options?: {
+    install?: boolean;
+}): ExecuteResult;
+/**
+ * Save a completed manifest to .boop/logs/ for audit trail.
+ */
+export declare function saveManifestLog(manifest: AddManifest): void;
+/**
+ * Format a manifest as a human-readable summary (for --dry-run output).
+ */
+export declare function formatManifest(manifest: AddManifest): string;

package/dist/lib/execute.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * Execute phase for `boop add`.
+ *
+ * Walks a pre-flight manifest and performs each operation using the
+ * safe-io utilities. Each task is marked done/failed/skipped as it executes.
+ */
+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.executeManifest = executeManifest;
+exports.saveManifestLog = saveManifestLog;
+exports.formatManifest = formatManifest;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const scaffold_1 = require("./scaffold");
+const project_1 = require("./project");
+const env_1 = require("./env");
+const rewire_1 = require("./rewire");
+const safe_io_1 = require("./safe-io");
+/**
+ * Execute all tasks in a manifest. Returns the result with per-task status.
+ */
+function executeManifest(manifest, options = {}) {
+    const shouldInstall = options.install !== false;
+    const completed = [];
+    const failed = [];
+    const skipped = [];
+    // 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')
+            continue;
+        if (task.target && fs.existsSync(task.target) && !backedUp.has(task.target)) {
+            (0, safe_io_1.createBackup)(task.target);
+            backedUp.add(task.target);
+        }
+    }
+    for (const task of manifest.tasks) {
+        // Skip npm install if install=false
+        if (task.op === 'run-command' && !shouldInstall) {
+            task.status = 'skipped';
+            skipped.push(task);
+            continue;
+        }
+        try {
+            executeTask(task, manifest);
+            task.status = 'done';
+            completed.push(task);
+        }
+        catch (err) {
+            task.status = 'failed';
+            failed.push(task);
+            // Log but continue — best effort for remaining tasks
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Warning: Task "${task.detail}" failed: ${message}`);
+        }
+    }
+    return {
+        success: failed.length === 0,
+        completed,
+        failed,
+        skipped,
+    };
+}
+function executeTask(task, manifest) {
+    const { targetDir, capability: capabilityName } = manifest;
+    switch (task.op) {
+        case 'copy-files': {
+            (0, scaffold_1.copyCapabilityFiles)(targetDir, capabilityName);
+            break;
+        }
+        case 'merge-deps': {
+            const data = task.data;
+            (0, scaffold_1.mergePackageJson)(targetDir, data.dependencies, data.devDependencies, undefined, { skipBackup: true });
+            break;
+        }
+        case 'merge-scripts': {
+            const data = task.data;
+            const pkgPath = path.join(targetDir, 'package.json');
+            if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                if (!pkg.scripts)
+                    pkg.scripts = {};
+                for (const [scriptName, scriptDef] of Object.entries(data.scripts)) {
+                    if (!(scriptName in pkg.scripts)) {
+                        pkg.scripts[scriptName] = scriptDef.cmd;
+                    }
+                }
+                fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+            }
+            break;
+        }
+        case 'link-package': {
+            const data = task.data;
+            (0, scaffold_1.mergePackageJson)(targetDir, undefined, undefined, {
+                [data.packageName]: (0, scaffold_1.getBoopkitVersion)(data.packageName),
+            }, { skipBackup: true });
+            break;
+        }
+        case 'set-env': {
+            const data = task.data;
+            (0, env_1.generateEnvFiles)(targetDir, data.entries, data.projectName);
+            break;
+        }
+        case 'inject-hook': {
+            const data = task.data;
+            const appPath = path.join(targetDir, 'src', 'app.ts');
+            const serverPath = path.join(targetDir, 'src', 'server.ts');
+            // New structure: all hooks in app.ts; legacy: all in server.ts
+            const targetFile = fs.existsSync(appPath) ? appPath : serverPath;
+            if (fs.existsSync(targetFile)) {
+                (0, rewire_1.rewireServerFile)(targetFile, capabilityName, data.hooks, {
+                    needsEnv: data.needsEnv,
+                    skipBackup: true,
+                });
+            }
+            break;
+        }
+        case 'inject-css': {
+            const data = task.data;
+            (0, scaffold_1.injectCssImports)(targetDir, data.cssCapMap, { skipBackup: true });
+            break;
+        }
+        case 'generate-skills-index': {
+            (0, scaffold_1.generateSkillsIndex)(targetDir);
+            break;
+        }
+        case 'update-manifest': {
+            const data = task.data;
+            const projectManifest = (0, project_1.readProjectManifest)(targetDir);
+            if (projectManifest) {
+                projectManifest.capabilities.push(capabilityName);
+                if (data.hasEnv && data.envVars) {
+                    if (!projectManifest.capabilityConfig)
+                        projectManifest.capabilityConfig = {};
+                    const envConfig = {};
+                    for (const e of data.envVars) {
+                        envConfig[e.name] = { required: e.required, set: false };
+                    }
+                    const capConfig = { env: envConfig };
+                    projectManifest.capabilityConfig[capabilityName] = capConfig;
+                }
+                (0, project_1.writeProjectManifest)(targetDir, projectManifest);
+            }
+            break;
+        }
+        case 'run-command': {
+            const data = task.data;
+            console.log(`\nRunning ${data.command}...`);
+            (0, child_process_1.execSync)(data.command, { cwd: targetDir, stdio: 'inherit' });
+            break;
+        }
+    }
+}
+/**
+ * Save a completed manifest to .boop/logs/ for audit trail.
+ */
+function saveManifestLog(manifest) {
+    const logsDir = path.join(manifest.targetDir, '.boop', 'logs');
+    if (!fs.existsSync(logsDir)) {
+        fs.mkdirSync(logsDir, { recursive: true });
+    }
+    const timestamp = manifest.timestamp.replace(/[:.]/g, '-');
+    const logPath = path.join(logsDir, `add-${manifest.capability}-${timestamp}.json`);
+    fs.writeFileSync(logPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Format a manifest as a human-readable summary (for --dry-run output).
+ */
+function formatManifest(manifest) {
+    const lines = [];
+    lines.push(`Plan: boop add ${manifest.capability}`);
+    lines.push(`Target: ${manifest.targetDir}`);
+    lines.push('');
+    // Pre-flight checks
+    lines.push('Pre-flight checks:');
+    for (const check of manifest.preflight.checks) {
+        const hasWarning = check.passed && check.message;
+        const icon = !check.passed ? '✗' : hasWarning ? '◐' : '✓';
+        const msg = check.message ? ` — ${check.message}` : '';
+        lines.push(`  ${icon} ${check.name}${msg}`);
+    }
+    lines.push('');
+    // Tasks
+    lines.push(`Tasks (${manifest.tasks.length}):`);
+    for (let i = 0; i < manifest.tasks.length; i++) {
+        const task = manifest.tasks[i];
+        lines.push(`  ${i + 1}. [${task.op}] ${task.detail}`);
+        if (task.source) {
+            lines.push(`     from: ${task.source}`);
+        }
+        lines.push(`     to:   ${task.target}`);
+    }
+    return lines.join('\n');
+}

package/dist/lib/interpolate.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Replace ${name} placeholders in a string with values from a vars map.
+ */
+export declare function interpolate(str: string, vars: Record<string, string>): string;

package/dist/lib/interpolate.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interpolate = interpolate;
+/**
+ * Replace ${name} placeholders in a string with values from a vars map.
+ */
+function interpolate(str, vars) {
+    let result = str;
+    for (const [name, value] of Object.entries(vars)) {
+        result = result.split(`\${${name}}`).join(value);
+    }
+    return result;
+}

package/dist/lib/manifest.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Types for the two-phase pre-flight → execute architecture.
+ *
+ * Phase 1 (pre-flight) builds an AddManifest — a complete, ordered list of
+ * every mutation that `boop add` will perform.
+ *
+ * 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' | 'generate-skills-index' | 'update-manifest' | 'run-command';
+export type TaskStatus = 'pending' | 'done' | 'failed' | 'skipped';
+export interface ManifestTask {
+    op: ManifestOp;
+    /** Where data comes from (capability dir, package dir, etc.) */
+    source?: string;
+    /** What gets modified in the developer's project */
+    target: string;
+    /** Human-readable description of what this task does */
+    detail: string;
+    /** Execution status — starts as 'pending', updated during execute phase */
+    status: TaskStatus;
+    /** Additional data needed for execution (op-specific) */
+    data?: Record<string, unknown>;
+}
+export interface PreflightCheck {
+    name: string;
+    passed: boolean;
+    message?: string;
+}
+export interface PreflightResult {
+    passed: boolean;
+    checks: PreflightCheck[];
+}
+export interface AddManifest {
+    /** Capability being added */
+    capability: string;
+    /** Target project directory */
+    targetDir: string;
+    /** ISO 8601 timestamp when the plan was created */
+    timestamp: string;
+    /** Results of all pre-flight checks */
+    preflight: PreflightResult;
+    /** Ordered list of operations to perform */
+    tasks: ManifestTask[];
+}
+export interface ExecuteResult {
+    success: boolean;
+    /** Tasks that were executed */
+    completed: ManifestTask[];
+    /** Tasks that failed */
+    failed: ManifestTask[];
+    /** Tasks that were skipped */
+    skipped: ManifestTask[];
+}

package/dist/lib/manifest.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Types for the two-phase pre-flight → execute architecture.
+ *
+ * Phase 1 (pre-flight) builds an AddManifest — a complete, ordered list of
+ * every mutation that `boop add` will perform.
+ *
+ * Phase 2 (execute) walks the manifest, performing each operation and
+ * updating task status.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/preflight.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pre-flight planning for `boop add`.
+ *
+ * Reads all inputs, validates everything, and produces a manifest of tasks
+ * to execute — without writing a single file.
+ */
+import { CapabilityMetadata } from './config';
+import { BoopManifest } from './project';
+import { AddManifest, PreflightCheck } from './manifest';
+export declare class PreflightError extends Error {
+    readonly checks: PreflightCheck[];
+    constructor(message: string, checks: PreflightCheck[]);
+}
+export interface PlanAddResult {
+    manifest: AddManifest;
+    /** Resolved capability metadata (for use in output formatting) */
+    cap: CapabilityMetadata;
+    /** Current project manifest (for use in output formatting) */
+    projectManifest: BoopManifest;
+    /** Files that would be copied (relative paths) */
+    filesToCopy: string[];
+    /** Warnings generated during pre-flight (non-fatal) */
+    warnings: string[];
+}
+/**
+ * Plan a `boop add` operation. Reads filesystem, validates everything,
+ * and produces a manifest. Writes nothing.
+ *
+ * Throws PreflightError if any check fails.
+ */
+export declare function planAdd(targetDir: string, capabilityName: string): PlanAddResult;