create-kuckit-app 0.1.0 → 0.2.0

package/templates/base/apps/web/src/routes/__root.tsx

@@ -0,0 +1,31 @@
+import type { QueryClient } from '@tanstack/react-query'
+import { Outlet, createRootRouteWithContext } from '@tanstack/react-router'
+import type { ORPCUtils } from '../services/types'
+
+export interface RouterAppContext {
+	orpc: ORPCUtils
+	queryClient: QueryClient
+}
+
+export const Route = createRootRouteWithContext<RouterAppContext>()({
+	component: RootComponent,
+	head: () => ({
+		meta: [
+			{
+				title: '__APP_NAME__',
+			},
+			{
+				name: 'description',
+				content: '__APP_NAME__ - A Kuckit application',
+			},
+		],
+	}),
+})
+
+function RootComponent() {
+	return (
+		<div style={{ minHeight: '100vh' }}>
+			<Outlet />
+		</div>
+	)
+}

package/templates/base/apps/web/src/routes/index.tsx

@@ -0,0 +1,46 @@
+import { createFileRoute, Link } from '@tanstack/react-router'
+import { useServices } from '../providers/ServicesProvider'
+
+export const Route = createFileRoute('/')({
+	component: HomePage,
+})
+
+function HomePage() {
+	const { authClient } = useServices()
+	const { data: session, isPending } = authClient.useSession()
+
+	if (isPending) {
+		return (
+			<div style={{ padding: '2rem', fontFamily: 'system-ui' }}>
+				<p>Loading...</p>
+			</div>
+		)
+	}
+
+	return (
+		<div style={{ padding: '2rem', fontFamily: 'system-ui' }}>
+			<h1>Welcome to __APP_NAME__</h1>
+			{session?.user ? (
+				<div>
+					<p>Hello, {session.user.name || session.user.email}!</p>
+					<button
+						onClick={() => authClient.signOut()}
+						style={{
+							padding: '0.5rem 1rem',
+							cursor: 'pointer',
+						}}
+					>
+						Sign Out
+					</button>
+				</div>
+			) : (
+				<div>
+					<p>Your Kuckit application is ready!</p>
+					<Link to="/login" style={{ color: 'blue', textDecoration: 'underline' }}>
+						Sign In
+					</Link>
+				</div>
+			)}
+		</div>
+	)
+}

package/templates/base/apps/web/src/routes/login.tsx

@@ -0,0 +1,108 @@
+import { createFileRoute, useNavigate } from '@tanstack/react-router'
+import { useState } from 'react'
+import { useServices } from '../providers/ServicesProvider'
+
+export const Route = createFileRoute('/login')({
+	component: LoginPage,
+})
+
+function LoginPage() {
+	const { authClient } = useServices()
+	const navigate = useNavigate()
+	const [isSignUp, setIsSignUp] = useState(false)
+	const [email, setEmail] = useState('')
+	const [password, setPassword] = useState('')
+	const [name, setName] = useState('')
+	const [error, setError] = useState('')
+	const [loading, setLoading] = useState(false)
+
+	const handleSubmit = async (e: React.FormEvent) => {
+		e.preventDefault()
+		setError('')
+		setLoading(true)
+
+		try {
+			if (isSignUp) {
+				await authClient.signUp.email({
+					email,
+					password,
+					name,
+				})
+			} else {
+				await authClient.signIn.email({
+					email,
+					password,
+				})
+			}
+			navigate({ to: '/' })
+		} catch (err) {
+			setError(err instanceof Error ? err.message : 'Authentication failed')
+		} finally {
+			setLoading(false)
+		}
+	}
+
+	return (
+		<div style={{ padding: '2rem', fontFamily: 'system-ui', maxWidth: '400px', margin: '0 auto' }}>
+			<h1>{isSignUp ? 'Create Account' : 'Sign In'}</h1>
+
+			<form
+				onSubmit={handleSubmit}
+				style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}
+			>
+				{isSignUp && (
+					<input
+						type="text"
+						placeholder="Name"
+						value={name}
+						onChange={(e) => setName(e.target.value)}
+						required
+						style={{ padding: '0.5rem', fontSize: '1rem' }}
+					/>
+				)}
+				<input
+					type="email"
+					placeholder="Email"
+					value={email}
+					onChange={(e) => setEmail(e.target.value)}
+					required
+					style={{ padding: '0.5rem', fontSize: '1rem' }}
+				/>
+				<input
+					type="password"
+					placeholder="Password"
+					value={password}
+					onChange={(e) => setPassword(e.target.value)}
+					required
+					style={{ padding: '0.5rem', fontSize: '1rem' }}
+				/>
+
+				{error && <p style={{ color: 'red' }}>{error}</p>}
+
+				<button
+					type="submit"
+					disabled={loading}
+					style={{ padding: '0.5rem 1rem', fontSize: '1rem', cursor: 'pointer' }}
+				>
+					{loading ? 'Loading...' : isSignUp ? 'Create Account' : 'Sign In'}
+				</button>
+			</form>
+
+			<p style={{ marginTop: '1rem' }}>
+				{isSignUp ? 'Already have an account? ' : "Don't have an account? "}
+				<button
+					onClick={() => setIsSignUp(!isSignUp)}
+					style={{
+						background: 'none',
+						border: 'none',
+						color: 'blue',
+						cursor: 'pointer',
+						textDecoration: 'underline',
+					}}
+				>
+					{isSignUp ? 'Sign In' : 'Create Account'}
+				</button>
+			</p>
+		</div>
+	)
+}

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

