create-kuckit-app 0.1.1 → 0.2.1

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

@@ -0,0 +1,93 @@
+# AGENTS.md - Server App
+
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
+
+## Purpose
+
+Express backend hosting oRPC API, Better-Auth authentication, and the Kuckit module system.
+
+## 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 |
+| `auth.ts`                | Better-Auth configuration  |
+
+## Module Loading Sequence
+
+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 routers to rootRpcRouter
+   └─► onBootstrap() hooks run (startup logic)
+3. setupRPC() - Create RPCHandler AFTER modules loaded
+4. 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
+		}
+	}
+}
+```
+
+```typescript
+// server.ts
+await loadKuckitModules({
+	container,
+	modules: getModuleSpecs(),
+	onApiRegistrations: (registrations) => {
+		wireModuleRpcRouters(registrations) // Wire BEFORE setupRPC()
+	},
+})
+
+setupRPC(app) // Now create handler with fully-wired router
+```
+
+## Per-Request Scoping
+
+Each HTTP request gets a scoped container with:
+
+- `requestId` - Unique request identifier
+- `requestLogger` - Logger with request context
+- `session` - Current user session (if authenticated)
+
+Access scoped services in routers via `context.di.cradle`.
+
+## Adding New Modules
+
+1. Install the module package
+2. Add to `config/modules.ts`:
+
+   ```typescript
+   import { kuckitModule as myModule } from '@__APP_NAME_KEBAB__/my-module'
+
+   export const getModuleSpecs = () => [
+   	{ module: itemsModule },
+   	{ module: myModule }, // Add here
+   ]
+   ```
+
+3. Restart the server
+
+## Environment Variables
+
+See `.env.example` in this directory.

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

@@ -1,5 +1,6 @@
 {
-	"name": "__APP_NAME_KEBAB__-server",
+	"name": "@__APP_NAME_KEBAB__/server",
+	"private": true,
 	"type": "module",
 	"scripts": {
 		"build": "tsdown",
@@ -10,11 +11,21 @@
 		"express": "^5.1.0",
 		"cors": "^2.8.5",
 		"dotenv": "^17.2.2",
-		"awilix": "^12.0.5"
+		"awilix": "^12.0.5",
+		"pg": "^8.14.1",
+		"@orpc/server": "^1.10.0",
+		"@orpc/zod": "^1.10.0",
+		"better-auth": "^1.3.28",
+		"zod": "^4.1.11",
+		"@kuckit/sdk": "^1.0.0",
+		"@__APP_NAME_KEBAB__/api": "workspace:*",
+		"@__APP_NAME_KEBAB__/auth": "workspace:*",
+		"@__APP_NAME_KEBAB__/db": "workspace:*"
 	},
 	"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/app.ts

@@ -0,0 +1,20 @@
+import express, { type Express } from 'express'
+import cors from 'cors'
+
+/**
+ * Create and configure Express app
+ */
+export const createApp = (): Express => {
+	const app = express()
+
+	app.use(
+		cors({
+			origin: process.env.CORS_ORIGIN || 'http://localhost:3001',
+			methods: ['GET', 'POST', 'OPTIONS'],
+			allowedHeaders: ['Content-Type', 'Authorization'],
+			credentials: true,
+		})
+	)
+
+	return app
+}

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

@@ -0,0 +1,10 @@
+import { auth } from '@__APP_NAME_KEBAB__/auth'
+import { toNodeHandler } from 'better-auth/node'
+import type { Express } from 'express'
+
+/**
+ * Setup Better-Auth routes
+ */
+export const setupAuth = (app: Express) => {
+	app.all('/api/auth{/*path}', toNodeHandler(auth))
+}

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

@@ -0,0 +1,22 @@
+import type { ModuleSpec } from '@kuckit/sdk'
+
+// Import your modules here
+// import { kuckitModule as itemsModule } from '@__APP_NAME_KEBAB__/items-module'
+
+/**
+ * Module specifications for the server application
+ *
+ * Add modules here to configure the server's functionality.
+ * Modules are loaded in order, with dependencies resolved automatically.
+ */
+export const getModuleSpecs = (): ModuleSpec[] => {
+	const modules: ModuleSpec[] = [
+		// Add your modules here:
+		// {
+		//   module: itemsModule,
+		//   config: { ... },
+		// },
+	]
+
+	return modules
+}

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

@@ -0,0 +1,81 @@
+import type { AwilixContainer } from 'awilix'
+import {
+	createKuckitContainer,
+	loadKuckitModules,
+	type CoreConfig,
+	type CoreCradle,
+} from '@kuckit/sdk'
+import type { Pool } from 'pg'
+import { ensureDatabaseUrl } from '@__APP_NAME_KEBAB__/db/connection'
+import { getModuleSpecs } from './config/modules'
+import { wireModuleRpcRouters } from './rpc-router-registry'
+
+/**
+ * Server configuration
+ */
+export interface ServerConfig extends CoreConfig {
+	port: number
+	corsOrigin: string
+}
+
+/**
+ * Server DI container cradle
+ */
+export interface ServerCradle extends CoreCradle {
+	config: ServerConfig
+	dbPool: Pool
+}
+
+export type AppContainer = AwilixContainer<ServerCradle>
+export type { ServerConfig as Config, ServerCradle as Cradle }
+
+/**
+ * Load configuration from environment
+ */
+const loadConfig = (): ServerConfig => {
+	const databaseUrl = ensureDatabaseUrl()
+
+	return {
+		databaseUrl,
+		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',
+	}
+}
+
+/**
+ * Build root container with all modules
+ */
+export const buildRootContainer = async (): Promise<AppContainer> => {
+	const config = loadConfig()
+
+	const container = await createKuckitContainer({ config })
+
+	await loadKuckitModules({
+		container,
+		env: config.env,
+		modules: getModuleSpecs(),
+		onApiRegistrations: (registrations) => {
+			wireModuleRpcRouters(registrations)
+			console.log(`Loaded ${registrations.length} API registrations from modules`)
+		},
+		onComplete: () => {
+			console.log('All modules loaded successfully')
+		},
+	})
+
+	return container as AppContainer
+}
+
+/**
+ * Cleanup container resources
+ */
+export const disposeContainer = async (container: AppContainer): Promise<void> => {
+	const { dbPool } = container.cradle
+	if (dbPool && typeof dbPool.end === 'function') {
+		await dbPool.end()
+	}
+}

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

@@ -0,0 +1,27 @@
+import type { Express } from 'express'
+import type { AppContainer } from './container'
+
+export const setupHealth = (app: Express, container: AppContainer) => {
+	app.get('/health', async (_req, res) => {
+		const { dbPool } = container.cradle
+
+		try {
+			const client = await dbPool.connect()
+			await client.query('SELECT 1')
+			client.release()
+
+			res.status(200).json({
+				status: 'healthy',
+				timestamp: new Date().toISOString(),
+				checks: { database: 'ok' },
+			})
+		} catch (error) {
+			console.error('[Health] Database check failed:', error)
+			res.status(503).json({
+				status: 'unhealthy',
+				timestamp: new Date().toISOString(),
+				checks: { database: 'failed' },
+			})
+		}
+	})
+}

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

@@ -0,0 +1,41 @@
+import type { Express, Request, Response, NextFunction } from 'express'
+import { asValue } from 'awilix'
+import { buildRootContainer, type AppContainer } from '../container'
+
+let rootContainer: AppContainer
+
+/**
+ * Initialize and setup container middleware
+ * Must be awaited before using the container
+ */
+export const setupContainerMiddleware = async (app: Express): Promise<void> => {
+	rootContainer = await buildRootContainer()
+
+	app.use((req: Request, res: Response, next: NextFunction) => {
+		req.scope = rootContainer.createScope()
+
+		req.scope.register({
+			requestId: asValue(crypto.randomUUID()),
+		})
+
+		res.on('finish', () => {
+			req.scope?.dispose()
+		})
+
+		res.on('close', () => {
+			req.scope?.dispose()
+		})
+
+		next()
+	})
+}
+
+/**
+ * Get root container (for graceful shutdown)
+ */
+export const getRootContainer = (): AppContainer => {
+	if (!rootContainer) {
+		throw new Error('Container not initialized')
+	}
+	return rootContainer
+}

package/templates/base/apps/server/src/rpc-router-registry.ts

@@ -0,0 +1,26 @@
+import type { ApiRegistration } from '@kuckit/sdk'
+
+/**
+ * Central mutable RPC router object used by RPCHandler.
+ *
+ * Module routers are wired into this object during the SDK loader's
+ * "wire" phase, before RPCHandler is instantiated.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const rootRpcRouter: Record<string, any> = {}
+
+/**
+ * Wire module RPC routers into the central router object.
+ * Called from the SDK loader's onApiRegistrations callback.
+ */
+export const wireModuleRpcRouters = (registrations: ApiRegistration[]): void => {
+	for (const reg of registrations) {
+		if (reg.type !== 'rpc-router') continue
+
+		if (rootRpcRouter[reg.name]) {
+			throw new Error(`Duplicate RPC router name: "${reg.name}"`)
+		}
+
+		rootRpcRouter[reg.name] = reg.router
+	}
+}

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

@@ -0,0 +1,31 @@
+import { RPCHandler } from '@orpc/server/node'
+import { onError } from '@orpc/server'
+import { createContext } from '@__APP_NAME_KEBAB__/api'
+import type { Express } from 'express'
+import { rootRpcRouter } from './rpc-router-registry'
+
+/**
+ * Setup oRPC handler
+ *
+ * IMPORTANT: This must be called AFTER setupContainerMiddleware() has completed,
+ * which ensures all module routers have been wired into rootRpcRouter.
+ */
+export const setupRPC = (app: Express) => {
+	const rpcHandler = new RPCHandler(rootRpcRouter, {
+		interceptors: [
+			onError((error) => {
+				console.error('[RPC Error]', error)
+			}),
+		],
+	})
+
+	app.use(async (req, res, next) => {
+		const result = await rpcHandler.handle(req, res, {
+			prefix: '/rpc',
+			context: await createContext({ req }),
+		})
+
+		if (result.matched) return
+		next()
+	})
+}

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

@@ -1,21 +1,49 @@
 import 'dotenv/config'
-import express from 'express'
-import cors from 'cors'
+import { createApp } from './app'
+import { setupContainerMiddleware, getRootContainer } from './middleware/container'
+import { setupAuth } from './auth'
+import { setupRPC } from './rpc'
+import { setupHealth } from './health'
+import { disposeContainer } from './container'
 
-const app = express()
-const port = process.env.PORT ?? 3000
+/**
+ * Bootstrap and start server
+ */
+const bootstrap = async () => {
+	const app = createApp()
 
-app.use(cors())
-app.use(express.json())
+	await setupContainerMiddleware(app)
+	const rootContainer = getRootContainer()
 
-// Health check
-app.get('/health', (_req, res) => {
-	res.json({ status: 'ok' })
-})
+	setupAuth(app)
+	setupRPC(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)
+	}
 
-// TODO: Kuckit SDK integration will be added in future version
-// See: https://kuckit.dev/docs/getting-started
+	process.on('SIGTERM', shutdown)
+	process.on('SIGINT', shutdown)
+}
 
-app.listen(port, () => {
-	console.log(`Server running at http://localhost:${port}`)
+bootstrap().catch((error) => {
+	console.error('Failed to start server:', error)
+	process.exit(1)
 })

