@boopkit/cli 0.1.0

package/dist/lib/update.js

@@ -0,0 +1,379 @@
+"use strict";
+/**
+ * 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.
+ */
+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.compareFileHash = compareFileHash;
+exports.planCapabilityUpdate = planCapabilityUpdate;
+exports.executeUpdatePlan = executeUpdatePlan;
+exports.formatUpdateSummary = formatUpdateSummary;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const scaffold_1 = require("./scaffold");
+const capability_1 = require("./capability");
+const project_1 = require("./project");
+const safe_io_1 = require("./safe-io");
+/**
+ * Compare a file's current hash against a stored hash.
+ */
+function compareFileHash(filePath, storedHash) {
+    if (!fs.existsSync(filePath)) {
+        return 'missing';
+    }
+    const currentHash = (0, scaffold_1.hashFile)(filePath);
+    return currentHash === storedHash ? 'match' : 'modified';
+}
+/**
+ * Plan an update for a single capability. Returns null if the capability
+ * is not installed or has no package.
+ */
+function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
+    // Capability must be installed
+    if (!projectManifest.capabilities.includes(capabilityName)) {
+        return null;
+    }
+    // Must have a package
+    const pkgDir = (0, capability_1.getPackageDir)(capabilityName);
+    if (!pkgDir)
+        return null;
+    const pkgJsonPath = path.join(pkgDir, 'package.json');
+    if (!fs.existsSync(pkgJsonPath))
+        return null;
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+    const boopkit = pkgJson.boopkit;
+    if (!boopkit?.capability)
+        return null;
+    const newVersion = pkgJson.version || '0.0.0';
+    const meta = projectManifest.capabilityMeta?.[capabilityName];
+    const storedHashes = meta?.fileHashes || {};
+    const actions = [];
+    let unchangedCount = 0;
+    // Collect files from package scaffold dir
+    const packageFiles = new Map(); // relPath → absolute source path
+    if (boopkit.scaffoldDir) {
+        const scaffoldDir = path.join(pkgDir, boopkit.scaffoldDir);
+        if (fs.existsSync(scaffoldDir)) {
+            collectFiles(scaffoldDir, scaffoldDir, packageFiles);
+        }
+    }
+    // Collect files from package skills dir
+    if (boopkit.skillsDir) {
+        const skillsDir = path.join(pkgDir, boopkit.skillsDir);
+        if (fs.existsSync(skillsDir)) {
+            const entries = fs.readdirSync(skillsDir);
+            for (const entry of entries) {
+                const srcPath = path.join(skillsDir, entry);
+                if (fs.statSync(srcPath).isFile()) {
+                    packageFiles.set(path.join('skills', entry), srcPath);
+                }
+            }
+        }
+    }
+    // For each file in the package, determine action
+    for (const [relPath, srcPath] of packageFiles) {
+        const destPath = path.join(targetDir, relPath);
+        const storedHash = storedHashes[relPath];
+        const newHash = (0, scaffold_1.hashFile)(srcPath);
+        if (!storedHash) {
+            // New file — not in stored hashes
+            if (fs.existsSync(destPath)) {
+                // File exists but wasn't tracked — treat as modified (skip)
+                actions.push({
+                    relativePath: relPath,
+                    action: 'skip',
+                    reason: 'File exists but has no stored hash (untracked)',
+                    currentHash: (0, scaffold_1.hashFile)(destPath),
+                    newHash,
+                });
+            }
+            else {
+                actions.push({
+                    relativePath: relPath,
+                    action: 'add',
+                    reason: 'New file from package',
+                    newHash,
+                });
+            }
+            continue;
+        }
+        const state = compareFileHash(destPath, storedHash);
+        switch (state) {
+            case 'match':
+                // Unmodified — safe to overwrite
+                if (newHash === storedHash) {
+                    // File hasn't changed in package either — no action needed
+                    unchangedCount++;
+                    continue;
+                }
+                actions.push({
+                    relativePath: relPath,
+                    action: 'overwrite',
+                    reason: 'Unmodified locally, updated in package',
+                    storedHash,
+                    currentHash: storedHash,
+                    newHash,
+                });
+                break;
+            case 'modified':
+                // Locally modified — skip with warning
+                actions.push({
+                    relativePath: relPath,
+                    action: 'skip',
+                    reason: 'Locally modified',
+                    storedHash,
+                    currentHash: (0, scaffold_1.hashFile)(destPath),
+                    newHash,
+                });
+                break;
+            case 'missing':
+                // File was deleted locally — respect user's deletion, skip by default
+                actions.push({
+                    relativePath: relPath,
+                    action: 'skip',
+                    reason: 'Locally deleted',
+                    storedHash,
+                    newHash,
+                });
+                break;
+        }
+    }
+    // Check for files removed from package (in stored hashes but not in package)
+    for (const relPath of Object.keys(storedHashes)) {
+        if (!packageFiles.has(relPath)) {
+            actions.push({
+                relativePath: relPath,
+                action: 'deprecate',
+                reason: 'Removed from package, leaving in place',
+                storedHash: storedHashes[relPath],
+            });
+        }
+    }
+    const upToDate = actions.length === 0;
+    return {
+        capability: capabilityName,
+        targetDir,
+        packageDir: pkgDir,
+        currentVersion: meta?.version,
+        newVersion,
+        actions,
+        unchangedCount,
+        upToDate,
+    };
+}
+/**
+ * Execute an update plan, writing files and updating config.
+ * If force is true, overwrites even locally modified files (with backup).
+ */
+function executeUpdatePlan(plan, options = {}) {
+    const result = {
+        capability: plan.capability,
+        overwritten: [],
+        skipped: [],
+        added: [],
+        deprecated: [],
+        forcedOverwrite: [],
+        skippedDeleted: [],
+        pruned: [],
+        unchangedCount: plan.unchangedCount,
+    };
+    const pkgJson = JSON.parse(fs.readFileSync(path.join(plan.packageDir, 'package.json'), 'utf-8'));
+    const boopkit = pkgJson.boopkit;
+    const newHashes = {};
+    // Start with existing hashes
+    const manifest = (0, project_1.readProjectManifest)(plan.targetDir);
+    if (manifest?.capabilityMeta?.[plan.capability]) {
+        Object.assign(newHashes, manifest.capabilityMeta[plan.capability].fileHashes);
+    }
+    for (const action of plan.actions) {
+        const destPath = path.join(plan.targetDir, action.relativePath);
+        switch (action.action) {
+            case 'overwrite': {
+                const srcPath = resolveSourcePath(plan.packageDir, boopkit, action.relativePath);
+                if (srcPath) {
+                    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+                    fs.copyFileSync(srcPath, destPath);
+                    newHashes[action.relativePath] = (0, scaffold_1.hashFile)(destPath);
+                    result.overwritten.push(action.relativePath);
+                }
+                break;
+            }
+            case 'skip': {
+                const isLocallyDeleted = action.reason === 'Locally deleted';
+                if (isLocallyDeleted && options.restore) {
+                    // Restore mode: re-add locally deleted files
+                    const srcPath = resolveSourcePath(plan.packageDir, boopkit, action.relativePath);
+                    if (srcPath) {
+                        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+                        fs.copyFileSync(srcPath, destPath);
+                        newHashes[action.relativePath] = (0, scaffold_1.hashFile)(destPath);
+                        result.added.push(action.relativePath);
+                    }
+                }
+                else if (!isLocallyDeleted && options.force) {
+                    // Force mode: backup and overwrite modified files
+                    const srcPath = resolveSourcePath(plan.packageDir, boopkit, action.relativePath);
+                    if (srcPath) {
+                        if (fs.existsSync(destPath)) {
+                            (0, safe_io_1.createBackup)(destPath);
+                        }
+                        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+                        fs.copyFileSync(srcPath, destPath);
+                        newHashes[action.relativePath] = (0, scaffold_1.hashFile)(destPath);
+                        result.overwritten.push(action.relativePath);
+                        result.forcedOverwrite.push(action.relativePath);
+                        console.warn(`\x1b[33mWARN\x1b[0m Force-overwriting modified file: ${action.relativePath} (backup saved as ${action.relativePath}.bak)`);
+                    }
+                }
+                else {
+                    result.skipped.push(action.relativePath);
+                    if (isLocallyDeleted) {
+                        result.skippedDeleted.push(action.relativePath);
+                    }
+                    // Keep existing hash unchanged
+                }
+                break;
+            }
+            case 'add': {
+                const srcPath = resolveSourcePath(plan.packageDir, boopkit, action.relativePath);
+                if (srcPath) {
+                    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+                    fs.copyFileSync(srcPath, destPath);
+                    newHashes[action.relativePath] = (0, scaffold_1.hashFile)(destPath);
+                    result.added.push(action.relativePath);
+                }
+                break;
+            }
+            case 'deprecate': {
+                result.deprecated.push(action.relativePath);
+                // Remove from hashes since it's no longer in the package
+                delete newHashes[action.relativePath];
+                if (options.prune) {
+                    const filePath = path.join(plan.targetDir, action.relativePath);
+                    if (fs.existsSync(filePath)) {
+                        (0, safe_io_1.createBackup)(filePath);
+                        fs.unlinkSync(filePath);
+                        result.pruned.push(action.relativePath);
+                        console.warn(`\x1b[33mWARN\x1b[0m Pruned deprecated file: ${action.relativePath} (backup saved as ${action.relativePath}.bak)`);
+                    }
+                }
+                break;
+            }
+        }
+    }
+    // Update .boop/config.json
+    if (manifest) {
+        if (!manifest.capabilityMeta) {
+            manifest.capabilityMeta = {};
+        }
+        manifest.capabilityMeta[plan.capability] = {
+            installedAt: new Date().toISOString(),
+            version: plan.newVersion,
+            fileHashes: newHashes,
+        };
+        (0, project_1.writeProjectManifest)(plan.targetDir, manifest);
+    }
+    return result;
+}
+/**
+ * Resolve the source path for a relative file path from the package.
+ */
+function resolveSourcePath(pkgDir, boopkit, relativePath) {
+    // Skills are stored as skills/<filename> in relPath
+    if (relativePath.startsWith('skills/') && boopkit.skillsDir) {
+        const filename = relativePath.slice('skills/'.length);
+        const srcPath = path.join(pkgDir, boopkit.skillsDir, filename);
+        return fs.existsSync(srcPath) ? srcPath : null;
+    }
+    // Scaffold files
+    if (boopkit.scaffoldDir) {
+        const srcPath = path.join(pkgDir, boopkit.scaffoldDir, relativePath);
+        return fs.existsSync(srcPath) ? srcPath : null;
+    }
+    return null;
+}
+/**
+ * Recursively collect files from a directory into a map of relPath → absPath.
+ */
+function collectFiles(baseDir, dir, result) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            collectFiles(baseDir, fullPath, result);
+        }
+        else {
+            const relPath = path.relative(baseDir, fullPath);
+            result.set(relPath, fullPath);
+        }
+    }
+}
+/**
+ * Format an update result as a human-readable summary line.
+ */
+function formatUpdateSummary(result) {
+    const parts = [];
+    const normalOverwrites = result.overwritten.length - result.forcedOverwrite.length;
+    if (normalOverwrites > 0) {
+        parts.push(`Updated ${normalOverwrites} file${normalOverwrites === 1 ? '' : 's'}`);
+    }
+    if (result.forcedOverwrite.length > 0) {
+        parts.push(`force-overwrote ${result.forcedOverwrite.length} modified file${result.forcedOverwrite.length === 1 ? '' : 's'}`);
+    }
+    const skippedModified = result.skipped.length - (result.skippedDeleted?.length || 0);
+    if (skippedModified > 0) {
+        parts.push(`skipped ${skippedModified} (locally modified)`);
+    }
+    if (result.skippedDeleted && result.skippedDeleted.length > 0) {
+        parts.push(`skipped ${result.skippedDeleted.length} (locally deleted)`);
+    }
+    if (result.added.length > 0) {
+        parts.push(`added ${result.added.length} new file${result.added.length === 1 ? '' : 's'}`);
+    }
+    if (result.pruned && result.pruned.length > 0) {
+        parts.push(`pruned ${result.pruned.length} deprecated file${result.pruned.length === 1 ? '' : 's'}`);
+    }
+    const unpruned = result.deprecated.length - (result.pruned?.length || 0);
+    if (unpruned > 0) {
+        parts.push(`${unpruned} deprecated (left in place)`);
+    }
+    if (result.unchangedCount > 0) {
+        parts.push(`${result.unchangedCount} unchanged`);
+    }
+    return parts.length > 0 ? parts.join(', ') : 'Already up to date';
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@boopkit/cli",
+  "version": "0.1.0",
+  "description": "CLI tool to scaffold new projects from boop profiles and capabilities",
+  "main": "dist/cli.js",
+  "workspaces": [
+    "packages/*"
+  ],
+  "bin": {
+    "boop": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "profiles/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "test": "jest"
+  },
+  "keywords": [],
+  "license": "ISC",
+  "dependencies": {
+    "bcryptjs": "^3.0.3",
+    "commander": "^14.0.3",
+    "gray-matter": "^4.0.3",
+    "handlebars": "^4.7.8"
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.5.0",
+    "@types/supertest": "^7.2.0",
+    "cookie-parser": "^1.4.7",
+    "jest": "^30.3.0",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.6",
+    "tsx": "^4.19.4",
+    "typescript": "^5.9.3"
+  }
+}

