create-kuckit-app 0.4.0 → 0.4.1

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as createProject } from "./create-project-geQBZ0Ru.js";
+import { t as createProject } from "./create-project-CAsuZMK5.js";
 import { program } from "commander";
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";

package/dist/{create-project-geQBZ0Ru.js → create-project-CAsuZMK5.js}

@@ -39,7 +39,8 @@ async function createProject(name, options) {
 	const replacements = {
 		__APP_NAME__: name,
 		__APP_NAME_LOWER__: name.toLowerCase(),
-		__APP_NAME_KEBAB__: name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()
+		__APP_NAME_KEBAB__: name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase(),
+		__APP_TITLE__: name
 	};
 	console.log("  Copying template files...");
 	await copyDir(templateDir, targetDir, replacements);

package/dist/index.js

@@ -1,3 +1,3 @@
-import { t as createProject } from "./create-project-geQBZ0Ru.js";
+import { t as createProject } from "./create-project-CAsuZMK5.js";
 
 export { createProject };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-kuckit-app",
-	"version": "0.4.0",
+	"version": "0.4.1",
 	"description": "Create a new Kuckit application",
 	"type": "module",
 	"license": "MIT",

package/templates/base/.claude/CLAUDE.md

@@ -42,3 +42,86 @@ This is a Kuckit application using Clean Architecture patterns.
 - Adapters: `*.drizzle.ts`
 - Routers: `*.router.ts`
 - Use cases: verb-noun (e.g., `create-item.ts`, `list-items.ts`)
+
+<!-- MCP_AGENT_MAIL_AND_BEADS_SNIPPET_START -->
+
+## MCP Agent Mail: coordination for multi-agent workflows
+
+What it is
+
+- A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources.
+- Provides identities, inbox/outbox, searchable threads, and advisory file reservations, with human-auditable artifacts in Git.
+
+Why it's useful
+
+- Prevents agents from stepping on each other with explicit file reservations (leases) for files/globs.
+- Keeps communication out of your token budget by storing messages in a per-project archive.
+- Offers quick reads (`resource://inbox/...`, `resource://thread/...`) and macros that bundle common flows.
+
+How to use effectively
+
+1. Same repository
+   - Register an identity: call `ensure_project`, then `register_agent` using this repo's absolute path as `project_key`.
+   - Reserve files before you edit: `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)` to signal intent and avoid conflict.
+   - Communicate with threads: use `send_message(..., thread_id="FEAT-123")`; check inbox with `fetch_inbox` and acknowledge with `acknowledge_message`.
+   - Read fast: `resource://inbox/{Agent}?project=<abs-path>&limit=20` or `resource://thread/{id}?project=<abs-path>&include_bodies=true`.
+   - Tip: set `AGENT_NAME` in your environment so the pre-commit guard can block commits that conflict with others' active exclusive file reservations.
+
+2. Across different repos in one project (e.g., Next.js frontend + FastAPI backend)
+   - Option A (single project bus): register both sides under the same `project_key` (shared key/path). Keep reservation patterns specific (e.g., `frontend/**` vs `backend/**`).
+   - Option B (separate projects): each repo has its own `project_key`; use `macro_contact_handshake` or `request_contact`/`respond_contact` to link agents, then message directly. Keep a shared `thread_id` (e.g., ticket key) across repos for clean summaries/audits.
+
+Macros vs granular tools
+
+- Prefer macros when you want speed or are on a smaller model: `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`.
+- Use granular tools when you need control: `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`.
+
+Common pitfalls
+
+- "from_agent not registered": always `register_agent` in the correct `project_key` first.
+- "FILE_RESERVATION_CONFLICT": adjust patterns, wait for expiry, or use a non-exclusive reservation when appropriate.
+- Auth errors: if JWT+JWKS is enabled, include a bearer token with a `kid` that matches server JWKS; static bearer is used only when JWT is disabled.
+
+## Integrating with Beads (dependency-aware task planning)
+
+Beads provides a lightweight, dependency-aware issue database and a CLI (`bd`) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging, audit trail, and file-reservation signals. Project: [steveyegge/beads](https://github.com/steveyegge/beads)
+
+Recommended conventions
+
+- **Single source of truth**: Use **Beads** for task status/priority/dependencies; use **Agent Mail** for conversation, decisions, and attachments (audit).
+- **Shared identifiers**: Use the Beads issue id (e.g., `bd-123`) as the Mail `thread_id` and prefix message subjects with `[bd-123]`.
+- **Reservations**: When starting a `bd-###` task, call `file_reservation_paths(...)` for the affected paths; include the issue id in the `reason` and release on completion.
+
+Typical flow (agents)
+
+1. **Pick ready work** (Beads)
+   - `bd ready --json` → choose one item (highest priority, no blockers)
+2. **Reserve edit surface** (Mail)
+   - `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="bd-123")`
+3. **Announce start** (Mail)
+   - `send_message(..., thread_id="bd-123", subject="[bd-123] Start: <short title>", ack_required=true)`
+4. **Work and update**
+   - Reply in-thread with progress and attach artifacts/images; keep the discussion in one thread per issue id
+5. **Complete and release**
+   - `bd close bd-123 --reason "Completed"` (Beads is status authority)
+   - `release_file_reservations(project_key, agent_name, paths=["src/**"])`
+   - Final Mail reply: `[bd-123] Completed` with summary and links
+
+Mapping cheat-sheet
+
+- **Mail `thread_id`** ↔ `bd-###`
+- **Mail subject**: `[bd-###] …`
+- **File reservation `reason`**: `bd-###`
+- **Commit messages (optional)**: include `bd-###` for traceability
+
+Event mirroring (optional automation)
+
+- On `bd update --status blocked`, send a high-importance Mail message in thread `bd-###` describing the blocker.
+- On Mail "ACK overdue" for a critical decision, add a Beads label (e.g., `needs-ack`) or bump priority to surface it in `bd ready`.
+
+Pitfalls to avoid
+
+- Don't create or manage tasks in Mail; treat Beads as the single task queue.
+- Always include `bd-###` in message `thread_id` to avoid ID drift across tools.
+
+<!-- MCP_AGENT_MAIL_AND_BEADS_SNIPPET_END -->

package/templates/base/AGENTS.md

@@ -1,5 +1,7 @@
 # AGENTS.md - **APP_NAME**
 
+> **Main Documentation**: [Kuckit SDK](https://github.com/draphonix/kuckit)
+
 ## Quick Start
 
 ```bash
@@ -26,6 +28,90 @@ __APP_NAME_KEBAB__/
 
 **Note:** Core packages (`api`, `auth`, `db`, `domain`, `contracts`) are installed from npm as `@kuckit/*` dependencies, not copied into your project.
 
+## Bootstrap Architecture
+
+Kuckit uses **bootstrap packages** to minimize boilerplate in your apps:
+
+### Server Bootstrap (`@kuckit/app-server`)
+
+```typescript
+// apps/server/src/server.ts
+import 'dotenv/config'
+import { runKuckitServer } from '@kuckit/app-server'
+import { loadConfig } from './config/server'
+import { getModuleSpecs } from './config/modules'
+
+runKuckitServer({
+	loadConfig,
+	getModuleSpecs,
+}).catch((error) => {
+	console.error('Failed to start server:', error)
+	process.exit(1)
+})
+```
+
+**What `runKuckitServer` handles automatically:**
+
+- Express app creation with CORS, JSON parsing
+- DI container setup with per-request scoping
+- Module loading and API route wiring
+- Auth, health, metrics endpoints
+- Graceful shutdown
+
+**Customization via hooks:**
+
+```typescript
+runKuckitServer({
+	loadConfig,
+	getModuleSpecs,
+	hooks: {
+		onAppCreated: (app) => app.use(helmet()),
+		onContainerReady: (container) => {
+			/* warm caches */
+		},
+		onServerReady: (port) => console.log(`Listening on ${port}`),
+	},
+})
+```
+
+### Web Bootstrap (`@kuckit/app-web`)
+
+```typescript
+// apps/web/src/main.tsx
+import { createKuckitWebProvider } from '@kuckit/app-web'
+import { createAuthClient } from 'better-auth/react'
+import config from '../kuckit.config'
+
+const authClient = createAuthClient({
+  baseURL: import.meta.env.VITE_API_URL,
+})
+
+const KuckitProvider = createKuckitWebProvider({
+  config,
+  authClient,
+})
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <KuckitProvider>
+      <App />
+    </KuckitProvider>
+  </StrictMode>
+)
+```
+
+**Access registries and auth via hooks:**
+
+```typescript
+import { useKuckitWeb, useAuth } from '@kuckit/app-web'
+
+function MyComponent() {
+	const { routeRegistry, navRegistry, slotRegistry } = useKuckitWeb()
+	const authClient = useAuth()
+	const { data: session } = authClient.useSession()
+}
+```
+
 ## Module Development
 
 Kuckit uses a **module-based architecture** where each module contains its own Clean Architecture layers internally.

package/templates/base/apps/server/AGENTS.md

@@ -8,111 +8,68 @@ Express backend hosting oRPC API, Better-Auth authentication, and the Kuckit mod
 
 ## Key Files
 
-| File                      | Purpose                    |
-| ------------------------- | -------------------------- |
-| `server.ts`               | Entry point, bootstrap     |
-| `container.ts`            | DI container setup         |
-| `config/modules.ts`       | Module registration        |
-| `rpc.ts`                  | oRPC handler setup         |
-| `rpc-router-registry.ts`  | Mutable router for modules |
-| `rest-router-registry.ts` | REST router collection     |
-| `module-rest-routes.ts`   | REST router wiring         |
-| `auth.ts`                 | Better-Auth configuration  |
+| File         | Purpose                                           |
+| ------------ | ------------------------------------------------- |
+| `server.ts`  | Entry point (9 lines)                             |
+| `config.ts`  | Server configuration                              |
+| `modules.ts` | Module registration (reads from kuckit.config.ts) |
 
-## Module Loading Sequence
+## How It Works
 
-The server bootstraps in this order:
-
-```
-1. createKuckitContainer() - Core services (db, logger, cache, etc.)
-2. loadKuckitModules() with onApiRegistrations callback:
-   ├─► register() hooks run (DI bindings)
-   ├─► registerApi() hooks run (routers collected)
-   ├─► onApiRegistrations() - Wire RPC and REST routers
-   └─► onBootstrap() hooks run (startup logic)
-3. setupRPC() - Create RPCHandler AFTER modules loaded
-4. setupModuleRestRouters() - Mount REST routers to Express
-5. Express listens
-```
-
-## Router Registry Pattern
-
-oRPC's `RPCHandler` captures the router at construction time. Modules wire their routers into a **mutable object** before the handler is created:
-
-```typescript
-// rpc-router-registry.ts
-export const rootRpcRouter = { ...appRouter }
-
-export const wireModuleRpcRouters = (registrations: ApiRegistration[]) => {
-	for (const reg of registrations) {
-		if (reg.type === 'rpc-router') {
-			rootRpcRouter[reg.name] = reg.router
-		}
-	}
-}
-```
+The server uses `@kuckit/app-server` which handles all the complexity internally:
 
 ```typescript
 // server.ts
