create-kuckit-app 0.1.1 → 0.2.1

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/tsconfig.json

@@ -3,7 +3,11 @@
 	"compilerOptions": {
 		"lib": ["DOM", "DOM.Iterable", "ESNext"],
 		"jsx": "react-jsx",
-		"noEmit": true
+		"noEmit": true,
+		"baseUrl": ".",
+		"paths": {
+			"@/*": ["./src/*"]
+		}
 	},
 	"include": ["src"]
 }

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

@@ -1,6 +1,13 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
+import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
+import path from 'path'
 
 export default defineConfig({
-	plugins: [react()],
+	plugins: [TanStackRouterVite(), react()],
+	resolve: {
+		alias: {
+			'@': path.resolve(__dirname, './src'),
+		},
+	},
 })

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,66 @@
+# AGENTS.md - API Package
+
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
+
+## Purpose
+
+Shared API context, types, and procedure definitions for oRPC.
+
+## Key Files
+
+| File         | Purpose                          |
+| ------------ | -------------------------------- |
+| `context.ts` | Request context type definitions |
+| `index.ts`   | Public exports                   |
+
+## Procedure Types
+
+```typescript
+import { publicProcedure, protectedProcedure } from '@__APP_NAME_KEBAB__/api'
+
+// Public - no authentication required
+export const healthRouter = {
+	ping: publicProcedure.handler(() => 'pong'),
+}
+
+// Protected - requires authenticated user
+export const itemsRouter = {
+	list: protectedProcedure.handler(async ({ context }) => {
+		const userId = context.session?.user?.id
+		// ...
+	}),
+}
+```
+
+## Context Structure
+
+The API context provides:
+
+- `di` - Scoped DI container for the request
+- `session` - Current user session (when using `protectedProcedure`)
+
+## Typing DI Access in Routers
+
+Use a module-local interface to type `context.di.cradle`:
+
+```typescript
+// In your module's router file
+interface ItemsCradle {
+	itemRepository: ItemRepository
+	createItem: (input: CreateItemInput) => Promise<Item>
+}
+
+export const itemsRouter = {
+	create: protectedProcedure.input(createItemSchema).handler(async ({ input, context }) => {
+		const { createItem } = context.di.cradle as ItemsCradle
+		return createItem(input)
+	}),
+}
+```
+
+**Why module-local interfaces:**
+
+- Type assertion stays within the module
+- Module remains self-contained
+- Server app doesn't need to know about module internals
+- Scales to any number of modules without server changes

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,61 @@
+# AGENTS.md - Auth Package
+
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
+
+## 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()
+```
+
+## Session in oRPC Context
+
+The current user session is available in `protectedProcedure` handlers:
+
+```typescript
+import { protectedProcedure } from '@__APP_NAME_KEBAB__/api'
+
+export const myRouter = {
+	getProfile: protectedProcedure.handler(async ({ context }) => {
+		const userId = context.session?.user?.id
+		const userEmail = context.session?.user?.email
+		// ... use session data
+	}),
+}
+```
+
+## 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,74 @@
+# AGENTS.md - Database Package
+
+> See root [AGENTS.md](../../AGENTS.md) for SDK Module System patterns
+
+## 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
+   ```
+
+## Module Schema Pattern
+
+Modules can define their own schemas in `adapters/`:
+
+```typescript
+// packages/items-module/src/adapters/items.schema.ts
+export const itemsTable = pgTable('items', {
+	id: uuid('id').primaryKey().defaultRandom(),
+	userId: text('user_id').notNull(),
+	name: text('name').notNull(),
+})
+```
+
+The schema is imported by `drizzle.config.ts` for migration generation.
+
+## 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() },
+})

package/templates/base/packages/db/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "@__APP_NAME_KEBAB__/db",
+	"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"
+		}
+	},
+	"scripts": {
+		"db:generate": "drizzle-kit generate",
+		"db:migrate": "drizzle-kit migrate",
+		"db:studio": "drizzle-kit studio"
+	},
+	"devDependencies": {
+		"drizzle-kit": "^0.31.2",
+		"@types/pg": "^8.11.11"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"drizzle-orm": "^0.44.2",
+		"pg": "^8.14.1",
+		"dotenv": "^17.2.2",
+		"zod": "^4.1.11"
+	}
+}

package/templates/base/packages/db/src/connection.ts

@@ -0,0 +1,40 @@
+/**
+ * Database connection utilities
+ * Single source of truth for DATABASE_URL construction
+ */
+
+/**
+ * Build DATABASE_URL from environment variables
+ *
+ * Supports two modes:
+ * 1. Direct DATABASE_URL - used in local development
+ * 2. Individual DB_* vars - used in Cloud Run with Cloud SQL Auth Proxy
+ *
+ * @throws Error if neither DATABASE_URL nor complete DB_* vars are provided
+ */
+export function buildDatabaseUrl(): string {
+	// Prefer DATABASE_URL if provided directly
+	if (process.env.DATABASE_URL) {
+		return process.env.DATABASE_URL
+	}
+
+	// Construct from individual components (Cloud Run with Cloud SQL)
+	const { DB_HOST, DB_USER, DB_PASSWORD, DB_NAME } = process.env
+	if (DB_HOST && DB_USER && DB_PASSWORD && DB_NAME) {
+		return `postgresql://${DB_USER}:${encodeURIComponent(DB_PASSWORD)}@/${DB_NAME}?host=${DB_HOST}`
+	}
+
+	throw new Error(
+		'Missing database configuration: provide DATABASE_URL or DB_HOST, DB_USER, DB_PASSWORD, DB_NAME'
+	)
+}
+
+/**
+ * Ensure DATABASE_URL is set in process.env
+ * Call this early in application startup to set up the environment
+ */
+export function ensureDatabaseUrl(): string {
+	const url = buildDatabaseUrl()
+	process.env.DATABASE_URL = url
+	return url
+}

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

@@ -0,0 +1,4 @@
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { buildDatabaseUrl } from './connection'
+
+export const db = drizzle(buildDatabaseUrl())