@@ -0,0 +1,12 @@
+import type { auth } from '@__APP_NAME_KEBAB__/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

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

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

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

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

package/templates/base/apps/web/vite.config.ts

@@ -1,6 +1,7 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
+import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
 
 export default defineConfig({
-	plugins: [react()],
+	plugins: [TanStackRouterVite(), react()],
 })

package/templates/base/docker-compose.yml

@@ -0,0 +1,23 @@
+name: __APP_NAME_KEBAB__
+
+services:
+  postgres:
+    image: postgres
+    container_name: __APP_NAME_KEBAB__-postgres
+    environment:
+      POSTGRES_DB: __APP_NAME_KEBAB__
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+    ports:
+      - '5432:5432'
+    volumes:
+      - __APP_NAME_KEBAB___postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+volumes:
+  __APP_NAME_KEBAB___postgres_data:

package/templates/base/eslint.config.js

@@ -0,0 +1,18 @@
+import js from '@eslint/js'
+import tseslint from 'typescript-eslint'
+import prettierConfig from 'eslint-config-prettier'
+
+export default [
+	{
+		ignores: ['**/node_modules', '**/dist', '**/.turbo', '**/routeTree.gen.ts'],
+	},
+	js.configs.recommended,
+	...tseslint.configs.recommended,
+	{
+		rules: {
+			'@typescript-eslint/no-explicit-any': 'warn',
+			'@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+		},
+	},
+	prettierConfig,
+]

package/templates/base/package.json

@@ -9,11 +9,41 @@
 	"scripts": {
 		"dev": "turbo dev",
 		"build": "turbo build",
-		"check-types": "turbo check-types"
+		"check-types": "turbo check-types",
+		"lint": "eslint apps packages",
+		"lint:fix": "eslint apps packages --fix",
+		"format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\"",
+		"format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\"",
+		"db:generate": "turbo -F @__APP_NAME_KEBAB__/db db:generate",
+		"db:migrate": "turbo -F @__APP_NAME_KEBAB__/db db:migrate",
+		"db:studio": "turbo -F @__APP_NAME_KEBAB__/db db:studio",
+		"prepare": "husky"
+	},
+	"lint-staged": {
+		"*.{ts,tsx,js,jsx}": [
+			"eslint --max-warnings=0",
+			"prettier --write"
+		],
+		"*.{json,md,yml,yaml}": [
+			"prettier --write"
+		]
+	},
+	"dependencies": {
+		"@kuckit/sdk": "^1.0.0",
+		"awilix": "^12.0.5",
+		"dotenv": "^17.2.2",
+		"zod": "^4.1.11"
 	},
 	"devDependencies": {
+		"@eslint/js": "^9.17.0",
+		"eslint": "^9.17.0",
+		"eslint-config-prettier": "^10.0.1",
+		"husky": "^9.1.7",
+		"lint-staged": "^16.0.0",
+		"prettier": "^3.4.2",
 		"turbo": "^2.5.4",
-		"typescript": "^5.8.2"
+		"typescript": "^5.8.2",
+		"typescript-eslint": "^8.18.2"
 	},
 	"packageManager": "bun@1.2.21"
 }

