create-kuckit-app 0.4.0 → 1.0.0

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

@@ -1,83 +0,0 @@
-import type { AwilixContainer } from 'awilix'
-import {
-	createKuckitContainer,
-	loadKuckitModules,
-	type CoreConfig,
-	type CoreCradle,
-} from '@kuckit/sdk'
-import type { Pool } from 'pg'
-import { ensureDatabaseUrl } from '@kuckit/db/connection'
-import { getModuleSpecs } from './config/modules'
-import { wireModuleRpcRouters } from './rpc-router-registry'
-import { collectModuleRestRouters } from './rest-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)
-			collectModuleRestRouters(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

@@ -1,27 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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/module-rest-routes.ts

@@ -1,47 +0,0 @@
-import type { Express, Request, Response, NextFunction } from 'express'
-import express from 'express'
-import { asValue } from 'awilix'
-import { fromNodeHeaders } from 'better-auth/node'
-import { auth } from '@kuckit/auth'
-import { getRestRouters } from './rest-router-registry'
-
-/**
- * Middleware to add session to request scope for REST routes.
- * Similar to createContext for RPC, but for Express routes.
- */
-const sessionMiddleware = async (req: Request, _res: Response, next: NextFunction) => {
-	if (!req.scope) {
-		return next(new Error('Request scope not initialized'))
-	}
-
-	try {
-		const session = await auth.api.getSession({
-			headers: fromNodeHeaders(req.headers),
-		})
-
-		req.scope.register({
-			session: asValue(session),
-		})
-
-		next()
-	} catch (error) {
-		console.error('[REST Auth] Failed to get session:', error)
-		req.scope.register({
-			session: asValue(null),
-		})
-		next()
-	}
-}
-
-/**
- * Setup REST routers from modules.
- * Must be called after container middleware is initialized.
- */
-export const setupModuleRestRouters = (app: Express): void => {
-	const routers = getRestRouters()
-
-	for (const { name, router, basePath } of routers) {
-		app.use(`/api${basePath}`, express.json(), sessionMiddleware, router)
-		console.log(`[REST] Mounted module router: /api${basePath} (${name})`)
-	}
-}

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

@@ -1,32 +0,0 @@
-import type { Router } from 'express'
-import type { ApiRegistration } from '@kuckit/sdk'
-
-interface RestRouterEntry {
-	name: string
-	router: Router
-	basePath: string
-}
-
-const restRouters: RestRouterEntry[] = []
-
-/**
- * Collect REST routers from module registrations.
- * Called from the SDK loader's onApiRegistrations callback.
- */
-export const collectModuleRestRouters = (registrations: ApiRegistration[]): void => {
-	for (const reg of registrations) {
-		if (reg.type !== 'rest-router') continue
-
-		const basePath = reg.prefix ?? `/${reg.name}`
-		restRouters.push({
-			name: reg.name,
-			router: reg.router as Router,
-			basePath,
-		})
-	}
-}
-
-/**
- * Get all collected REST routers for wiring to Express app.
- */
-export const getRestRouters = (): readonly RestRouterEntry[] => restRouters

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

@@ -1,26 +0,0 @@
-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

@@ -1,31 +0,0 @@
-import { RPCHandler } from '@orpc/server/node'
-import { onError } from '@orpc/server'
-import { createContext } from '@kuckit/api/context'
-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/web/src/components/KuckitModuleRoute.tsx

@@ -1,119 +0,0 @@
-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/providers/KuckitProvider.tsx

@@ -1,123 +0,0 @@
-import { createContext, useContext, useEffect, useState, useMemo, type ReactNode } from 'react'
-import { RouterProvider, createRouter } from '@tanstack/react-router'
-import {
-	loadKuckitClientModules,
-	KuckitNavProvider,
-	KuckitSlotProvider,
-	KuckitRpcProvider,
-	type LoadClientModulesResult,
-	type RouteRegistry,
-	type NavRegistry,
-	type SlotRegistry,
-} from '@kuckit/sdk-react'
-import { routeTree } from '../routeTree.gen'
-import { useServices } from './ServicesProvider'
-import { getClientModuleSpecs } from '../modules.client'
-
-interface KuckitContextValue {
-	routeRegistry: RouteRegistry
-	navRegistry: NavRegistry
-	slotRegistry: SlotRegistry
-	isLoaded: boolean
-}
-
-const KuckitContext = createContext<KuckitContextValue | null>(null)
-
-/**
- * Hook to access Kuckit registries
- */
-export function useKuckit(): KuckitContextValue {
-	const ctx = useContext(KuckitContext)
-	if (!ctx) {
-		throw new Error('useKuckit must be used within a KuckitProvider')
-	}
-	return ctx
-}
-
-interface KuckitProviderProps {
-	children?: ReactNode
-}
-
-/**
- * KuckitProvider handles module loading and router creation
- */
-export function KuckitProvider({ children }: KuckitProviderProps) {
-	const { orpc, queryClient, rpcClient } = useServices()
-	const [loadResult, setLoadResult] = useState<LoadClientModulesResult | null>(null)
-	const [error, setError] = useState<Error | null>(null)
-
-	useEffect(() => {
-		let cancelled = false
-
-		const loadModules = async () => {
-			try {
-				const result = await loadKuckitClientModules({
-					orpc,
-					queryClient,
-					env: import.meta.env.MODE,
-					modules: getClientModuleSpecs(),
-				})
-
-				if (!cancelled) {
-					setLoadResult(result)
-				}
-			} catch (err) {
-				if (!cancelled) {
-					setError(err instanceof Error ? err : new Error(String(err)))
-				}
-			}
-		}
-
-		loadModules()
-
-		return () => {
-			cancelled = true
-		}
-	}, [orpc, queryClient])
-
-	const router = useMemo(() => {
-		if (!loadResult) return null
-		return createRouter({
-			routeTree,
-			defaultPreload: 'intent',
-			context: { orpc, queryClient },
-		})
-	}, [loadResult, orpc, queryClient])
-
-	if (error) {
-		return (
-			<div style={{ padding: '2rem', color: 'red' }}>
-				<h2>Failed to load modules</h2>
-				<p>{error.message}</p>
-			</div>
-		)
-	}
-
-	if (!loadResult || !router) {
-		return (
-			<div style={{ padding: '2rem' }}>
-				<p>Loading...</p>
-			</div>
-		)
-	}
-
-	const contextValue: KuckitContextValue = {
-		routeRegistry: loadResult.routeRegistry,
-		navRegistry: loadResult.navRegistry,
-		slotRegistry: loadResult.slotRegistry,
-		isLoaded: true,
-	}
-
-	return (
-		<KuckitContext.Provider value={contextValue}>
-			<KuckitRpcProvider client={rpcClient}>
-				<KuckitNavProvider registry={loadResult.navRegistry}>
-					<KuckitSlotProvider registry={loadResult.slotRegistry}>
-						<RouterProvider router={router} />
-						{children}
-					</KuckitSlotProvider>
-				</KuckitNavProvider>
-			</KuckitRpcProvider>
-		</KuckitContext.Provider>
-	)
-}

package/templates/base/apps/web/src/providers/ServicesProvider.tsx

@@ -1,47 +0,0 @@
-import { createContext, useContext, useMemo, type ReactNode } from 'react'
-import { QueryClientProvider } from '@tanstack/react-query'
-import {
-	createQueryClient,
-	createRPCLink,
-	createRPCClient,
-	createORPCUtils,
-	createAuthClientService,
-	type Services,
-} from '../services'
-
-const ServicesContext = createContext<Services | null>(null)
-
-interface ServicesProviderProps {
-	children: ReactNode
-}
-
-export function ServicesProvider({ children }: ServicesProviderProps) {
-	const services = useMemo<Services>(() => {
-		const queryClient = createQueryClient()
-		const link = createRPCLink()
-		const rpcClient = createRPCClient(link)
-		const orpc = createORPCUtils(rpcClient)
-		const authClient = createAuthClientService()
-
-		return {
-			queryClient,
-			rpcClient,
-			orpc,
-			authClient,
-		}
-	}, [])
-
-	return (
-		<ServicesContext.Provider value={services}>
-			<QueryClientProvider client={services.queryClient}>{children}</QueryClientProvider>
-		</ServicesContext.Provider>
-	)
-}
-
-export function useServices(): Services {
-	const context = useContext(ServicesContext)
-	if (!context) {
-		throw new Error('useServices must be used within a ServicesProvider')
-	}
-	return context
-}

package/templates/base/apps/web/src/services/auth-client.ts

@@ -1,12 +0,0 @@
-import type { auth } from '@kuckit/auth'
-import { createAuthClient } from 'better-auth/react'
-import { inferAdditionalFields } from 'better-auth/client/plugins'
-
-export function createAuthClientService() {
-	return createAuthClient({
-		baseURL: import.meta.env.VITE_API_URL || 'http://localhost:3000',
-		plugins: [inferAdditionalFields<typeof auth>()],
-	})
-}
-
-export type AuthClient = ReturnType<typeof createAuthClientService>

package/templates/base/apps/web/src/services/index.ts

@@ -1,3 +0,0 @@
-export * from './types'
-export * from './rpc'
-export * from './auth-client'

package/templates/base/apps/web/src/services/rpc.ts

@@ -1,29 +0,0 @@
-import { createORPCClient } from '@orpc/client'
-import { RPCLink } from '@orpc/client/fetch'
-import { createTanstackQueryUtils } from '@orpc/tanstack-query'
-import { QueryClient } from '@tanstack/react-query'
-import type { RPCClient, ORPCUtils } from './types'
-
-export function createQueryClient(): QueryClient {
-	return new QueryClient()
-}
-
-export function createRPCLink() {
-	return new RPCLink({
-		url: `${import.meta.env.VITE_API_URL || 'http://localhost:3000'}/rpc`,
-		fetch(url, options) {
-			return fetch(url, {
-				...options,
-				credentials: 'include',
-			})
-		},
-	})
-}
-
-export function createRPCClient(link: ReturnType<typeof createRPCLink>): RPCClient {
-	return createORPCClient(link)
-}
-
-export function createORPCUtils(client: RPCClient): ORPCUtils {
-	return createTanstackQueryUtils(client)
-}

package/templates/base/apps/web/src/services/types.ts

@@ -1,14 +0,0 @@
-import type { QueryClient } from '@tanstack/react-query'
-import type { createTanstackQueryUtils } from '@orpc/tanstack-query'
-import type { AuthClient } from './auth-client'
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type RPCClient = Record<string, any>
-export type ORPCUtils = ReturnType<typeof createTanstackQueryUtils<RPCClient>>
-
-export interface Services {
-	queryClient: QueryClient
-	rpcClient: RPCClient
-	orpc: ORPCUtils
-	authClient: AuthClient
-}