-await loadKuckitModules({
-	container,
-	modules: getModuleSpecs(),
-	onApiRegistrations: (registrations) => {
-		wireModuleRpcRouters(registrations) // Wire BEFORE setupRPC()
-		collectModuleRestRouters(registrations) // Collect REST routers
-	},
-})
-
-setupRPC(app) // Now create handler with fully-wired router
-setupModuleRestRouters(app) // Mount REST routers at /api/<name>
-```
-
-## REST Router Pattern
+import 'dotenv/config'
+import { runKuckitServer } from '@kuckit/app-server'
+import { loadConfig } from './config'
+import { getModuleSpecs } from './modules'
 
-For modules that need direct Express response access (e.g., AI streaming), use REST routers:
-
-```typescript
-// In your module's registerApi()
-ctx.addApiRegistration({
-	type: 'rest-router',
-	name: 'ai',
-	router: createAiRouter(),
-	prefix: '/ai', // Optional, defaults to /<name>
-})
+runKuckitServer({ loadConfig, getModuleSpecs }).catch(console.error)
 ```
 
-REST routers are mounted at `/api<prefix>` (e.g., `/api/ai/chat`). They receive:
-
-- Per-request scoped container via `req.scope`
-- Session via `req.scope.cradle.session`
-- Full Express `Request` and `Response` objects
+The `@kuckit/app-server` package handles:
 
-## Per-Request Scoping
+- DI container creation and setup
+- Module loading with proper lifecycle hooks
+- RPC router wiring (oRPC)
+- REST router mounting
+- Authentication (Better-Auth)
+- Health endpoints
+- Graceful shutdown
 
-Each HTTP request gets a scoped container with:
+## Adding New Modules
 
-- `requestId` - Unique request identifier
-- `requestLogger` - Logger with request context
-- `session` - Current user session (if authenticated)
+**`kuckit.config.ts` is the single source of truth for modules.**
 
-Access scoped services in routers via `context.di.cradle`.
+1. Add to `kuckit.config.ts` (at project root):
 
-## Adding New Modules
+   ```typescript
+   export default defineConfig({
+   	modules: [
+   		{ package: '@__APP_NAME_KEBAB__/items-module' },
+   		{ package: '@acme/billing-module' }, // Add new module here
+   	],
+   })
+   ```
 
-1. Install the module package
-2. Add to `config/modules.ts`:
+2. Add import and mapping to `modules.ts`:
 
    ```typescript
