create-kuckit-app 2.0.0 → 2.0.2

package/package.json

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

package/templates/base/AGENTS.md

@@ -83,7 +83,7 @@ import { createAuthClient } from 'better-auth/react'
 import config from '../kuckit.config'
 
 const authClient = createAuthClient({
-  baseURL: import.meta.env.VITE_API_URL,
+  baseURL: import.meta.env.VITE_SERVER_URL,
 })
 
 const KuckitProvider = createKuckitWebProvider({
@@ -452,7 +452,7 @@ See `.env.example` for required variables:
 - `BETTER_AUTH_SECRET` - Auth session secret
 - `BETTER_AUTH_URL` - Auth callback URL
 - `PORT` - Server port (default: 3000)
-- `VITE_API_URL` - API URL for frontend
+- `VITE_SERVER_URL` - API URL for frontend
 
 ## Troubleshooting
 

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

@@ -29,7 +29,7 @@ import { getClientModuleSpecs } from './modules.client'
 import './index.css'
 
 const KuckitApp = createKuckitWebProvider({
-	serverUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000',
+	serverUrl: import.meta.env.VITE_SERVER_URL || 'http://localhost:3000',
 	modules: getClientModuleSpecs(),
 	env: import.meta.env.MODE,
 	routeTree,

package/templates/base/apps/web/src/index.css

@@ -1,4 +1,5 @@
 @import "tailwindcss";
+@import "./kuckit-modules.css";
 
 @custom-variant dark (&:where(.dark, .dark *));
 

package/templates/base/apps/web/src/kuckit-modules.css

@@ -0,0 +1,13 @@
+/**
+ * Kuckit Module Styles Aggregator
+ * 
+ * This file is managed by the kuckit CLI. Do not edit the section between
+ * the markers manually - it will be overwritten when modules are added/removed.
+ * 
+ * Module styles are automatically injected here when you run:
+ *   bunx kuckit add <module-name>
+ */
+
+/* KUCKIT_MODULE_STYLES_START */
+/* Module CSS imports will be injected here by the CLI */
+/* KUCKIT_MODULE_STYLES_END */

package/templates/base/apps/web/src/main.tsx

@@ -6,7 +6,7 @@ import { getClientModuleSpecs } from './modules.client'
 import './index.css'
 
 const KuckitApp = createKuckitWebProvider({
-	serverUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000',
+	serverUrl: import.meta.env.VITE_SERVER_URL || 'http://localhost:3000',
 	modules: getClientModuleSpecs(),
 	env: import.meta.env.MODE,
 	routeTree,

package/templates/base/kuckit.config.ts

@@ -11,7 +11,7 @@ import { defineConfig } from '@kuckit/sdk/config'
 export default defineConfig({
 	modules: [
 		// KUCKIT_MODULES_START
-		{ package: '@__APP_NAME_KEBAB__/items-module', schemaDir: 'src/adapters' },
+		{ package: '@__APP_NAME_KEBAB__/items-module' },
 		// KUCKIT_MODULES_END
 	],
 

package/templates/base/packages/items-module/AGENTS.md

@@ -15,26 +15,74 @@ Use this module as a template when creating new modules.
 
 ```
 src/
-├── domain/
-│   └── item.entity.ts      # Entity schema (Zod)
-├── ports/
-│   └── item.repository.ts  # Repository interface
-├── adapters/
-│   └── item.drizzle.ts     # Drizzle implementation
-├── usecases/
-│   ├── create-item.ts      # Create item use case
-│   ├── get-item.ts         # Get single item
-│   ├── list-items.ts       # List all items
-│   └── delete-item.ts      # Delete item
-├── api/
-│   └── items.router.ts     # oRPC router
-├── ui/
-│   └── ItemsPage.tsx       # React component
-├── module.ts               # Server module definition
-├── client-module.ts        # Client module definition
-└── index.ts                # Public exports
+├── server/
+│   ├── domain/
+│   │   └── item.entity.ts      # Entity schema (Zod)
+│   ├── ports/
+│   │   └── item.repository.ts  # Repository interface
+│   ├── adapters/
+│   │   └── item.drizzle.ts     # Drizzle implementation
+│   ├── usecases/
+│   │   ├── create-item.ts      # Create item use case
+│   │   ├── get-item.ts         # Get single item
+│   │   ├── list-items.ts       # List all items
+│   │   ├── update-item.ts      # Update item
+│   │   └── delete-item.ts      # Delete item
+│   ├── api/
+│   │   └── items.router.ts     # oRPC router
+│   ├── config.ts               # Module config with Zod schema
+│   ├── module.ts               # Server module definition
+│   └── index.ts                # Server exports
+└── client/
+    ├── ui/
+    │   └── ItemsPage.tsx       # React component
+    └── index.ts                # Client module + exports
 ```
 
+## Configuration Options
+
+| Option             | Type      | Default | Description                                      |
+| ------------------ | --------- | ------- | ------------------------------------------------ |
+| `maxItemsPerPage`  | `number`  | `100`   | Maximum items returned per list request (1-1000) |
+| `enableSoftDelete` | `boolean` | `false` | Mark items as deleted instead of hard delete     |
+
+Configure via `kuckit.config.ts`:
+
+```typescript
+modules: [
+	{
+		spec: itemsModule,
+		config: {
+			maxItemsPerPage: 50,
+			enableSoftDelete: true,
+		},
+	},
+]
+```
+
+## DI Registrations
+
+| Token            | Type                | Lifetime | Description                 |
+| ---------------- | ------------------- | -------- | --------------------------- |
+| `itemRepository` | `ItemRepository`    | Scoped   | Data access for items table |
+| `listItems`      | `ListItemsUseCase`  | Scoped   | List items by user          |
+| `createItem`     | `CreateItemUseCase` | Scoped   | Create new item             |
+| `getItem`        | `GetItemUseCase`    | Scoped   | Get single item by ID       |
+| `updateItem`     | `UpdateItemUseCase` | Scoped   | Update existing item        |
+| `deleteItem`     | `DeleteItemUseCase` | Scoped   | Delete item by ID           |
+
+## API Endpoints
+
+All endpoints require authentication (`protectedProcedure`).
+
+| Endpoint       | Method | Input                                    | Output              | Description       |
+| -------------- | ------ | ---------------------------------------- | ------------------- | ----------------- |
+| `items.list`   | RPC    | `{}`                                     | `Item[]`            | List user's items |
+| `items.get`    | RPC    | `{ id: string }`                         | `Item \| null`      | Get item by ID    |
+| `items.create` | RPC    | `{ name: string, description?: string }` | `Item`              | Create new item   |
+| `items.update` | RPC    | `{ id, name?, description? }`            | `Item`              | Update item       |
+| `items.delete` | RPC    | `{ id: string }`                         | `{ success: bool }` | Delete item       |
+
 ## Key Patterns
 
 ### Domain Layer
@@ -139,7 +187,7 @@ export const clientModules = [{ module: itemsClient }]
 The client module registers routes, navigation items, and slots:
 
 ```typescript
-// client-module.ts
+// src/client/index.ts
 import { defineKuckitClientModule } from '@kuckit/sdk-react'
 import { ItemsPage } from './ui/ItemsPage'
 
@@ -147,23 +195,24 @@ export const kuckitClientModule = defineKuckitClientModule({
 	id: 'items',
 	displayName: 'Items',
 
-	routes: [
-		{
+	register(ctx) {
+		ctx.registerComponent('ItemsPage', ItemsPage)
+
+		ctx.addRoute({
 			id: 'items-page',
 			path: '/items',
 			component: ItemsPage,
 			meta: { requiresAuth: true },
-		},
-	],
+		})
 
-	navItems: [
-		{
+		ctx.addNavItem({
 			id: 'items-nav',
 			label: 'Items',
-			href: '/items',
-			order: 20,
-		},
-	],
+			path: '/items',
+			icon: 'list',
+			order: 10,
+		})
+	},
 })
 ```
 
@@ -172,7 +221,7 @@ export const kuckitClientModule = defineKuckitClientModule({
 Module components access the API via the `useRpc` hook:
 
 ```typescript
-// ui/ItemsPage.tsx
+// src/client/ui/ItemsPage.tsx
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
 import { useRpc } from '@kuckit/sdk-react'
 

package/templates/base/packages/items-module/README.md

@@ -0,0 +1,132 @@
+# Items Module
+
+> **Reference implementation** of a Kuckit module demonstrating Clean Architecture patterns.
+
+Use this module as a template when creating new modules for your Kuckit application.
+
+## Features
+
+- **CRUD operations** for items with full validation
+- **Clean Architecture** with domain, ports, adapters, use cases, and API layers
+- **Type-safe API** using oRPC with Zod schemas
+- **React components** with TanStack Query integration
+- **Configurable** via `kuckit.config.ts`
+
+## Installation
+
+The items-module is included by default in projects scaffolded with `create-kuckit-app`.
+
+For manual installation:
+
+```bash
+# Copy the module to your project
+cp -r packages/items-module packages/your-module
+
+# Update package.json name
+# Edit packages/your-module/package.json
+```
+
+## Usage
+
+### Server Registration
+
+```typescript
+// apps/server/src/config/modules.ts
+import { kuckitModule as itemsModule } from '@your-app/items-module'
+
+export const getModuleSpecs = () => [{ spec: itemsModule }]
+```
+
+### Client Registration
+
+```typescript
+// apps/web/src/modules.client.ts
+import { kuckitClientModule as itemsClient } from '@your-app/items-module/client'
+
+export const clientModules = [{ module: itemsClient }]
+```
+
+### Database Setup
+
+Add the module's schema to your Drizzle config:
+
+```typescript
+// drizzle.config.ts
+schema: [
+  './node_modules/@kuckit/db/dist/schema/auth.js',
+  './packages/items-module/src/server/adapters',
+],
+```
+
+Then run migrations:
+
+```bash
+bun run db:push    # Development
+bun run db:migrate # Production
+```
+
+## Configuration
+
+Configure the module in `kuckit.config.ts`:
+
+```typescript
+import { kuckitModule as itemsModule } from '@your-app/items-module'
+
+export default defineKuckitConfig({
+	modules: [
+		{
+			spec: itemsModule,
+			config: {
+				maxItemsPerPage: 50, // Default: 100
+				enableSoftDelete: true, // Default: false
+			},
+		},
+	],
+})
+```
+
+## API Reference
+
+All endpoints require authentication.
+
+| Endpoint       | Input                                    | Output         | Description       |
+| -------------- | ---------------------------------------- | -------------- | ----------------- |
+| `items.list`   | `{}`                                     | `Item[]`       | List user's items |
+| `items.get`    | `{ id: string }`                         | `Item \| null` | Get item by ID    |
+| `items.create` | `{ name: string, description?: string }` | `Item`         | Create new item   |
+| `items.update` | `{ id, name?, description? }`            | `Item`         | Update item       |
+| `items.delete` | `{ id: string }`                         | `{ success }`  | Delete item       |
+
+## Project Structure
+
+```
+src/
+├── server/           # Backend code
+│   ├── domain/       # Entity schemas (Zod)
+│   ├── ports/        # Repository interfaces
+│   ├── adapters/     # Drizzle implementations
+│   ├── usecases/     # Business logic
+│   ├── api/          # oRPC router
+│   ├── config.ts     # Module configuration
+│   └── module.ts     # Server module definition
+└── client/           # Frontend code
+    ├── ui/           # React components
+    └── index.ts      # Client module definition
+```
+
+## Creating a New Module
+
+1. Copy this module: `cp -r packages/items-module packages/your-module`
+2. Update `package.json` name to `@your-app/your-module`
+3. Replace domain entities in `src/server/domain/`
+4. Update ports and adapters
+5. Implement use cases
+6. Create API router
+7. Register in both server and client configs
+8. Add schema path to `drizzle.config.ts`
+9. Run `bun run db:push`
+
+## Documentation
+
+- [AGENTS.md](./AGENTS.md) - AI assistant guidance and detailed patterns
+- [Kuckit SDK](https://github.com/draphonix/kuckit) - Framework documentation

package/templates/base/packages/items-module/package.json

@@ -3,22 +3,24 @@
 	"version": "0.0.1",
 	"private": true,
 	"type": "module",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
+	"main": "src/server/module.ts",
+	"types": "src/server/module.ts",
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
-			"default": "./src/index.ts"
+			"types": "./src/server/index.ts",
+			"default": "./src/server/index.ts"
 		},
 		"./client": {
-			"types": "./src/client-module.ts",
-			"default": "./src/client-module.ts"
-		},
-		"./ui": {
-			"types": "./src/ui/index.ts",
-			"default": "./src/ui/index.ts"
+			"types": "./src/client/index.ts",
+			"default": "./src/client/index.ts"
 		}
 	},
+	"kuckit": {
+		"id": "items",
+		"server": ".",
+		"client": "./client",
+		"schemaDir": "src/server/adapters"
+	},
 	"peerDependencies": {
 		"typescript": "^5"
 	},

package/templates/base/packages/items-module/src/server/api/items.router.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod'
+import { protectedProcedure } from '@kuckit/api'
+import { CreateItemInputSchema, UpdateItemInputSchema } from '../domain/item.entity'
+import type { Item } from '../domain/item.entity'
+import type { ListItemsInput, ListItemsOutput } from '../usecases/list-items'
+import type { CreateItemUseCaseInput } from '../usecases/create-item'
+import type { GetItemInput } from '../usecases/get-item'
+import type { DeleteItemInput } from '../usecases/delete-item'
+import type { UpdateItemUseCaseInput } from '../usecases/update-item'
+
+/**
+ * Items cradle interface for DI resolution
+ */
+interface ItemsCradle {
+	listItems: (input: ListItemsInput) => Promise<ListItemsOutput>
+	createItem: (input: CreateItemUseCaseInput) => Promise<Item>
+	getItem: (input: GetItemInput) => Promise<Item | null>
+	deleteItem: (input: DeleteItemInput) => Promise<boolean>
+	updateItem: (input: UpdateItemUseCaseInput) => Promise<Item>
+}
+
+/**
+ * Items oRPC router
+ * Provides CRUD operations for items
+ */
+export const itemsRouter = {
+	list: protectedProcedure.input(z.object({})).handler(async ({ context }) => {
+		const userId = context.session?.user?.id
+		if (!userId) throw new Error('User not authenticated')
+
+		const { listItems } = context.di.cradle as ItemsCradle
+		return listItems({ userId })
+	}),
+
+	get: protectedProcedure
+		.input(z.object({ id: z.string() }))
+		.handler(async ({ input, context }) => {
+			const { getItem } = context.di.cradle as ItemsCradle
+			return getItem({ id: input.id })
+		}),
+
+	create: protectedProcedure.input(CreateItemInputSchema).handler(async ({ input, context }) => {
+		const userId = context.session?.user?.id
+		if (!userId) throw new Error('User not authenticated')
+
+		const { createItem } = context.di.cradle as ItemsCradle
+		return createItem({
+			name: input.name,
+			description: input.description,
+			userId,
+		})
+	}),
+
+	delete: protectedProcedure
+		.input(z.object({ id: z.string() }))
+		.handler(async ({ input, context }) => {
+			const { deleteItem } = context.di.cradle as ItemsCradle
+			const success = await deleteItem({ id: input.id })
+			return { success }
+		}),
+
+	update: protectedProcedure.input(UpdateItemInputSchema).handler(async ({ input, context }) => {
+		const userId = context.session?.user?.id
+		if (!userId) throw new Error('User not authenticated')
+
+		const { updateItem } = context.di.cradle as ItemsCradle
+		return updateItem({
+			id: input.id,
+			name: input.name,
+			description: input.description,
+			userId,
+		})
+	}),
+}

package/templates/base/packages/items-module/src/server/config.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod'
+
+/**
+ * Items module configuration schema
+ *
+ * This is an example module with minimal configuration.
+ * Real modules might include settings for:
+ * - Feature flags
+ * - Pagination limits
+ * - Cache TTLs
+ * - External service URLs
+ */
+export const itemsModuleConfigSchema = z.object({
+	/**
+	 * Maximum number of items to return per list request
+	 * @default 100
+	 */
+	maxItemsPerPage: z.number().min(1).max(1000).default(100),
+
+	/**
+	 * Enable soft delete (mark as deleted instead of hard delete)
+	 * @default false
+	 */
+	enableSoftDelete: z.boolean().default(false),
+})
+
+export type ItemsModuleConfig = z.infer<typeof itemsModuleConfigSchema>

package/templates/base/packages/items-module/src/{index.ts → server/index.ts}

@@ -1,6 +1,6 @@
 // Server module exports
 export { kuckitModule } from './module'
-export type { ItemsModuleConfig } from './module'
+export { itemsModuleConfigSchema, type ItemsModuleConfig } from './config'
 
 // Domain exports
 export * from './domain/item.entity'

package/templates/base/packages/items-module/src/{module.ts → server/module.ts}

@@ -1,8 +1,14 @@
 import { defineKuckitModule, asFunction, type KuckitModuleContext } from '@kuckit/sdk'
 import { itemsTable, makeItemRepository } from './adapters/item.drizzle'
 import { itemsRouter } from './api/items.router'
+import { itemsModuleConfigSchema, type ItemsModuleConfig } from './config'
+import { makeListItems } from './usecases/list-items'
+import { makeCreateItem } from './usecases/create-item'
+import { makeGetItem } from './usecases/get-item'
+import { makeDeleteItem } from './usecases/delete-item'
+import { makeUpdateItem } from './usecases/update-item'
 
-export type ItemsModuleConfig = Record<string, never>
+export type { ItemsModuleConfig }
 
 /**
  * Items module - example Kuckit module demonstrating the full pattern
@@ -20,15 +26,29 @@ export const kuckitModule = defineKuckitModule<ItemsModuleConfig>({
 	version: '0.1.0',
 
 	async register(ctx: KuckitModuleContext<ItemsModuleConfig>) {
-		const { container } = ctx
+		const { container, config } = ctx
+		const resolvedConfig = itemsModuleConfigSchema.parse(config ?? {})
 
 		// Register schema for migrations
 		ctx.registerSchema('items', itemsTable)
 
+		// Log configuration
+		const logger = container.resolve('logger')
+		logger.debug('Items module config', { config: resolvedConfig })
+
 		// Register repository
 		container.register({
 			itemRepository: asFunction(({ db }) => makeItemRepository(db)).scoped(),
 		})
+
+		// Register use cases
+		container.register({
+			listItems: asFunction(({ itemRepository }) => makeListItems({ itemRepository })).scoped(),
+			createItem: asFunction(({ itemRepository }) => makeCreateItem({ itemRepository })).scoped(),
+			getItem: asFunction(({ itemRepository }) => makeGetItem({ itemRepository })).scoped(),
+			deleteItem: asFunction(({ itemRepository }) => makeDeleteItem({ itemRepository })).scoped(),
+			updateItem: asFunction(({ itemRepository }) => makeUpdateItem({ itemRepository })).scoped(),
+		})
 	},
 
 	registerApi(ctx) {

package/templates/base/packages/items-module/src/server/usecases/update-item.ts

@@ -0,0 +1,28 @@
+import type { ItemRepository } from '../ports/item.repository'
+import type { Item, UpdateItemInput } from '../domain/item.entity'
+
+export interface UpdateItemUseCaseInput extends UpdateItemInput {
+	userId: string
+}
+
+interface UpdateItemDeps {
+	itemRepository: ItemRepository
+}
+
+/**
+ * Update item use case
+ * Validates ownership before allowing update
+ */
+export function makeUpdateItem(deps: UpdateItemDeps) {
+	return async (input: UpdateItemUseCaseInput): Promise<Item> => {
+		const existing = await deps.itemRepository.findById(input.id)
+		if (!existing || existing.userId !== input.userId) {
+			throw new Error('Item not found')
+		}
+		const updated = await deps.itemRepository.update(input)
+		if (!updated) {
+			throw new Error('Failed to update item')
+		}
+		return updated
+	}
+}

package/templates/base/packages/items-module/src/api/items.router.ts

@@ -1,47 +0,0 @@
-import { z } from 'zod'
-import { protectedProcedure } from '@kuckit/api'
-import { CreateItemInputSchema } from '../domain/item.entity'
-import type { ItemRepository } from '../ports/item.repository'
-
-/**
- * Items oRPC router
- * Provides CRUD operations for items
- */
-export const itemsRouter = {
-	list: protectedProcedure.input(z.object({})).handler(async ({ context }) => {
-		const userId = context.session?.user?.id
-		if (!userId) throw new Error('User not authenticated')
-
-		// In a real app, you'd resolve this from the DI container
-		const items = await context.di.resolve<ItemRepository>('itemRepository').findByUserId(userId)
-		return items
-	}),
-
-	get: protectedProcedure
-		.input(z.object({ id: z.string() }))
-		.handler(async ({ input, context }) => {
-			const item = await context.di.resolve<ItemRepository>('itemRepository').findById(input.id)
-			return item
-		}),
-
-	create: protectedProcedure.input(CreateItemInputSchema).handler(async ({ input, context }) => {
-		const userId = context.session?.user?.id
-		if (!userId) throw new Error('User not authenticated')
-
-		const id = crypto.randomUUID()
-		const item = await context.di.resolve<ItemRepository>('itemRepository').create({
-			id,
-			name: input.name,
-			description: input.description,
-			userId,
-		})
-		return item
-	}),
-
-	delete: protectedProcedure
-		.input(z.object({ id: z.string() }))
-		.handler(async ({ input, context }) => {
-			const success = await context.di.resolve<ItemRepository>('itemRepository').delete(input.id)
-			return { success }
-		}),
-}

package/templates/base/packages/items-module/src/ui/index.ts

@@ -1 +0,0 @@
-export { ItemsPage } from './ItemsPage'