package/templates/base/packages/api/AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md - API Package
+
+> See root [AGENTS.md](../../AGENTS.md) for project overview
+
+## Purpose
+
+Shared API context, types, and procedure definitions for oRPC.
+
+## Key Files
+
+| File         | Purpose                          |
+| ------------ | -------------------------------- |
+| `context.ts` | Request context type definitions |
+| `index.ts`   | Public exports                   |
+
+## Usage
+
+```typescript
+import { type Context, protectedProcedure } from '@__APP_NAME_KEBAB__/api'
+```
+
+## Context Structure
+
+The API context provides:
+
+- `container` - Scoped DI container for the request
+- `user` - Authenticated user (when using `protectedProcedure`)

package/templates/base/packages/api/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@__APP_NAME_KEBAB__/api",
+	"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"
+		}
+	},
+	"devDependencies": {
+		"@types/express": "^5.0.1"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"@orpc/server": "^1.10.0",
+		"@orpc/client": "^1.10.0",
+		"@orpc/zod": "^1.10.0",
+		"better-auth": "^1.3.28",
+		"dotenv": "^17.2.2",
+		"zod": "^4.1.11",
+		"awilix": "^12.0.5",
+		"@__APP_NAME_KEBAB__/auth": "workspace:*",
+		"@__APP_NAME_KEBAB__/db": "workspace:*"
+	}
+}

package/templates/base/packages/api/src/context.ts

@@ -0,0 +1,48 @@
+import type { Request } from 'express'
+import { fromNodeHeaders } from 'better-auth/node'
+import { auth } from '@__APP_NAME_KEBAB__/auth'
+import { asValue, type AwilixContainer } from 'awilix'
+
+declare global {
+	// eslint-disable-next-line @typescript-eslint/no-namespace
+	namespace Express {
+		interface Request {
+			scope?: AwilixContainer
+		}
+	}
+}
+
+export interface CreateContextOptions {
+	req: Request
+}
+
+/**
+ * Create per-request context with DI container
+ */
+export async function createContext(opts: CreateContextOptions) {
+	let session
+	try {
+		session = await auth.api.getSession({
+			headers: fromNodeHeaders(opts.req.headers),
+		})
+	} catch (error) {
+		console.error('[Auth] Failed to get session:', error)
+		session = null
+	}
+
+	const requestId = crypto.randomUUID()
+
+	if (opts.req.scope) {
+		opts.req.scope.register({
+			session: asValue(session),
+			requestId: asValue(requestId),
+		})
+	}
+
+	return {
+		session,
+		di: opts.req.scope!,
+	}
+}
+
+export type Context = Awaited<ReturnType<typeof createContext>>

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

@@ -0,0 +1,22 @@
+import { ORPCError, os } from '@orpc/server'
+import type { Context } from './context'
+
+export const o = os.$context<Context>()
+
+export const publicProcedure = o
+
+const requireAuth = o.middleware(async ({ context, next }) => {
+	if (!context.session?.user) {
+		throw new ORPCError('UNAUTHORIZED')
+	}
+	return next({
+		context: {
+			session: context.session,
+		},
+	})
+})
+
+export const protectedProcedure = publicProcedure.use(requireAuth)
+
+export { createContext } from './context'
+export type { Context } from './context'

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

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

