create-kuckit-app 0.3.5 → 0.4.1

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

@@ -8,86 +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 |
-| `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 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
-		}
-	}
-}
-```
+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()
-	},
-})
-
-setupRPC(app) // Now create handler with fully-wired router
-```
-
-## Per-Request Scoping
+import 'dotenv/config'
+import { runKuckitServer } from '@kuckit/app-server'
+import { loadConfig } from './config'
+import { getModuleSpecs } from './modules'
 
-Each HTTP request gets a scoped container with:
+runKuckitServer({ loadConfig, getModuleSpecs }).catch(console.error)
+```
 
-- `requestId` - Unique request identifier
-- `requestLogger` - Logger with request context
-- `session` - Current user session (if authenticated)
+The `@kuckit/app-server` package handles:
 
-Access scoped services in routers via `context.di.cradle`.
+- 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
 
 ## Adding New Modules
 
-1. Install the module package
-2. Add to `config/modules.ts`:
+**`kuckit.config.ts` is the single source of truth for modules.**
+
+1. Add to `kuckit.config.ts` (at project root):
 
    ```typescript
-   import { kuckitModule as myModule } from '@__APP_NAME_KEBAB__/my-module'
+   export default defineConfig({
+   	modules: [
+   		{ package: '@__APP_NAME_KEBAB__/items-module' },
+   		{ package: '@acme/billing-module' }, // Add new module here
+   	],
+   })
+   ```
+
+2. Add import and mapping to `modules.ts`:
 
-   export const getModuleSpecs = () => [
-   	{ module: itemsModule },
-   	{ module: myModule }, // Add here
-   ]
+   ```typescript
+   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.2.2",
-		"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:*"
+		"dotenv": "^17.0.0",
+		"@kuckit/app-server": "^2.0.0",
+		"@kuckit/sdk": "^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,49 +1,9 @@
 import 'dotenv/config'
-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'
+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)
-	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)
 })

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

@@ -10,118 +10,96 @@ React frontend using TanStack Router, TanStack Query, and Kuckit client modules.
 
 | File                               | Purpose                           |
 | ---------------------------------- | --------------------------------- |
-| `main.tsx`                         | App entry point                   |
+| `main.tsx`                         | App entry point (17 lines)        |
 | `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.
+## How It Works
 
-## 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
+The web app uses `@kuckit/app-web` which provides a provider factory:
 
 ```tsx
-// routes/$.tsx - Catches module routes
-import { KuckitModuleRoute } from '@/components/KuckitModuleRoute'
-
-export function Route() {
-	return <KuckitModuleRoute />
-}
+// main.tsx
+import ReactDOM from 'react-dom/client'
+import { createKuckitWebProvider } from '@kuckit/app-web'
+import { routeTree } from './routeTree.gen'
+import { Route as rootRoute } from './routes/__root'
+import { getClientModuleSpecs } from './modules.client'
+import './index.css'
+
+const KuckitApp = createKuckitWebProvider({
+	serverUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000',
+	modules: getClientModuleSpecs(),
+	env: import.meta.env.MODE,
+	routeTree,
+	rootRoute,
+})
+
+const rootEl = document.getElementById('app')!
+ReactDOM.createRoot(rootEl).render(<KuckitApp />)
 ```
 
-## Context Providers
-
-The app wraps content in Kuckit providers:
+The `@kuckit/app-web` package handles:
 
-```tsx
-<ServicesProvider>
-	{' '}
-	{/* RPC client, auth */}
-	<KuckitProvider>
-		{' '}
-		{/* Nav, slots, routes registries */}
-		<KuckitRpcProvider>
-			{' '}
-			{/* RPC context for modules */}
-			{children}
-		</KuckitRpcProvider>
-	</KuckitProvider>
-</ServicesProvider>
-```
+- RPC client and oRPC utils creation
+- React Query client setup
+- Better-Auth client integration
+- Module loading and route registration
+- Navigation and slot registries
+- Provider composition
 
-**Available hooks:**
+## 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
+Import from `@kuckit/app-web`:
 
-## useRpc Hook
+- `useAuth()` - Auth client for sign in/out, session
+- `useRpc()` - Typed RPC client for API calls
+- `useOrpc()` - oRPC TanStack Query utils
+- `useQueryClient()` - React Query client
+- `useKuckitWeb()` - Full context with registries
 
