create-kuckit-app 0.1.0 → 0.2.0

package/templates/base/packages/db/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "@__APP_NAME_KEBAB__/db",
+	"version": "0.0.1",
+	"private": true,
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./src/*.ts",
+			"default": "./src/*.ts"
+		}
+	},
+	"scripts": {
+		"db:generate": "drizzle-kit generate",
+		"db:migrate": "drizzle-kit migrate",
+		"db:studio": "drizzle-kit studio"
+	},
+	"devDependencies": {
+		"drizzle-kit": "^0.31.2",
+		"@types/pg": "^8.11.11"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"drizzle-orm": "^0.44.2",
+		"pg": "^8.14.1",
+		"dotenv": "^17.2.2",
+		"zod": "^4.1.11"
+	}
+}

package/templates/base/packages/db/src/connection.ts

@@ -0,0 +1,40 @@
+/**
+ * Database connection utilities
+ * Single source of truth for DATABASE_URL construction
+ */
+
+/**
+ * Build DATABASE_URL from environment variables
+ *
+ * Supports two modes:
+ * 1. Direct DATABASE_URL - used in local development
+ * 2. Individual DB_* vars - used in Cloud Run with Cloud SQL Auth Proxy
+ *
+ * @throws Error if neither DATABASE_URL nor complete DB_* vars are provided
+ */
+export function buildDatabaseUrl(): string {
+	// Prefer DATABASE_URL if provided directly
+	if (process.env.DATABASE_URL) {
+		return process.env.DATABASE_URL
+	}
+
+	// Construct from individual components (Cloud Run with Cloud SQL)
+	const { DB_HOST, DB_USER, DB_PASSWORD, DB_NAME } = process.env
+	if (DB_HOST && DB_USER && DB_PASSWORD && DB_NAME) {
+		return `postgresql://${DB_USER}:${encodeURIComponent(DB_PASSWORD)}@/${DB_NAME}?host=${DB_HOST}`
+	}
+
+	throw new Error(
+		'Missing database configuration: provide DATABASE_URL or DB_HOST, DB_USER, DB_PASSWORD, DB_NAME'
+	)
+}
+
+/**
+ * Ensure DATABASE_URL is set in process.env
+ * Call this early in application startup to set up the environment
+ */
+export function ensureDatabaseUrl(): string {
+	const url = buildDatabaseUrl()
+	process.env.DATABASE_URL = url
+	return url
+}

package/templates/base/packages/db/src/index.ts

@@ -0,0 +1,4 @@
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { buildDatabaseUrl } from './connection'
+
+export const db = drizzle(buildDatabaseUrl())

package/templates/base/packages/db/src/migrations/0000_init.sql

@@ -0,0 +1,54 @@
+-- Initial migration: Auth tables
+-- This migration is generated by drizzle-kit
+-- Run: bun run db:migrate
+
+CREATE TABLE IF NOT EXISTS "user" (
+	"id" text PRIMARY KEY NOT NULL,
+	"name" text NOT NULL,
+	"email" text NOT NULL,
+	"email_verified" boolean NOT NULL,
+	"image" text,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL,
+	CONSTRAINT "user_email_unique" UNIQUE("email")
+);
+
+CREATE TABLE IF NOT EXISTS "session" (
+	"id" text PRIMARY KEY NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"token" text NOT NULL,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL,
+	"ip_address" text,
+	"user_agent" text,
+	"user_id" text NOT NULL,
+	CONSTRAINT "session_token_unique" UNIQUE("token")
+);
+
+CREATE TABLE IF NOT EXISTS "account" (
+	"id" text PRIMARY KEY NOT NULL,
+	"account_id" text NOT NULL,
+	"provider_id" text NOT NULL,
+	"user_id" text NOT NULL,
+	"access_token" text,
+	"refresh_token" text,
+	"id_token" text,
+	"access_token_expires_at" timestamp,
+	"refresh_token_expires_at" timestamp,
+	"scope" text,
+	"password" text,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS "verification" (
+	"id" text PRIMARY KEY NOT NULL,
+	"identifier" text NOT NULL,
+	"value" text NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"created_at" timestamp,
+	"updated_at" timestamp
+);
+
+ALTER TABLE "session" ADD CONSTRAINT "session_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;
+ALTER TABLE "account" ADD CONSTRAINT "account_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;

package/templates/base/packages/db/src/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+	"version": "7",
+	"dialect": "postgresql",
+	"entries": [
+		{
+			"idx": 0,
+			"version": "7",
+			"when": 1734000000000,
+			"tag": "0000_init",
+			"breakpoints": true
+		}
+	]
+}

