create-kuckit-app 0.2.0 → 0.3.0

package/package.json

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

package/templates/base/AGENTS.md

@@ -71,6 +71,209 @@ adapters → Implements ports, depends on domain
 api → Wires everything together
 ```
 
+## SDK Module System
+
+> **SDK Documentation**: For comprehensive module patterns, see [@kuckit/sdk](https://github.com/draphonix/kuckit)
+
+### Module Lifecycle
+
+Modules are loaded in a specific sequence:
+
+```
+1. createKuckitContainer()
+   └─► Core services registered (logger, db, cache, eventBus)
+
+2. loadKuckitModules({ modules: [...] })
+   ├─► Phase 1: register() - DI bindings for all modules
+   ├─► Phase 2: registerApi() - API registrations collected
+   ├─► Phase 3: onApiRegistrations callback (wire routers HERE)
+   ├─► Phase 4: onBootstrap() - Startup logic
+   └─► Phase 5: onComplete callback
+
+3. Application runs...
+
+4. disposeContainer()
+   └─► For each module: onShutdown()
+```
+
+### Core Services (CoreCradle)
+
+After container creation, these services are available via DI:
+
+| Token              | Type               | Lifetime  | Description                 |
+| ------------------ | ------------------ | --------- | --------------------------- |
+| `config`           | `CoreConfig`       | Singleton | Application configuration   |
+| `db`               | Drizzle            | Singleton | Database query builder      |
+| `dbPool`           | `Pool`             | Singleton | PostgreSQL connection pool  |
+| `logger`           | `Logger`           | Singleton | Structured logging          |
+| `eventBus`         | `EventBus`         | Singleton | Pub/sub event system        |
+| `clock`            | `Clock`            | Singleton | Time abstraction (testable) |
+| `cacheStore`       | `CacheStore`       | Singleton | Key-value cache             |
+| `rateLimiterStore` | `RateLimiterStore` | Singleton | Rate limiting               |
+| `auth`             | Better-Auth        | Singleton | Authentication utilities    |
+| `requestId`        | `string`           | Scoped    | Per-request unique ID       |
+| `requestLogger`    | `Logger`           | Scoped    | Logger with request context |
+
+### Server Module Definition
+
+```typescript
+import { defineKuckitModule, asClass, asFunction } from '@kuckit/sdk'
+
+export const kuckitModule = defineKuckitModule({
+	id: 'myapp.billing',
+	displayName: 'Billing',
+	version: '1.0.0',
+	capabilities: ['nav.item', 'api.public'],
+
+	register(ctx) {
+		// Phase 1: Register DI bindings
+		ctx.container.register({
+			invoiceRepository: asClass(InvoiceRepository).scoped(),
+			createInvoice: asFunction(makeCreateInvoiceUseCase).scoped(),
+		})
+	},
+
+	registerApi(ctx) {
+		// Phase 2: Register API routes
+		ctx.addApiRegistration({
+			type: 'rpc-router',
+			name: 'invoices',
+			router: invoicesRouter,
+		})
+	},
+
+	onBootstrap(ctx) {
+		// Phase 4: Startup logic (cache warming, logging, etc.)
+		ctx.container.resolve('logger').info('Billing module started')
+	},
+
+	onShutdown(ctx) {
+		// Cleanup on shutdown
+		ctx.container.resolve('logger').info('Billing module stopped')
+	},
+})
+```
+
+### Client Module Definition
+
+```typescript
+import { defineKuckitClientModule } from '@kuckit/sdk-react'
+
+export const kuckitClientModule = defineKuckitClientModule({
+	id: 'myapp.billing',
+	displayName: 'Billing',
+	capabilities: ['nav.item', 'dashboard.widget'],
+
+	routes: [
+		{
+			id: 'billing-invoices',
+			path: '/billing/invoices',
+			component: InvoicesPage,
+		},
+	],
+
+	navItems: [
+		{
+			id: 'billing-nav',
+			label: 'Billing',
+			href: '/billing/invoices',
+			icon: CreditCard,
+			order: 50,
+		},
+	],
+
+	slots: {
+		'dashboard.widgets': {
+			component: BillingWidget,
+			order: 10,
+		},
+	},
+})
+```
+
+### Module Capabilities
+
+Modules can declare capabilities for discovery:
+
+- `nav.item` - Provides navigation items
+- `settings.page` - Has settings page
+- `dashboard.widget` - Provides dashboard widgets
+- `api.webhook` - Exposes webhooks
+- `api.public` - Has public API endpoints
+- `slot.provider` - Provides slot components
+
+### useRpc with TanStack Query
+
+Module components use the `useRpc` hook to access the API:
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { useRpc } from '@kuckit/sdk-react'
+
+interface ItemsRpc {
+	items: {
+		list: (input: Record<string, never>) => Promise<Item[]>
+		create: (input: { name: string }) => Promise<Item>
+	}
+}
+
+function ItemsPage() {
+	const rpc = useRpc<ItemsRpc>()
+	const queryClient = useQueryClient()
+
+	const { data: items = [], isLoading } = useQuery({
+		queryKey: ['items'],
+		queryFn: () => rpc.items.list({}),
+	})
+
+	const createMutation = useMutation({
+		mutationFn: (data: { name: string }) => rpc.items.create(data),
+		onSuccess: () => queryClient.invalidateQueries({ queryKey: ['items'] }),
+	})
+
+	// ... component render
+}
+```
+
+### oRPC Router Wiring (Important)
+
+oRPC's `RPCHandler` captures the router object at construction time. Module routers must be wired **before** the handler is created:
+
+1. Modules register routers via `registerApi()` hook
+2. Server wires routers in `onApiRegistrations` into a **mutable router object**
+3. `RPCHandler` is created **after** modules are loaded
+
+```typescript
+// apps/server/src/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
+		}
+	}
+}
+```
+
+### Typing DI in Routers
+
+Use a module-local interface to type `context.di.cradle`:
+
+```typescript
+// In your module's router file
+interface BillingCradle {
+	createInvoice: (input: CreateInvoiceInput) => Promise<Invoice>
+}
+
+export const invoicesRouter = {
+	create: protectedProcedure.input(createInvoiceSchema).handler(async ({ input, context }) => {
+		const { createInvoice } = context.di.cradle as BillingCradle
+		return createInvoice(input)
+	}),
+}
+```
+
 ## Common Tasks
 
 ### Add a new API endpoint

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

