@boopkit/cli 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI tool to scaffold new projects from boop profiles and capabilities",
   "main": "dist/cli.js",
   "workspaces": [
@@ -11,7 +11,8 @@
   },
   "files": [
     "dist/",
-    "profiles/"
+    "profiles/",
+    "src/templates/"
   ],
   "publishConfig": {
     "access": "public"

package/src/templates/kernel/.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+Read the [AGENTS.md](../AGENTS.md) file and follow those instructions.
+
+Before writing any code, run `boop status` to see what capabilities are configured and what needs setup.

package/src/templates/kernel/.gitignore.hbs

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store
+.boop/*
+!.boop/config.json

package/src/templates/kernel/AGENTS.md.hbs

@@ -0,0 +1,28 @@
+# {{projectName}}
+
+This is a **boop**-managed project. Use boop commands — don't reinvent what boop already provides.
+
+## Getting Started
+
+1. Run `boop status` to see what needs configuration
+2. Follow the setup hints to configure your environment
+3. Run `npm run dev` to start the development server
+
+## How to work in this project
+
+1. **Check skills first.** Before coding, reviewing, testing, or designing, check [skills/index.md](skills/index.md) for a matching skill and follow its process. Do not rely on general knowledge when a project skill exists.
+2. **Use boop for capabilities.** To add features like database, auth, or other infrastructure, run `boop add <capability>` — don't install or wire things manually. Run `boop caps` to see what's available.
+3. **Check project status.** Run `boop status` to see what's configured and what needs attention.
+4. **Run `boop --help`** for the full command list.
+
+## Boop extension model
+
+Read [reference/boop-guide.ref.md](reference/boop-guide.ref.md) to understand how this project's services, controllers, and styles are structured — service tiers, factory patterns, the adoption curve (use → compose → adopt), and CSS extension.
+
+## Project layout
+- `src/` — source code
+- `skills/` — process skills for agents (read `skills/index.md`)
+- `reference/` — architecture and coding standards ("what exists now")
+- `specs/` — design docs and specifications ("future state")
+- `tests/` — `npm test` (Jest)
+- `.boop/` — project manifest (managed by boop)

package/src/templates/kernel/CLAUDE.md.hbs

@@ -0,0 +1,3 @@
+# {{projectName}}
+
+Read [AGENTS.md](AGENTS.md) and follow all instructions there.

package/src/templates/kernel/Procfile.hbs

@@ -0,0 +1 @@
+web: npm start

package/src/templates/kernel/README.md.hbs

@@ -0,0 +1,17 @@
+# {{projectName}}
+
+A project scaffolded with [boop](https://github.com/boop).
+
+## Getting Started
+
+```bash
+npm install
+npm run dev
+```
+
+## Scripts
+
+- `npm start` — Start the application
+- `npm run dev` — Start in development mode
+- `npm run build` — Build the project
+- `npm test` — Run tests

package/src/templates/kernel/package.json.hbs

@@ -0,0 +1,16 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "engines": {
+    "node": "{{nodeVersion}}"
+  },
+  "scripts": {
+    "start": "{{scripts.start}}",
+    "dev": "{{scripts.dev}}",
+    "build": "{{scripts.build}}",
+    "test": "{{scripts.test}}"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/src/templates/kernel/reference/boop-guide.ref.md

@@ -0,0 +1,160 @@
+# Busy Agent's Guide to Boop
+
+Quick orientation for AI agents working in a boop-generated project. Read this before modifying service code, controller logic, or styles.
+
+**Deep dive**: If this project has `reference/application-services.ref.md`, it covers service tiers, factory internals, and controller patterns in full detail.
+
+---
+
+## How Boop Projects Work
+
+Boop projects are built from **capabilities** — each one adds skills, npm packages, scaffolded files, or all three. The developer owns scaffolded files from day one. Packages (`@boopkit/*`) are managed dependencies that can be updated via npm — or adopted into the project when the developer outgrows them.
+
+Key commands:
+- `boop caps` — list available capabilities
+- `boop add <capability>` — add a capability to the project
+- `boop adopt <capability>` — copy package source into the project and take ownership
+- `boop status` — check project configuration and what needs attention
+
+---
+
+## Service Tiers
+
+Application logic is organized into four tiers. Dependency flows downward only.
+
+```
+Developer code          ← project-owned, fully custom
+  → Business services   ← multi-step orchestration (e.g. postNotice)
+    → Data services     ← typed CRUD + lifecycle events (e.g. createNoticeService)
+      → Entity primitives ← createEntityService, createPropertyService (@boopkit/cap-services)
+        → Primitives    ← middleware, DB helpers, validators
+```
+
+| Tier | In package? | npm updatable? | Typical relationship |
+|------|-------------|----------------|---------------------|
+| Primitives | Yes | Yes | Stable utilities — rarely replaced |
+| Data services | Yes | Yes | Long-lived composable building blocks |
+| Business services | Yes | Yes | Use until you outgrow, then adopt |
+| Developer code | No | N/A | Fully owned from the start |
+
+---
+
+## Factory Pattern
+
+Boop services export **factory functions** that return a bag of typed methods — not classes, not singletons.
+
+```typescript
+const noticeService = createNoticeService<MyNoticeInfo>(store);
+const { create, findById, list } = noticeService;  // destructuring is safe
+```
+
+**Generic type params** let you extend the base entity shape. Set the type once at factory creation; type safety flows to every returned method:
+
+```typescript
+interface MyNoticeInfo extends BaseNoticeInfo {
+  priority: 'low' | 'medium' | 'high';
+  tags: string[];
+}
+const noticeService = createNoticeService<MyNoticeInfo>(store);
+// All methods are now typed with MyNoticeInfo
+```
+
+**Lifecycle events** are optional callbacks passed to the factory. When provided, they fire on mutations. When omitted, they're no-ops:
+
+```typescript
+const noticeService = createNoticeService<MyNoticeInfo>(store, {
+  onCreated: async (notice) => { /* publish, log, index, etc. */ },
+});
+```
+
+---
+
+## The Adoption Curve: Use → Compose → Adopt
+
+Every boop service supports three levels of engagement. Move between them as needs evolve.
+
+### 1. Use the box
+Call the high-level method. Accept the defaults.
+```typescript
+const notice = await noticeBoardService.postNotice(input);
+```
+
+### 2. Compose the steps
+Business services expose their sub-operations as public methods. Orchestrate them yourself, inserting custom logic between steps:
+```typescript
+noticeBoardService.validateContent(input);
+const notice = await noticeBoardService.createNotice(input);
+await myCustomApprovalWorkflow(notice);          // your step
+await noticeBoardService.notifySubscribers(notice);
+```
+
+**How to find decomposed operations**: Look at the convenience method's implementation — it calls the individual steps in sequence. Each step is a public method on the same service. JSDoc on each method explains what it does.
+
+### 3. Adopt
+Copy the package source into the project and own it:
+```bash
+boop adopt noticeboard
+```
+
+This copies `@boopkit/cap-noticeboard` source into `src/adopted/cap-noticeboard/`, rewrites all imports, removes the package dependency, and updates the manifest. From here, the developer maintains the code directly.
+
+> **"Adopt" not "eject."** Adoption implies natural maturation — taking ownership of code that served you well.
+
+---
+
+## Controller Handlers
+
+Packages export **individual route handlers** as named functions, plus an optional **router factory**:
+
+**Use the box** — mount the whole router:
+```typescript
+app.use('/noticeboard', createNoticeBoardRouter({ noticeBoardService }));
+```
+
+**Compose the steps** — pick individual handlers, add custom middleware:
+```typescript
+const handlers = createNoticeBoardHandlers({ noticeBoardService });
+app.get('/noticeboard',     handlers.listNotices);
+app.post('/noticeboard',    rateLimit(5), handlers.postNotice);
+app.delete('/noticeboard/:id', requireAdmin, handlers.deleteNotice);
+```
+
+---
+
+## CSS Extension
+
+The project's `styles/styles.css` imports from packages in a layered cascade:
+
+```css
+@import "tailwindcss";                              /* 1. Framework */
+@import "@boopkit/cap-web/styles/theme.css";        /* 2. Design tokens */
+@import "@boopkit/cap-web/styles/base.css";         /* 3. Base styles */
+@import "@boopkit/cap-noticeboard/styles/...";      /* 4. Capability styles */
+
+@theme { --color-brand-600: #059669; }              /* 5. Project overrides */
+.btn-primary { @apply shadow-lg; }                  /* 6. Component overrides */
+```
+
+**Design tokens** (`@theme`) generate Tailwind utilities automatically. Override a token → everything downstream updates.
+
+**Package CSS is npm-updatable.** Boop ships new components that pick up the project's brand colors via tokens. Developers override any class by redeclaring it later in the file — CSS cascade handles precedence.
+
+**The same adoption curve applies**: use the imports → override specific classes → drop the import and own the styles.
+
+---
+
+## Project Structure at a Glance
+
+| Directory | Owned by | Purpose |
+|-----------|----------|---------|
+| `src/services/` | Developer | Service wiring files (bridge factories to ServiceMap) |
+| `src/routes/` | Developer | Route mounting (thin glue over handler sets) |
+| `src/controllers/` | Developer | Project-specific controllers |
+| `src/adopted/` | Developer | Adopted package source (created by `boop adopt`) |
+| `styles/` | Developer | Project CSS (imports from packages + overrides) |
+| `styles/adopted/` | Developer | Adopted package styles |
+| `views/` | Developer | Handlebars templates (layouts, pages, partials) |
+| `node_modules/@boopkit/*` | Package | Managed dependencies (updatable via npm) |
+| `skills/` | Scaffolded | Agent skills (process guidance) |
+| `reference/` | Scaffolded | Architecture docs |
+| `.boop/config.json` | Boop | Project manifest (capabilities, adopted packages) |

package/src/templates/kernel/specs/README.md

@@ -0,0 +1,12 @@
+# Specs
+
+Design documents and specifications for planned features and changes. Specs describe the **future state** — what we intend to build — in contrast to `reference/` which documents the **current state**.
+
+## Workflow
+
+1. Write a spec for a new feature or significant change
+2. Review and approve the spec
+3. Create implementation tasks (in beads) from the approved spec
+4. After shipping, update `reference/` docs to reflect the new reality
+
+Specs remain as a record of design intent even after implementation.

package/src/templates/kernel/src/app.ts.hbs

@@ -0,0 +1,23 @@
+// @boopkit:env
+import express from 'express';
+{{{hookImports}}}
+
+const app = express();
+const PORT = process.env.PORT || {{port}};
+app.locals.projectName = '{{projectName}}';
+
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+{{{hookPreRoutes}}}
+
+{{{hookPostRoutes}}}
+
+export async function boot() {
+  {{{hookInit}}}
+
+  app.listen(PORT, () => {
+    console.log(`{{projectName}} listening on port ${PORT}`);
+  });
+}
+
+export default app;

package/src/templates/kernel/src/server.ts.hbs

@@ -0,0 +1,3 @@
+import { boot } from './app';
+boot();
+

package/src/templates/kernel/tsconfig.json.hbs

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}