-   import { kuckitModule as myModule } from '@__APP_NAME_KEBAB__/my-module'
-
-   export const getModuleSpecs = () => [
-   	{ module: itemsModule },
-   	{ module: myModule }, // Add here
-   ]
+   import { kuckitModule as billingModule } from '@acme/billing-module'
+
+   const KNOWN_MODULES = {
+   	// ...existing
+   	'@acme/billing-module': {
+   		module: billingModule,
+   	},
+   }
    ```
 
 3. Restart the server
 
+The CLI command `bunx kuckit add @acme/billing-module` automates both steps.
+
 ## Environment Variables
 
 See `.env.example` in this directory.

package/templates/base/apps/server/package.json

@@ -5,27 +5,15 @@
 	"scripts": {
 		"build": "tsdown",
 		"check-types": "tsc -b",
-		"dev": "bun run --hot src/server.ts"
+		"dev": "kuckit dev"
 	},
 	"dependencies": {
-		"express": "^5.1.0",
-		"cors": "^2.8.5",
 		"dotenv": "^17.0.0",
-		"awilix": "^12.0.5",
-		"pg": "^8.14.1",
-		"@orpc/server": "^1.10.0",
-		"@orpc/zod": "^1.10.0",
-		"better-auth": "^1.3.0",
-		"zod": "^3.23.0",
+		"@kuckit/app-server": "^2.0.0",
 		"@kuckit/sdk": "^2.0.0",
-		"@kuckit/api": "^2.0.0",
-		"@kuckit/auth": "^2.0.0",
 		"@kuckit/db": "^2.0.0"
 	},
 	"devDependencies": {
-		"@types/express": "^5.0.1",
-		"@types/cors": "^2.8.17",
-		"@types/pg": "^8.11.11",
 		"typescript": "^5.8.2",
 		"tsdown": "^0.15.5"
 	}

package/templates/base/apps/server/src/config.ts

@@ -0,0 +1,12 @@
+import { ensureDatabaseUrl } from '@kuckit/db/connection'
+import type { KuckitServerConfig } from '@kuckit/app-server'
+
+export const loadConfig = (): KuckitServerConfig => ({
+	databaseUrl: ensureDatabaseUrl(),
+	enableFileLogging: process.env.ENABLE_FILE_LOGGING === 'true',
+	logDir: process.env.LOG_DIR || './logs',
+	logLevel: (process.env.LOG_LEVEL || 'INFO') as 'DEBUG' | 'INFO' | 'WARN' | 'ERROR',
+	env: process.env.NODE_ENV || 'development',
+	port: parseInt(process.env.PORT || '3000', 10),
+	corsOrigin: process.env.CORS_ORIGIN || 'http://localhost:3001',
+})

package/templates/base/apps/server/src/modules.ts

@@ -0,0 +1,66 @@
+import type { ModuleSpec, KuckitConfig } from '@kuckit/sdk'
+import { tryLoadKuckitConfig } from '@kuckit/sdk'
+import { kuckitModule as itemsModule } from '@__APP_NAME_KEBAB__/items-module'
+
+/**
+ * Known modules mapping: package name → direct module import
+ *
+ * This enables config-driven module loading while keeping direct imports
+ * for workspace packages (required for monorepo compatibility).
+ *
+ * When adding a new module:
+ * 1. Add to kuckit.config.ts (source of truth)
+ * 2. Add import and mapping here
+ */
+const KNOWN_MODULES: Record<string, { module: unknown; defaultConfig?: unknown }> = {
+	// KUCKIT_KNOWN_MODULES_START
+	'@__APP_NAME_KEBAB__/items-module': {
+		module: itemsModule,
+	},
+	// KUCKIT_KNOWN_MODULES_END
+}
+
+/**
+ * Convert unified config to ModuleSpec array.
+ * For known modules, uses direct imports. For npm packages, uses package-based loading.
+ */
+function configToModuleSpecs(config: KuckitConfig): ModuleSpec[] {
+	return config.modules
+		.filter((m) => m.enabled !== false)
+		.map((m) => {
+			const known = KNOWN_MODULES[m.package]
+			if (known) {
+				return {
+					module: known.module,
+					config: m.config ?? known.defaultConfig,
+				} as ModuleSpec
+			}
+			// For npm packages, use package-based loading
+			return {
+				package: m.package,
+				config: m.config,
+			} as ModuleSpec
+		})
+}
+
+/**
+ * Fallback module specs (used when kuckit.config.ts is not found)
+ */
+const getFallbackModuleSpecs = (): ModuleSpec[] => [{ module: itemsModule }]
+
+/**
+ * Get module specs from kuckit.config.ts (single source of truth).
+ * Falls back to direct module specs if config is not found.
+ */
+export const getModuleSpecs = async (): Promise<ModuleSpec[]> => {
+	const config = await tryLoadKuckitConfig()
+
+	if (config) {
+		console.log(`[kuckit] Loading modules from: ${config._configPath}`)
+		return configToModuleSpecs(config)
+	}
+
+	// Fallback for legacy projects without kuckit.config.ts
+	console.log('[kuckit] No config found, using fallback module specs')
+	return getFallbackModuleSpecs()
+}

package/templates/base/apps/server/src/server.ts

@@ -1,51 +1,9 @@
 import 'dotenv/config'
-import { createApp } from './app'
-import { setupContainerMiddleware, getRootContainer } from './middleware/container'
-import { setupAuth } from './auth'
-import { setupRPC } from './rpc'
-import { setupModuleRestRouters } from './module-rest-routes'
-import { setupHealth } from './health'
-import { disposeContainer } from './container'
+import { runKuckitServer } from '@kuckit/app-server'
+import { loadConfig } from './config'
+import { getModuleSpecs } from './modules'
 
-/**
- * Bootstrap and start server
- */
-const bootstrap = async () => {
-	const app = createApp()
-
-	await setupContainerMiddleware(app)
-	const rootContainer = getRootContainer()
-
-	setupAuth(app)
-	setupRPC(app)
-	setupModuleRestRouters(app)
-	setupHealth(app, rootContainer)
-
-	const port = process.env.PORT || 3000
-	const server = app.listen(port, () => {
-		console.log(`Server is running on port ${port}`)
-	})
-
-	const shutdown = async () => {
-		console.log('Shutting down gracefully...')
-
-		server.close(async () => {
-			await disposeContainer(rootContainer)
-			console.log('Server closed')
-			process.exit(0)
-		})
-
-		setTimeout(() => {
-			console.error('Forced shutdown')
-			process.exit(1)
-		}, 10000)
-	}
-
-	process.on('SIGTERM', shutdown)
-	process.on('SIGINT', shutdown)
-}
-
-bootstrap().catch((error) => {
+runKuckitServer({ loadConfig, getModuleSpecs }).catch((error) => {
 	console.error('Failed to start server:', error)
 	process.exit(1)
 })