package/templates/base/apps/web/.env.example

@@ -0,0 +1,4 @@
+# Web Environment Variables
+
+# API URL for the backend server
+VITE_API_URL=http://localhost:3000

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

@@ -0,0 +1,127 @@
+# AGENTS.md - Web App
+
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
+
+## Purpose
+
+React frontend using TanStack Router, TanStack Query, and Kuckit client modules.
+
+## Key Files
+
+| File                               | Purpose                           |
+| ---------------------------------- | --------------------------------- |
+| `main.tsx`                         | App entry point                   |
+| `modules.client.ts`                | Client module registration        |
+| `providers/KuckitProvider.tsx`     | Kuckit context setup              |
+| `providers/ServicesProvider.tsx`   | Services context (RPC, auth)      |
+| `routes/`                          | TanStack Router file-based routes |
+| `routes/$.tsx`                     | Catch-all for module routes       |
+| `components/KuckitModuleRoute.tsx` | Renders module-registered routes  |
+
+## Adding Routes
+
+Create files in `src/routes/`:
+
+- `src/routes/about.tsx` → `/about`
+- `src/routes/users/$id.tsx` → `/users/:id`
+- `src/routes/settings/index.tsx` → `/settings`
+
+**File-based routes take precedence** over module-registered routes.
+
+## Module Route Integration
+
+Modules register routes via `defineKuckitClientModule`. These are rendered via a catch-all pattern:
+
+1. Module registers route in `routes` array
+2. `RouteRegistry` collects routes during `loadKuckitClientModules()`
+3. Catch-all route (`$.tsx`) matches any unhandled path
+4. `KuckitModuleRoute` looks up path in registry and renders the component
+
+```tsx
+// routes/$.tsx - Catches module routes
+import { KuckitModuleRoute } from '@/components/KuckitModuleRoute'
+
+export function Route() {
+	return <KuckitModuleRoute />
+}
+```
+
+## Context Providers
+
+The app wraps content in Kuckit providers:
+
+```tsx
+<ServicesProvider>
+	{' '}
+	{/* RPC client, auth */}
+	<KuckitProvider>
+		{' '}
+		{/* Nav, slots, routes registries */}
+		<KuckitRpcProvider>
+			{' '}
+			{/* RPC context for modules */}
+			{children}
+		</KuckitRpcProvider>
+	</KuckitProvider>
+</ServicesProvider>
+```
+
+**Available hooks:**
+
+- `useRpc<T>()` - Get typed RPC client for API calls
+- `useNavItems()` - Flat navigation items list
+- `useNavTree()` - Hierarchical navigation tree
+- `useSlot(name)` - Get components for a slot
+- `useHasSlot(name)` - Check if slot has content
+
+## useRpc Hook
+
+Module components must use `useRpc()` to access the API:
+
+```tsx
+import { useRpc } from '@kuckit/sdk-react'
+import { useQuery } from '@tanstack/react-query'
+
+interface MyRpc {
+	items: { list: (input: {}) => Promise<Item[]> }
+}
+
+function MyComponent() {
+	const rpc = useRpc<MyRpc>()
+
+	const { data } = useQuery({
+		queryKey: ['items'],
+		queryFn: () => rpc.items.list({}),
+	})
+}
+```
+
+**Important**: Never use `import.meta.env.VITE_SERVER_URL` directly in module components - it's unavailable in external packages. The `useRpc` hook provides the correctly-configured client.
+
+## Using Module UI Components
+
+```tsx
+import { ItemsPage } from '@__APP_NAME_KEBAB__/items-module/ui'
+
+// In your route component
+export function Route() {
+	return <ItemsPage />
+}
+```
+
+## Adding Client Modules
+
+1. Import in `modules.client.ts`:
+
+   ```typescript
+   import { kuckitClientModule as myClientModule } from '@__APP_NAME_KEBAB__/my-module/client'
+
+   export const clientModules = [
+   	itemsClientModule,
+   	myClientModule, // Add here
+   ]
+   ```
+
+## Environment Variables
+
+See `.env.example` in this directory.