package/templates/base/packages/db/src/schema/auth.ts

@@ -0,0 +1,51 @@
+import { pgTable, text, timestamp, boolean } from 'drizzle-orm/pg-core'
+
+export const user = pgTable('user', {
+	id: text('id').primaryKey(),
+	name: text('name').notNull(),
+	email: text('email').notNull().unique(),
+	emailVerified: boolean('email_verified').notNull(),
+	image: text('image'),
+	createdAt: timestamp('created_at').notNull(),
+	updatedAt: timestamp('updated_at').notNull(),
+})
+
+export const session = pgTable('session', {
+	id: text('id').primaryKey(),
+	expiresAt: timestamp('expires_at').notNull(),
+	token: text('token').notNull().unique(),
+	createdAt: timestamp('created_at').notNull(),
+	updatedAt: timestamp('updated_at').notNull(),
+	ipAddress: text('ip_address'),
+	userAgent: text('user_agent'),
+	userId: text('user_id')
+		.notNull()
+		.references(() => user.id, { onDelete: 'cascade' }),
+})
+
+export const account = pgTable('account', {
+	id: text('id').primaryKey(),
+	accountId: text('account_id').notNull(),
+	providerId: text('provider_id').notNull(),
+	userId: text('user_id')
+		.notNull()
+		.references(() => user.id, { onDelete: 'cascade' }),
+	accessToken: text('access_token'),
+	refreshToken: text('refresh_token'),
+	idToken: text('id_token'),
+	accessTokenExpiresAt: timestamp('access_token_expires_at'),
+	refreshTokenExpiresAt: timestamp('refresh_token_expires_at'),
+	scope: text('scope'),
+	password: text('password'),
+	createdAt: timestamp('created_at').notNull(),
+	updatedAt: timestamp('updated_at').notNull(),
+})
+
+export const verification = pgTable('verification', {
+	id: text('id').primaryKey(),
+	identifier: text('identifier').notNull(),
+	value: text('value').notNull(),
+	expiresAt: timestamp('expires_at').notNull(),
+	createdAt: timestamp('created_at'),
+	updatedAt: timestamp('updated_at'),
+})

package/templates/base/packages/db/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"outDir": "dist",
+		"rootDir": "src"
+	},
+	"include": ["src/**/*"]
+}

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

@@ -0,0 +1,112 @@
+# AGENTS.md - Items Module
+
+> See root [AGENTS.md](../../AGENTS.md) for project overview
+
+## Purpose
+
+**Reference implementation** of a Kuckit module demonstrating the full pattern.
+
+Use this module as a template when creating new modules.
+
+## Structure
+
+```
+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
+```
+
+## Key Patterns
+
+### Domain Layer
+
+Pure Zod schemas, no dependencies:
+
+```typescript
+export const ItemSchema = z.object({
+	id: z.string().uuid(),
+	name: z.string().min(1),
+})
+```
+
+### Ports Layer
+
+Interfaces only, depend on domain:
+
+```typescript
+export interface ItemRepository {
+	findAll(): Promise<Item[]>
+	findById(id: string): Promise<Item | null>
+	create(item: CreateItem): Promise<Item>
+	delete(id: string): Promise<void>
+}
+```
+
+### Adapters Layer
+
+Implement ports using Drizzle:
+
+```typescript
+export const makeItemRepository = (db: Database): ItemRepository => ({
+	findAll: () => db.select().from(itemsTable),
+	// ...
+})
+```
+
+### Use Cases
+
+Business logic, depend on ports:
+
+```typescript
+export const createItem =
+	(repo: ItemRepository) =>
+	async (input: CreateItem): Promise<Item> => {
+		return repo.create(input)
+	}
+```
+
+### Module Definition
+
+Lifecycle hooks for registration:
+
+```typescript
+export const kuckitModule = defineKuckitModule({
+	id: 'items',
+	register(ctx) {
+		/* DI registration */
+	},
+	registerApi(ctx) {
+		/* API routes */
+	},
+	onBootstrap(ctx) {
+		/* Startup logic */
+	},
+})
+```
+
+## Creating a New Module
+
+1. Copy this entire `items-module` folder
+2. Rename to `your-module`
+3. Update `package.json` name
+4. Replace domain entities
+5. Update ports and adapters
+6. Implement use cases
+7. Create API router
+8. Register in server's `config/modules.ts`

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