package/profiles/web-app/profile.md

@@ -0,0 +1,113 @@
+---
+name: web-app
+description: Full-stack web application (Express + Handlebars + Tailwind)
+defaultCapabilities:
+  # Application
+  - web
+  - api
+  - services
+  - database
+  # Development
+  - coding
+  - testing
+  - project-mgmt
+  - product-design
+  - skills
+  # Demo
+  - hello
+kernel:
+  runtime: node
+  languages:
+    - typescript
+  deploy: heroku
+  port: 3000
+  nodeVersion: ">=24.0.0"
+  dependencies: []
+  devDependencies:
+    - typescript
+    - tsx
+    - nodemon
+    - "@types/express"
+    - "@types/node"
+  scripts:
+    start: "tsx src/server.ts"
+    dev: "nodemon --exec tsx src/server.ts"
+    build: "tsc"
+    test: "jest --runInBand"
+---
+
+# Web App Profile
+
+A full-stack web application built on Express, server-rendered with Handlebars, styled with Tailwind CSS, and backed by PostgreSQL via Prisma ORM. Designed for rapid product experiments that deploy to Heroku.
+
+## What You Get
+
+### Multi-Process Architecture
+The kernel scaffolds the web process entry point:
+
+- **Web** (`src/server.ts`) — Express app serving the UI and API on port 3000
+
+As your application grows, the architecture supports additional Heroku process types for async work:
+
+- **Worker** — Background message queue consumer for async tasks
+- **Scheduler** — Cron-based job publisher
+
+These are not scaffolded by default. See `reference/message-queue-patterns.ref.md` for the documented patterns when you're ready to add async processing.
+
+### Application Layers
+
+| Layer | Location | Responsibility |
+|-------|----------|----------------|
+| **Controllers** | `src/controllers/` | Protocol-specific request handlers (HTTP routes, MQ messages, CLI). Dispatch commands, no business logic. |
+| **Services** | `src/services/` | Protocol-agnostic business logic and domain operations. Auto-discovered from `*.service.ts` files. |
+| **Data Access** | `src/db/` | Prisma ORM models, migrations, and generated client. |
+| **Config** | `src/config/` | Environment-specific configuration (database, logging, runtime settings). |
+| **Middleware** | `src/middleware/` | Express middleware (auth, error handling, request parsing). |
+| **Utils** | `src/utils/` | Shared utility functions. |
+
+### TypeScript Setup
+- Path aliases (`@config/*`, `@db/*`, `@services/*`, `@controllers/*`, `@middleware/*`, `@utils/*`)
+- Transpile-only in dev and production for fast startup
+- Strict mode with custom type roots
+
+### Deployment
+- Heroku with Procfile-based process management
+- `release` phase for database migrations (`prisma migrate deploy`)
+- Environment-based config via Heroku config vars
+
+## Default Capabilities
+
+The `web-app` profile ships all of the following capabilities by default:
+
+**Application capabilities** — bring project artifacts, dependencies, and skills:
+- **web** — Handlebars templates, Tailwind CSS, and static asset serving
+- **api** — Express routes, controllers, and middleware for building REST APIs
+- **services** — Service layer scaffolding, auto-discovery, and design skills
+- **database** — PostgreSQL with Prisma ORM, migrations, and seeding
+
+**Development capabilities** — pure skill bundles that guide agent behavior:
+- **coding** — Development conventions and code style skills
+- **testing** — Jest setup, test utilities, TDD workflow skills
+- **project-mgmt** — Beads issue tracking, planning skills
+- **product-design** — Feature requirements, design thinking skills
+- **skills** — Skill authoring and maintenance
+
+**Demo:**
+- **hello** — Minimal demo capability to validate the pipeline
+
+Additional capabilities can be added post-init with `boop add`.
+
+## Optional Add-ons
+
+These capabilities are not included by default but can be added to a web-app project:
+
+- **users-and-accounts** — User management, authentication, and account settings. Add with `boop add users-and-accounts`.
+- **noticeboard** — A richer reference demo showcasing the full service-layer pattern. Add with `boop add noticeboard`.
+
+## Reference & Skills
+
+This profile ships with reference docs and skill files tuned for this stack:
+
+- `reference/architecture.ref.md` — System architecture and layer responsibilities
+- `reference/message-queue-patterns.ref.md` — Async processing patterns
+- `skills/` — Development, testing, design, and planning skills for the web-app stack