package/templates/base/apps/web/index.html

@@ -6,7 +6,7 @@
 		<title>__APP_NAME__</title>
 	</head>
 	<body>
-		<div id="root"></div>
+		<div id="app"></div>
 		<script type="module" src="/src/main.tsx"></script>
 	</body>
 </html>

package/templates/base/apps/web/package.json

@@ -1,5 +1,7 @@
 {
-	"name": "__APP_NAME_KEBAB__-web",
+	"name": "@__APP_NAME_KEBAB__/web",
+	"version": "0.0.1",
+	"private": true,
 	"type": "module",
 	"scripts": {
 		"dev": "vite --port=3001",
@@ -7,11 +9,22 @@
 		"check-types": "tsc --noEmit"
 	},
 	"dependencies": {
+		"@kuckit/sdk-react": "^1.0.0",
+		"@orpc/client": "^1.10.0",
+		"@orpc/tanstack-query": "^1.10.0",
 		"@tanstack/react-query": "^5.85.5",
+		"@tanstack/react-router": "^1.114.25",
+		"better-auth": "^1.3.28",
 		"react": "^19.1.0",
-		"react-dom": "^19.1.0"
+		"react-dom": "^19.1.0",
+		"zod": "^4.1.11",
+		"@__APP_NAME_KEBAB__/auth": "workspace:*"
 	},
 	"devDependencies": {
+		"@tanstack/react-router-devtools": "^1.114.27",
+		"@tanstack/router-plugin": "^1.114.27",
+		"@tanstack/react-query-devtools": "^5.85.5",
+		"@types/node": "^22.13.13",
 		"@types/react": "~19.1.10",
 		"@types/react-dom": "^19.0.4",
 		"@vitejs/plugin-react": "^4.3.4",