@@ -0,0 +1,32 @@
+{
+	"name": "@__APP_NAME_KEBAB__/items-module",
+	"version": "0.0.1",
+	"private": true,
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./client": {
+			"types": "./src/client-module.ts",
+			"default": "./src/client-module.ts"
+		}
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"@kuckit/sdk": "^1.0.0",
+		"@kuckit/sdk-react": "^1.0.0",
+		"@orpc/server": "^1.10.0",
+		"@orpc/zod": "^1.10.0",
+		"drizzle-orm": "^0.44.2",
+		"zod": "^4.1.11",
+		"react": "^19.1.0",
+		"@__APP_NAME_KEBAB__/api": "workspace:*",
+		"@__APP_NAME_KEBAB__/db": "workspace:*"
+	}
+}

package/templates/base/packages/items-module/src/adapters/item.drizzle.ts

@@ -0,0 +1,66 @@
+import { pgTable, text, timestamp } from 'drizzle-orm/pg-core'
+import { eq } from 'drizzle-orm'
+import type { ItemRepository } from '../ports/item.repository'
+import type { Item, CreateItemInput, UpdateItemInput } from '../domain/item.entity'
+
+/**
+ * Items table schema for Drizzle ORM
+ */
+export const itemsTable = pgTable('items', {
+	id: text('id').primaryKey(),
+	name: text('name').notNull(),
+	description: text('description'),
+	createdAt: timestamp('created_at').notNull().defaultNow(),
+	updatedAt: timestamp('updated_at').notNull().defaultNow(),
+	userId: text('user_id').notNull(),
+})
+
+/**
+ * Create a Drizzle-based item repository
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function makeItemRepository(db: any): ItemRepository {
+	return {
+		async findById(id: string): Promise<Item | null> {
+			const results = await db.select().from(itemsTable).where(eq(itemsTable.id, id))
+			return results[0] ?? null
+		},
+
+		async findByUserId(userId: string): Promise<Item[]> {
+			return db.select().from(itemsTable).where(eq(itemsTable.userId, userId))
+		},
+
+		async create(input: CreateItemInput & { id: string; userId: string }): Promise<Item> {
+			const now = new Date()
+			const item = {
+				id: input.id,
+				name: input.name,
+				description: input.description ?? null,
+				createdAt: now,
+				updatedAt: now,
+				userId: input.userId,
+			}
+			await db.insert(itemsTable).values(item)
+			return item as Item
+		},
+
+		async update(input: UpdateItemInput): Promise<Item | null> {
+			const existing = await this.findById(input.id)
+			if (!existing) return null
+
+			const updated = {
+				...existing,
+				...(input.name !== undefined && { name: input.name }),
+				...(input.description !== undefined && { description: input.description }),
+				updatedAt: new Date(),
+			}
+			await db.update(itemsTable).set(updated).where(eq(itemsTable.id, input.id))
+			return updated
+		},
+
+		async delete(id: string): Promise<boolean> {
+			const result = await db.delete(itemsTable).where(eq(itemsTable.id, id))
+			return result.rowCount > 0
+		},
+	}
+}

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

@@ -0,0 +1,47 @@
+import { z } from 'zod'
+import { protectedProcedure } from '@__APP_NAME_KEBAB__/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/client-module.ts

@@ -0,0 +1,39 @@
+import { defineKuckitClientModule, type KuckitClientModuleContext } from '@kuckit/sdk-react'
+import { ItemsPage } from './ui/ItemsPage'
+
+/**
+ * Items client module
+ * Registers routes and components for the web app
+ */
+export const kuckitClientModule = defineKuckitClientModule({
+	id: 'items',
+	displayName: 'Items',
+	version: '0.1.0',
+
+	register(ctx: KuckitClientModuleContext) {
+		// Register the items page component
+		ctx.registerComponent('ItemsPage', ItemsPage)
+
+		// Add route for items page
+		ctx.addRoute({
+			id: 'items',
+			path: '/items',
+			component: ItemsPage,
+			meta: {
+				title: 'Items',
+				requiresAuth: true,
+			},
+		})
+
+		// Add navigation item
+		ctx.addNavItem({
+			id: 'items-nav',
+			label: 'Items',
+			path: '/items',
+			icon: 'list',
+			order: 10,
+		})
+	},
+})
+
+export { ItemsPage } from './ui/ItemsPage'