package/profiles/web-app/reference/architecture.ref.md

@@ -0,0 +1,65 @@
+# Architecture
+There are multiple 'stacks' at play in the ecosystem:
+## This Project
+A full-stack web application deployed to Heroku.
+
+
+## Multi-Process System
+The application starts with a single web process (see `Procfile`):
+
+1. **Web Server** (`src/server.ts`) - Express app on port 3000
+   - Main web interface and Core API
+   - Handles dashboards, authentication, content serving
+
+As the application grows, the architecture supports additional Heroku process types for async work:
+
+2. **Worker** (`src/worker.ts`) - Background message queue consumer
+   - Processes async tasks: long running content generation
+   - Listens to RabbitMQ queues (Heroku CLOUDAMQP)
+
+3. **Scheduler** (`src/scheduler.ts`) - Cron-based task scheduler
+   - Publishes scheduled messages to queues for worker processing
+   - Not typically used in local development (can run with `npm run scheduler -- run-jobs` to trigger immediately)
+
+> **Note:** Worker and scheduler entry points are not scaffolded by `boop init`. Add them when your project needs async processing. See [Message Queue Patterns](./message-queue-patterns.ref.md) for implementation guidance.
+
+
+## Data Layer
+### **PostgreSQL** (Prisma ORM) - Primary data store
+  - Schema: `src/db/prisma/schema.prisma`
+  - Models in `src/db/models/`, Generated client at `@prisma/*`
+  
+> **Context:** This project uses a hybrid relational + document model: key entities are tables with FK relationships; most attributes live in an `info` JSON column with `info_schema` and `revision` for change tracking. 
+
+
+### **ClickHouse** - Analytics/OLAP database
+(Not enabled here yet)
+
+### **Message Queue** (RabbitMQ via Heroku CLOUDAMQP)
+  - Async communication between web/scheduler and workers
+  - Local dev uses dev prefixes (e.g., `mike-`) to isolate queues
+  - A `worker` process must be running to consume messages
+  - A `scheduler` process may be run to publish messages triggering scheduled tasks
+    - In production this is triggered by Heroku
+    - In local dev, run `npm run scheduler -- run-jobs` to trigger immediately (results in messages published to queues)
+  - See [Message Queue Patterns](./message-queue-patterns.ref.md) for consumer modes, buffered batch ACK, and backpressure patterns
+  - **Graceful shutdown**: MQ service owns a coordinated SIGINT handler. Subsystems that need to complete work before AMQP connections close (e.g. S3 batch writer flush + ACK) register via `registerBeforeCloseHook()`. On SIGINT the shutdown sequence is: (1) run all before-close hooks, (2) close all tracked AMQP connections. This prevents race conditions where connections close while messages are still being acknowledged.
+
+### **S3** (Cloud Storage)
+(not yet defined; will be used for asset storage, e.g. images, generated content, etc.)
+
+## Application Layers
+
+### Controllers (`src/controllers/`)
+Protocol-specific command/request handlers. A controller receives commands over a specific transport — HTTP routes, MQ messages, scheduler triggers, CLI invocations — and orchestrates the response by calling services. Controllers own command dispatch (e.g., publishing messages to queues) and protocol-specific concerns (parsing message payloads, sending HTTP responses). They should **not** contain business logic or direct data access.
+
+### Services (`src/services/`)
+Business logic and domain operations. Services are protocol-agnostic — they have no knowledge of HTTP, message queues, or CLI arguments. They expose functions that controllers (or other services) call. Services access the data layer (Prisma, ClickHouse, S3) through configured clients. Services are registered in the `services` bag via `loadServices()` and accessed by name (e.g., `services.batch_processor`).
+
+Some services are low-level and more 'data' oriented or third-party API wrappers (e.g.,  `ClickHouseService`, `StorageService`), while others implement higher-level domain logic or 'app level' logic (e.g., `ContentGenerationService`, `UserManagementService`). Services can call other services, but should avoid circular dependencies. Low level services should not call high-level services to prevent tight coupling between domain logic and data access layers.
+
+
+### Data Access
+  - **Prisma ORM** (`src/db/prisma/`) — PostgreSQL models, migrations, and generated client
+  - **ClickHouse** (`src/ch/`) — Analytics queries via `ClickHouseService`
+  - **S3** — Object storage via `StorageService` with per-feature clients