-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[]> }
-}
+## Adding Routes
 
-function MyComponent() {
-	const rpc = useRpc<MyRpc>()
+Create files in `src/routes/`:
 
-	const { data } = useQuery({
-		queryKey: ['items'],
-		queryFn: () => rpc.items.list({}),
-	})
-}
-```
+- `src/routes/about.tsx` → `/about`
+- `src/routes/users/$id.tsx` → `/users/:id`
+- `src/routes/settings/index.tsx` → `/settings`
 
-**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.
+**File-based routes take precedence** over module-registered routes.
 
-## Using Module UI Components
+## Adding Client Modules
 
-```tsx
-import { ItemsPage } from '@__APP_NAME_KEBAB__/items-module/ui'
+**`kuckit.config.ts` is the single source of truth for modules.**
 
-// In your route component
-export function Route() {
-	return <ItemsPage />
-}
-```
+1. Add to `kuckit.config.ts` (at project root):
 
-## Adding Client Modules
+   ```typescript
+   export default defineConfig({
+   	modules: [
+   		{ package: '@__APP_NAME_KEBAB__/items-module' },
+   		{ package: '@acme/billing-module' }, // Add new module here
+   	],
+   })
+   ```
 
-1. Import in `modules.client.ts`:
+2. Add import and mapping to `modules.client.ts`:
 
    ```typescript