package/templates/base/packages/items-module/src/domain/item.entity.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+
+/**
+ * Item entity schema
+ */
+export const ItemSchema = z.object({
+	id: z.string(),
+	name: z.string().min(1, 'Name is required'),
+	description: z.string().optional(),
+	createdAt: z.date(),
+	updatedAt: z.date(),
+	userId: z.string(),
+})
+
+export type Item = z.infer<typeof ItemSchema>
+
+/**
+ * Create item input schema
+ */
+export const CreateItemInputSchema = z.object({
+	name: z.string().min(1, 'Name is required'),
+	description: z.string().optional(),
+})
+
+export type CreateItemInput = z.infer<typeof CreateItemInputSchema>
+
+/**
+ * Update item input schema
+ */
+export const UpdateItemInputSchema = z.object({
+	id: z.string(),
+	name: z.string().min(1, 'Name is required').optional(),
+	description: z.string().optional(),
+})
+
+export type UpdateItemInput = z.infer<typeof UpdateItemInputSchema>

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

@@ -0,0 +1,15 @@
+// Server module exports
+export { kuckitModule } from './module'
+export type { ItemsModuleConfig } from './module'
+
+// Domain exports
+export * from './domain/item.entity'
+
+// Port exports
+export type { ItemRepository } from './ports/item.repository'
+
+// Use case exports
+export { makeListItems } from './usecases/list-items'
+export { makeCreateItem } from './usecases/create-item'
+export { makeGetItem } from './usecases/get-item'
+export { makeDeleteItem } from './usecases/delete-item'

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

@@ -0,0 +1,53 @@
+import { defineKuckitModule, asFunction, type KuckitModuleContext } from '@kuckit/sdk'
+import { itemsTable, makeItemRepository } from './adapters/item.drizzle'
+import { itemsRouter } from './api/items.router'
+
+export type ItemsModuleConfig = Record<string, never>
+
+/**
+ * Items module - example Kuckit module demonstrating the full pattern
+ *
+ * This module shows:
+ * - Domain entity with Zod validation
+ * - Repository port/adapter pattern
+ * - Use cases for business logic
+ * - oRPC router for API endpoints
+ */
+export const kuckitModule = defineKuckitModule<ItemsModuleConfig>({
+	id: 'items',
+	displayName: 'Items',
+	description: 'Example items module for CRUD operations',
+	version: '0.1.0',
+
+	async register(ctx: KuckitModuleContext<ItemsModuleConfig>) {
+		const { container } = ctx
+
+		// Register schema for migrations
+		ctx.registerSchema('items', itemsTable)
+
+		// Register repository
+		container.register({
+			itemRepository: asFunction(({ db }) => makeItemRepository(db)).scoped(),
+		})
+	},
+
+	registerApi(ctx) {
+		ctx.addApiRegistration({
+			type: 'rpc-router',
+			name: 'items',
+			router: itemsRouter,
+		})
+	},
+
+	async onBootstrap(ctx: KuckitModuleContext<ItemsModuleConfig>) {
+		const { container } = ctx
+		const logger = container.resolve('logger')
+		logger.info('Items module initialized')
+	},
+
+	async onShutdown(ctx: KuckitModuleContext<ItemsModuleConfig>) {
+		const { container } = ctx
+		const logger = container.resolve('logger')
+		logger.info('Items module shutting down')
+	},
+})

package/templates/base/packages/items-module/src/ports/item.repository.ts

@@ -0,0 +1,13 @@
+import type { Item, CreateItemInput, UpdateItemInput } from '../domain/item.entity'
+
+/**
+ * Item repository port interface
+ * Defines the contract for item persistence operations
+ */
+export interface ItemRepository {
+	findById(id: string): Promise<Item | null>
+	findByUserId(userId: string): Promise<Item[]>
+	create(input: CreateItemInput & { id: string; userId: string }): Promise<Item>
+	update(input: UpdateItemInput): Promise<Item | null>
+	delete(id: string): Promise<boolean>
+}