package/templates/base/packages/auth/AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md - Auth Package
+
+> See root [AGENTS.md](../../AGENTS.md) for project overview
+
+## Purpose
+
+Better-Auth configuration shared between server and web apps.
+
+## Key Files
+
+| File       | Purpose                                |
+| ---------- | -------------------------------------- |
+| `index.ts` | Auth configuration and client creation |
+
+## Server Usage
+
+```typescript
+import { auth } from '@__APP_NAME_KEBAB__/auth'
+
+// In Express
+app.all('/api/auth/*', auth.handler)
+```
+
+## Client Usage
+
+```typescript
+import { authClient } from '@__APP_NAME_KEBAB__/auth'
+
+// Sign in
+await authClient.signIn.email({ email, password })
+
+// Sign out
+await authClient.signOut()
+
+// Get session
+const session = await authClient.getSession()
+```
+
+## Configuration
+
+Auth requires these environment variables:
+
+- `BETTER_AUTH_SECRET` - Session encryption key
+- `BETTER_AUTH_URL` - Callback URL for OAuth
+- `DATABASE_URL` - For session storage

package/templates/base/packages/auth/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@__APP_NAME_KEBAB__/auth",
+	"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"
+		}
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"better-auth": "^1.3.28",
+		"dotenv": "^17.2.2",
+		"zod": "^4.1.11",
+		"@__APP_NAME_KEBAB__/db": "workspace:*"
+	}
+}

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

@@ -0,0 +1,22 @@
+import { betterAuth, type BetterAuthOptions } from 'better-auth'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { db } from '@__APP_NAME_KEBAB__/db'
+import * as schema from '@__APP_NAME_KEBAB__/db/schema/auth'
+
+export const auth = betterAuth<BetterAuthOptions>({
+	database: drizzleAdapter(db, {
+		provider: 'pg',
+		schema: schema,
+	}),
+	trustedOrigins: [process.env.CORS_ORIGIN || ''],
+	emailAndPassword: {
+		enabled: true,
+	},
+	advanced: {
+		defaultCookieAttributes: {
+			sameSite: process.env.NODE_ENV === 'production' ? 'none' : 'lax',
+			secure: process.env.NODE_ENV === 'production',
+			httpOnly: true,
+		},
+	},
+})

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

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

package/templates/base/packages/db/AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md - Database Package
+
+> See root [AGENTS.md](../../AGENTS.md) for project overview
+
+## Purpose
+
+Drizzle ORM configuration, database connection, migrations, and shared schema.
+
+## Key Files
+
+| File                | Purpose                   |
+| ------------------- | ------------------------- |
+| `drizzle.config.ts` | Drizzle Kit configuration |
+| `src/connection.ts` | Database connection pool  |
+| `src/schema/`       | Shared schema definitions |
+| `src/migrations/`   | SQL migration files       |
+
+## Commands
+
+```bash
+# Generate migration from schema changes
+bun run db:generate
+
+# Apply pending migrations
+bun run db:migrate
+
+# Open Drizzle Studio (database GUI)
+bun run db:studio
+```
+
+## Adding a New Table
+
+1. Create schema file in `src/schema/` or in your module's `adapters/`:
+
+   ```typescript
+   import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
+
+   export const myTable = pgTable('my_table', {
+   	id: uuid('id').primaryKey().defaultRandom(),
+   	name: text('name').notNull(),
+   	createdAt: timestamp('created_at').defaultNow(),
+   })
+   ```
+
+2. Export from `src/index.ts` if shared
+
+3. Generate and run migration:
+   ```bash
+   bun run db:generate
+   bun run db:migrate
+   ```
+
+## Connection
+
+```typescript
+import { db } from '@__APP_NAME_KEBAB__/db'
+
+const users = await db.select().from(usersTable)
+```

package/templates/base/packages/db/drizzle.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'drizzle-kit'
+import dotenv from 'dotenv'
+import { dirname, resolve } from 'path'
+import { fileURLToPath } from 'url'
+import { buildDatabaseUrl } from './src/connection'
+
+const currentFilePath = fileURLToPath(import.meta.url)
+const currentDirPath = dirname(currentFilePath)
+
+dotenv.config({
+	path: resolve(currentDirPath, '../../apps/server/.env'),
+})
+
+export default defineConfig({
+	schema: [resolve(currentDirPath, './src/schema')],
+	out: resolve(currentDirPath, './src/migrations'),
+	dialect: 'postgresql',
+	dbCredentials: { url: buildDatabaseUrl() },
+})