-   import { kuckitClientModule as myClientModule } from '@__APP_NAME_KEBAB__/my-module/client'
-
-   export const clientModules = [
-   	itemsClientModule,
-   	myClientModule, // Add here
-   ]
+   import { kuckitClientModule as billingClientModule } from '@acme/billing-module/client'
+
+   const KNOWN_CLIENT_MODULES = {
+   	// ...existing
+   	'@acme/billing-module': {
+   		module: billingClientModule,
+   	},
+   }
    ```
 
+The CLI command `bunx kuckit add @acme/billing-module` automates both steps.
+
 ## Environment Variables
 
 See `.env.example` in this directory.

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

@@ -9,9 +9,8 @@
 		"check-types": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@kuckit/sdk-react": "^1.0.0",
-		"@orpc/client": "^1.10.0",
-		"@orpc/tanstack-query": "^1.10.0",
+		"@kuckit/app-web": "^2.0.0",
+		"@kuckit/sdk-react": "^2.0.0",
 		"@radix-ui/react-avatar": "^1.1.10",
 		"@radix-ui/react-collapsible": "^1.1.11",
 		"@radix-ui/react-dialog": "^1.1.14",
@@ -19,17 +18,14 @@
 		"@radix-ui/react-separator": "^1.1.7",
 		"@radix-ui/react-slot": "^1.2.3",
 		"@radix-ui/react-tooltip": "^1.2.7",
-		"@tanstack/react-query": "^5.85.5",
-		"@tanstack/react-router": "^1.114.25",
-		"better-auth": "^1.3.28",
+		"@tanstack/react-query": "^5.0.0",
+		"@tanstack/react-router": "^1.114.0",
 		"class-variance-authority": "^0.7.1",
 		"clsx": "^2.1.1",
 		"lucide-react": "^0.511.0",
-		"react": "^19.1.0",
-		"react-dom": "^19.1.0",
-		"tailwind-merge": "^3.3.0",
-		"zod": "^4.1.11",
-		"@__APP_NAME_KEBAB__/auth": "workspace:*"
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"tailwind-merge": "^3.0.0"
 	},
 	"devDependencies": {
 		"@tailwindcss/vite": "^4.0.15",

package/templates/base/apps/web/src/components/KuckitModuleRoute.tsx

@@ -1,6 +1,5 @@
 import { useRouterState, Link, useNavigate } from '@tanstack/react-router'
-import { useKuckit } from '@/providers/KuckitProvider'
-import { useServices } from '@/providers/ServicesProvider'
+import { useKuckitWeb, useAuth } from '@kuckit/app-web'
 import { useEffect, useState } from 'react'
 
 /**
@@ -24,8 +23,8 @@ function isRootLevelRoute(path: string): boolean {
  * For root routes with meta.requiresAuth: true, redirects to /login if not authenticated.
  */
 export function KuckitModuleRoute() {
-	const { routeRegistry } = useKuckit()
-	const { authClient } = useServices()
+	const { routeRegistry } = useKuckitWeb()
+	const authClient = useAuth()
 	const { location } = useRouterState()
 	const navigate = useNavigate()
 	const pathname = location.pathname
@@ -47,11 +46,34 @@ export function KuckitModuleRoute() {
 	// For dashboard context, also try matching with /dashboard prefix stripped
 	const modulePathname = isDashboardContext ? pathname.replace('/dashboard', '') || '/' : pathname
 
-	// Find matching route
-	let routeDef = contextRoutes.find((r) => r.path === pathname)
+	// Match route path against pathname, supporting catch-all patterns like /docs/$
+	function matchRoute(routePath: string, pathname: string): boolean {
+		// Exact match
+		if (routePath === pathname) return true
+
+		// Catch-all pattern: /docs/$ matches /docs/anything/here
+		if (routePath.endsWith('/$')) {
+			const base = routePath.slice(0, -1) // Remove trailing $
+			return pathname.startsWith(base)
+		}
+
+		return false
+	}
+
+	// Find matching route - prefer exact matches over catch-all
+	const exactMatch = contextRoutes.find((r) => r.path === pathname)
+	const catchAllMatch = contextRoutes.find(
+		(r) => r.path.endsWith('/$') && matchRoute(r.path, pathname)
+	)
+	let routeDef = exactMatch || catchAllMatch
+
 	if (!routeDef && isDashboardContext) {
 		// For dashboard routes, also try matching stripped path
-		routeDef = contextRoutes.find((r) => r.path === modulePathname)
+		const exactDash = contextRoutes.find((r) => r.path === modulePathname)
+		const catchAllDash = contextRoutes.find(
+			(r) => r.path.endsWith('/$') && matchRoute(r.path, modulePathname)
+		)
+		routeDef = exactDash || catchAllDash
 	}
 
 	// Check auth for root routes with requiresAuth

package/templates/base/apps/web/src/components/dashboard/dashboard-overview.tsx

@@ -1,7 +1,7 @@
-import { useServices } from '@/providers/ServicesProvider'
+import { useAuth } from '@kuckit/app-web'
 
 export function DashboardOverview() {
-	const { authClient } = useServices()
+	const authClient = useAuth()
 	const { data: session } = authClient.useSession()
 
 	return (

package/templates/base/apps/web/src/components/dashboard/nav-user.tsx

@@ -1,6 +1,6 @@
 import { ChevronsUpDown, LogOut, User } from 'lucide-react'
 import { useNavigate } from '@tanstack/react-router'
-import { useServices } from '@/providers/ServicesProvider'
+import { useAuth } from '@kuckit/app-web'
 import {
 	DropdownMenu,
 	DropdownMenuContent,
@@ -19,7 +19,7 @@ import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar'
 export function NavUser() {
 	const { isMobile } = useSidebar()
 	const navigate = useNavigate()
-	const { authClient } = useServices()
+	const authClient = useAuth()
 	const { data: session } = authClient.useSession()
 
 	const user = session?.user

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

@@ -1,27 +1,17 @@
-import { createRouter } from '@tanstack/react-router'
 import ReactDOM from 'react-dom/client'
+import { createKuckitWebProvider } from '@kuckit/app-web'
 import { routeTree } from './routeTree.gen'
-import { ServicesProvider } from './providers/ServicesProvider'
-import { KuckitProvider } from './providers/KuckitProvider'
+import { Route as rootRoute } from './routes/__root'
+import { getClientModuleSpecs } from './modules.client'
 import './index.css'
 
-declare module '@tanstack/react-router' {
-	interface Register {
-		router: ReturnType<typeof createRouter<typeof routeTree>>
-	}
-}
+const KuckitApp = createKuckitWebProvider({
+	serverUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000',
+	modules: getClientModuleSpecs(),
+	env: import.meta.env.MODE,
+	routeTree,
+	rootRoute,
+})
 
-const rootElement = document.getElementById('app')
-
-if (!rootElement) {
-	throw new Error('Root element not found')
-}
-
-if (!rootElement.innerHTML) {
-	const root = ReactDOM.createRoot(rootElement)
-	root.render(
-		<ServicesProvider>
-			<KuckitProvider />
-		</ServicesProvider>
-	)
-}
+const rootEl = document.getElementById('app')!
+ReactDOM.createRoot(rootEl).render(<KuckitApp />)