@@ -1,6 +1,6 @@
 # AGENTS.md - Server App
 
-> See root [AGENTS.md](../../AGENTS.md) for project overview
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
 
 ## Purpose
 
@@ -8,13 +8,69 @@ 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        |
-| `auth.ts`           | Better-Auth configuration |
+| 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
 

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

@@ -1,6 +1,6 @@
 # AGENTS.md - Web App
 
-> See root [AGENTS.md](../../AGENTS.md) for project overview
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
 
 ## Purpose
 
@@ -8,13 +8,15 @@ 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 |
+| 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
 
@@ -24,6 +26,78 @@ Create files in `src/routes/`:
 - `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

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

@@ -0,0 +1,119 @@
+import { useRouterState, Link, useNavigate } from '@tanstack/react-router'
+import { useKuckit } from '@/providers/KuckitProvider'
+import { useServices } from '@/providers/ServicesProvider'
+import { useEffect, useState } from 'react'
+
+/**
+ * Helper to determine if a route path is a root-level route (outside dashboard).
+ * Root routes start with '/' but NOT '/dashboard'.
+ */
+function isRootLevelRoute(path: string): boolean {
+	return path.startsWith('/') && !path.startsWith('/dashboard')
+}
+
+/**
+ * Dynamic route renderer for Kuckit module routes.
+ *
+ * This component looks up the current path in the RouteRegistry
+ * and renders the corresponding module component if found.
+ *
+ * Route resolution is context-aware:
+ * - When rendered under /dashboard/*: matches dashboard routes
+ * - When rendered at root level: matches root-level routes (paths starting with '/' but not '/dashboard/')
+ *
+ * For root routes with meta.requiresAuth: true, redirects to /login if not authenticated.
+ */
+export function KuckitModuleRoute() {
+	const { routeRegistry } = useKuckit()
+	const { authClient } = useServices()
+	const { location } = useRouterState()
+	const navigate = useNavigate()
+	const pathname = location.pathname
+
+	const [authChecked, setAuthChecked] = useState(false)
+	const [isAuthenticated, setIsAuthenticated] = useState(false)
+
+	// Determine if we're in dashboard context
+	const isDashboardContext = pathname.startsWith('/dashboard')
+
+	// Filter routes based on context
+	const contextRoutes = routeRegistry.getAll().filter((r) => {
+		const isRoot = isRootLevelRoute(r.path)
+		// In dashboard context: show non-root routes
+		// In root context: show root routes
+		return isDashboardContext ? !isRoot : isRoot
+	})
+
+	// 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)
+	if (!routeDef && isDashboardContext) {
+		// For dashboard routes, also try matching stripped path
+		routeDef = contextRoutes.find((r) => r.path === modulePathname)
+	}
+
+	// Check auth for root routes with requiresAuth
+	useEffect(() => {
+		async function checkAuth() {
+			if (!routeDef) {
+				setAuthChecked(true)
+				return
+			}
+
+			// Dashboard routes are already protected by the dashboard layout
+			if (isDashboardContext) {
+				setAuthChecked(true)
+				setIsAuthenticated(true)
+				return
+			}
+
+			// For root routes, check if auth is required
+			if (routeDef.meta?.requiresAuth) {
+				const session = await authClient.getSession()
+				if (!session.data) {
+					// Redirect to login with return URL
+					navigate({
+						to: '/login',
+						search: { redirect: pathname },
+					})
+					return
+				}
+				setIsAuthenticated(true)
+			}
+			setAuthChecked(true)
+		}
+
+		checkAuth()
+	}, [routeDef, isDashboardContext, pathname, navigate, authClient])
+
+	// Show loading while checking auth for protected root routes
+	if (!isDashboardContext && routeDef?.meta?.requiresAuth && !authChecked) {
+		return (
+			<div className="flex items-center justify-center min-h-screen">
+				<div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary" />
+			</div>
+		)
+	}
+
+	// Protected root route - waiting for redirect
+	if (!isDashboardContext && routeDef?.meta?.requiresAuth && !isAuthenticated) {
+		return null
+	}
+
+	if (!routeDef) {
+		return (
+			<div className="flex flex-col items-center justify-center min-h-[50vh] gap-4">
+				<h1 className="text-2xl font-bold">Page Not Found</h1>
+				<p className="text-muted-foreground">The page "{pathname}" could not be found.</p>
+				<Link to="/" className="text-primary hover:underline">
+					Go Home
+				</Link>
+			</div>
+		)
+	}
+
+	const Component = routeDef.component as React.ComponentType
+	return <Component />
+}

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

@@ -0,0 +1,120 @@
+import { Link, useRouterState } from '@tanstack/react-router'
+import { LayoutDashboard, Settings, Blocks, type LucideIcon } from 'lucide-react'
+import { useKuckitNav } from '@kuckit/sdk-react'
+import {
+	Sidebar,
+	SidebarContent,
+	SidebarFooter,
+	SidebarGroup,
+	SidebarGroupContent,
+	SidebarGroupLabel,
+	SidebarHeader,
+	SidebarMenu,
+	SidebarMenuButton,
+	SidebarMenuItem,
+	SidebarRail,
+} from '@/components/ui/sidebar'
+import { NavUser } from './nav-user'
+
+const iconMap: Record<string, LucideIcon> = {
+	'layout-dashboard': LayoutDashboard,
+	settings: Settings,
+	blocks: Blocks,
+}
+
+const coreNavItems = [
+	{ label: 'Dashboard', path: '/dashboard', icon: LayoutDashboard },
+	{ label: 'Settings', path: '/dashboard/settings', icon: Settings },
+]
+
+export function AppSidebar() {
+	const navRegistry = useKuckitNav()
+	const pathname = useRouterState({ select: (s) => s.location.pathname })
+
+	const mainNavModuleItems = navRegistry.getMainNavItems()
+	const moduleItems = navRegistry.getModuleNavItems()
+
+	return (
+		<Sidebar collapsible="icon">
+			<SidebarHeader>
+				<div className="flex items-center gap-2 px-2 py-2">
+					<div className="flex h-8 w-8 items-center justify-center rounded-lg bg-gradient-to-br from-primary to-primary/80">
+						<span className="text-sm font-bold text-primary-foreground">K</span>
+					</div>
+					<span className="font-semibold group-data-[collapsible=icon]:hidden">__APP_TITLE__</span>
+				</div>
+			</SidebarHeader>
+
+			<SidebarContent>
+				<SidebarGroup>
+					<SidebarGroupLabel>Navigation</SidebarGroupLabel>
+					<SidebarGroupContent>
+						<SidebarMenu>
+							{coreNavItems.map((item) => (
+								<SidebarMenuItem key={item.path}>
+									<SidebarMenuButton asChild isActive={pathname === item.path} tooltip={item.label}>
+										<Link to={item.path}>
+											<item.icon className="h-4 w-4" />
+											<span>{item.label}</span>
+										</Link>
+									</SidebarMenuButton>
+								</SidebarMenuItem>
+							))}
+
+							{mainNavModuleItems.map((item) => {
+								const Icon = item.icon ? iconMap[item.icon] : Blocks
+								return (
+									<SidebarMenuItem key={item.id}>
+										<SidebarMenuButton
+											asChild
+											isActive={pathname === item.path || pathname.startsWith(item.path + '/')}
+											tooltip={item.label}
+										>
+											<Link to={item.path}>
+												{Icon && <Icon className="h-4 w-4" />}
+												<span>{item.label}</span>
+											</Link>
+										</SidebarMenuButton>
+									</SidebarMenuItem>
+								)
+							})}
+						</SidebarMenu>
+					</SidebarGroupContent>
+				</SidebarGroup>
+
+				{moduleItems.length > 0 && (
+					<SidebarGroup>
+						<SidebarGroupLabel>Modules</SidebarGroupLabel>
+						<SidebarGroupContent>
+							<SidebarMenu>
+								{moduleItems.map((item) => {
+									const Icon = item.icon ? iconMap[item.icon] : Blocks
+									return (
+										<SidebarMenuItem key={item.id}>
+											<SidebarMenuButton
+												asChild
+												isActive={pathname === item.path || pathname.startsWith(item.path + '/')}
+												tooltip={item.label}
+											>
+												<Link to={item.path}>
+													{Icon && <Icon className="h-4 w-4" />}
+													<span>{item.label}</span>
+												</Link>
+											</SidebarMenuButton>
+										</SidebarMenuItem>
+									)
+								})}
+							</SidebarMenu>
+						</SidebarGroupContent>
+					</SidebarGroup>
+				)}
+			</SidebarContent>
+
+			<SidebarFooter>
+				<NavUser />
+			</SidebarFooter>
+
+			<SidebarRail />
+		</Sidebar>
+	)
+}

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

@@ -0,0 +1,46 @@
+import type { ReactNode } from 'react'
+import { SidebarProvider, SidebarInset, SidebarTrigger } from '@/components/ui/sidebar'
+import { AppSidebar } from './app-sidebar'
+import { Separator } from '@/components/ui/separator'
+import {
+	Breadcrumb,
+	BreadcrumbItem,
+	BreadcrumbList,
+	BreadcrumbPage,
+} from '@/components/ui/breadcrumb'
+import { useRouterState } from '@tanstack/react-router'
+
+interface DashboardLayoutProps {
+	children: ReactNode
+}
+
+export function DashboardLayout({ children }: DashboardLayoutProps) {
+	const pathname = useRouterState({ select: (s) => s.location.pathname })
+
+	const pathSegments = pathname.split('/').filter(Boolean)
+	const pageTitle =
+		pathSegments.length > 1
+			? pathSegments[pathSegments.length - 1].charAt(0).toUpperCase() +
+				pathSegments[pathSegments.length - 1].slice(1)
+			: 'Dashboard'
+
+	return (
+		<SidebarProvider>
+			<AppSidebar />
+			<SidebarInset>
+				<header className="flex h-16 shrink-0 items-center gap-2 border-b px-4">
+					<SidebarTrigger className="-ml-1" />
+					<Separator orientation="vertical" className="mr-2 h-4" />
+					<Breadcrumb>
+						<BreadcrumbList>
+							<BreadcrumbItem>
+								<BreadcrumbPage>{pageTitle}</BreadcrumbPage>
+							</BreadcrumbItem>
+						</BreadcrumbList>
+					</Breadcrumb>
+				</header>
+				<main className="flex-1 overflow-auto p-4">{children}</main>
+			</SidebarInset>
+		</SidebarProvider>
+	)
+}