create-kuckit-app 0.1.1 → 0.2.0

package/templates/base/.claude/skills/kuckit/references/PUBLISHING.md

@@ -0,0 +1,231 @@
+# Publishing Kuckit Packages
+
+## Preferred Method: Git Tags + CI/CD
+
+The recommended way to publish kuckit packages is via Git tags, which trigger GitHub Actions to handle the npm publish.
+
+---
+
+## SDK Packages (Changeset Workflow)
+
+SDK packages use **Changesets** for version management. This is a **multi-step process** that must be followed exactly.
+
+### Complete Release Flow
+
+```bash
+# 1. Create a changeset (describes what changed)
+bunx changeset
+
+# 2. Consume changesets and bump versions
+bun run version-packages
+
+# NOTE: version-packages requires GITHUB_TOKEN for changelog generation.
+# If you don't have GITHUB_TOKEN set, use gh CLI:
+export GITHUB_TOKEN=$(gh auth token)
+
+# 3. Commit the version bumps and changelog updates
+git add packages/*/package.json packages/*/CHANGELOG.md .changeset/
+git commit -m "chore(release): bump SDK packages to X.Y.Z"
+git push
+
+# 4. Create and push a tag to trigger publish
+git tag sdk-v1.0.X
+git push origin sdk-v1.0.X
+```
+
+### What Each Step Does
+
+| Step             | Command                    | What It Does                                                                  |
+| ---------------- | -------------------------- | ----------------------------------------------------------------------------- |
+| Create changeset | `bunx changeset`           | Creates a `.changeset/*.md` file describing the change                        |
+| Version packages | `bun run version-packages` | Consumes changeset files, bumps `package.json` versions, generates CHANGELOGs |
+| Push tag         | `git tag sdk-v*`           | Triggers CI workflow which runs `changeset publish`                           |
+
+### Fixed Package Groups
+
+The SDK packages are configured as a **fixed** group in `.changeset/config.json`. This means they always share the same version number:
+
+- `@kuckit/domain`
+- `@kuckit/application`
+- `@kuckit/infrastructure`
+- `@kuckit/api`
+- `@kuckit/contracts`
+- `@kuckit/auth`
+- `@kuckit/db`
+- `@kuckit/sdk`
+- `@kuckit/sdk-react`
+- `@kuckit/users-module`
+
+When you bump one, they all bump together.
+
+---
+
+## Common Pitfalls
+
+### Pushing a tag without running `version-packages`
+
+**Symptom:** CI workflow runs successfully but outputs "No unpublished projects to publish". Packages stay at their old version on npm.
+
+**Cause:** A changeset file exists (`.changeset/*.md`) but `bun run version-packages` was never run. The tag triggers `changeset publish`, which only publishes packages whose `package.json` version is higher than what's on npm.
+
+**Fix:**
+
+```bash
+# Run the version step you missed
+bun run version-packages
+
+# Commit the version bumps
+git add packages/*/package.json packages/*/CHANGELOG.md .changeset/
+git commit -m "chore(release): bump SDK packages to X.Y.Z"
+git push
+
+# Delete the old tag and create a new one
+git tag -d sdk-vX.Y.Z
+git push origin :refs/tags/sdk-vX.Y.Z
+git tag sdk-vX.Y.Z
+git push origin sdk-vX.Y.Z
+```
+
+### Forgetting to create a changeset
+
+**Symptom:** `bun run version-packages` does nothing.
+
+**Cause:** No changeset files exist in `.changeset/`.
+
+**Fix:** Run `bunx changeset` first to create a changeset describing your changes.
+
+### Version already published
+
+**Symptom:** npm publish fails with "You cannot publish over previously published versions"
+
+**Cause:** The version in `package.json` already exists on npm.
+
+**Fix:** Create a new changeset and run `version-packages` again to bump to a new version.
+
+### Missing GITHUB_TOKEN for version-packages
+
+**Symptom:** `bun run version-packages` fails or hangs without clear explanation.
+
+**Cause:** The `version-packages` command requires `GITHUB_TOKEN` to be set for changelog generation (fetching PR/commit info from GitHub).
+
+**Fix:** Set the token using the `gh` CLI:
+
+```bash
+export GITHUB_TOKEN=$(gh auth token)
+bun run version-packages
+```
+
+---
+
+## CLI & Create-App Packages (Direct Publish)
+
+For `@kuckit/cli` and `create-kuckit-app`, these are published directly (not via changesets):
+
+### Workflow
+
+1. **Bump version** in the package's `package.json` (e.g., `packages/kuckit-cli/package.json`)
+
+2. **Commit and push:**
+
+   ```bash
+   git commit -am "chore(cli): release @kuckit/cli v0.2.0"
+   git push
+   ```
+
+3. **Create and push a tag:**
+
+   ```bash
+   git tag cli-v0.2.0
+   git push origin cli-v0.2.0
+   ```
+
+4. **GitHub Actions handles the rest** - builds and publishes to npm
+
+---
+
+## Tag Patterns
+
+| Tag Pattern     | Publishes                                  | Method             |
+| --------------- | ------------------------------------------ | ------------------ |
+| `sdk-v*`        | All SDK packages (fixed group)             | Changesets         |
+| `cli-v*`        | Only `@kuckit/cli`                         | Direct npm publish |
+| `create-app-v*` | Only `create-kuckit-app`                   | Direct npm publish |
+| `v*`            | Both `@kuckit/cli` and `create-kuckit-app` | Direct npm publish |
+
+---
+
+## Commands Reference
+
+| Command                    | Description                                                     |
+| -------------------------- | --------------------------------------------------------------- |
+| `bunx changeset`           | Create a new changeset file describing your changes             |
+| `bun run version-packages` | Consume changesets, bump versions, generate CHANGELOGs          |
+| `bunx changeset status`    | Check what changesets exist and which packages will be affected |
+| `bunx changeset publish`   | Publish packages (run by CI, not locally)                       |
+
+---
+
+## Pre-publish Check (Optional)
+
+Before tagging, you can verify the package builds correctly:
+
+```bash
+cd packages/kuckit-cli
+bun run prepublishOnly
+```
+
+This runs:
+
+1. `tsdown` build
+2. Workspace protocol check (ensures no `workspace:` or `catalog:` protocols leak into published package)
+
+---
+
+## CI/CD Workflow
+
+The publish workflow is located at `.github/workflows/publish.yml`.
+
+**What it does:**
+
+1. Triggers on tag push matching the patterns above
+2. Runs `bun install --frozen-lockfile`
+3. Builds the package(s)
+4. Resolves workspace protocols (converts `workspace:*` and `catalog:` to real versions)
+5. Publishes to npm
+
+**Required secret:** `NPM_TOKEN` must be configured in GitHub repository secrets.
+
+---
+
+## Key Files
+
+| File                                      | Purpose                                           |
+| ----------------------------------------- | ------------------------------------------------- |
+| `.changeset/config.json`                  | Changeset configuration with fixed package groups |
+| `scripts/resolve-workspace-protocols.cjs` | Resolves workspace:\*/catalog: before publish     |
+| `.github/workflows/publish.yml`           | CI workflow that handles publishing               |
+
+---
+
+## Why Git Tags over Local Publish?
+
+While the repo has Changesets configured, **local publishing doesn't work well** because:
+
+- npm requires 2FA for publishing
+- Local tokens don't have 2FA bypass permissions
+- The CI/CD workflow has a granular access token (`NPM_TOKEN` secret) with proper permissions
+
+**Use Changesets for:** Version management and changelog generation. Rely on Git tags for actual publishing.
+
+---
+
+## Troubleshooting
+
+| Issue                                                   | Solution                                                         |
+| ------------------------------------------------------- | ---------------------------------------------------------------- |
+| "No unpublished projects to publish"                    | Run `bun run version-packages` first, then push a new tag        |
+| "You cannot publish over previously published versions" | Bump the version in package.json first                           |
+| "Two-factor authentication required"                    | Use Git tags + CI/CD instead of local publish                    |
+| Build fails in CI                                       | Check `bun run prepublishOnly` locally first                     |
+| Changeset file exists but versions didn't bump          | Run `bun run version-packages` to consume the changeset          |
+| `version-packages` fails or hangs                       | Set `GITHUB_TOKEN` first: `export GITHUB_TOKEN=$(gh auth token)` |

package/templates/base/.env.example

@@ -0,0 +1,13 @@
+# Database
+DATABASE_URL=postgresql://postgres:password@localhost:5432/__APP_NAME_KEBAB__
+
+# Auth
+BETTER_AUTH_SECRET=your-secret-key-change-in-production
+BETTER_AUTH_URL=http://localhost:3000
+
+# Server
+PORT=3000
+NODE_ENV=development
+
+# Web
+VITE_API_URL=http://localhost:3000

package/templates/base/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  quality:
+    name: Code Quality
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Type check
+        run: bun run check-types

package/templates/base/.husky/pre-commit

@@ -0,0 +1 @@
+bun run lint-staged

package/templates/base/.prettierignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.turbo
+bun.lockb
+*.log

package/templates/base/.prettierrc

@@ -0,0 +1,8 @@
+{
+	"semi": false,
+	"singleQuote": true,
+	"tabWidth": 2,
+	"useTabs": true,
+	"trailingComma": "es5",
+	"printWidth": 100
+}

package/templates/base/AGENTS.md

@@ -0,0 +1,148 @@
+# AGENTS.md - **APP_NAME**
+
+## Quick Start
+
+```bash
+bun install              # Install dependencies
+docker compose up -d     # Start PostgreSQL
+bun run db:migrate       # Run database migrations
+bun run dev              # Start dev servers (web + server)
+```
+
+## Project Structure
+
+```
+__APP_NAME_KEBAB__/
+├── apps/
+│   ├── server/              # Express + oRPC backend (port 3000)
+│   └── web/                 # React + TanStack Router frontend (port 3001)
+├── packages/
+│   ├── api/                 # Shared API context and types
+│   ├── auth/                # Better-Auth configuration
+│   ├── db/                  # Drizzle ORM, migrations, schema
+│   └── items-module/        # Example Kuckit module (reference implementation)
+├── .env.example             # Environment template
+├── docker-compose.yml       # PostgreSQL container
+└── turbo.json               # Turborepo configuration
+```
+
+## Module Development
+
+Kuckit uses a **module-based architecture** where each module contains its own Clean Architecture layers internally.
+
+### Module Structure
+
+```
+packages/your-module/
+├── src/
+│   ├── domain/          # Entities with Zod schemas
+│   ├── ports/           # Repository interfaces
+│   ├── adapters/        # Drizzle implementations
+│   ├── usecases/        # Business logic
+│   ├── api/             # oRPC routers
+│   ├── ui/              # React components (optional)
+│   ├── module.ts        # Server module definition
+│   └── client-module.ts # Client module definition
+```
+
+### Creating a New Module
+
+1. Copy `packages/items-module` as a template
+2. Rename and update `package.json`
+3. Implement your domain entities in `domain/`
+4. Define repository interfaces in `ports/`
+5. Implement adapters in `adapters/`
+6. Create use cases in `usecases/`
+7. Expose API in `api/` via oRPC router
+8. Register module in `apps/server/src/config/modules.ts`
+9. Add client module to `apps/web/src/modules.client.ts`
+
+### Dependency Rules
+
+```
+domain → No dependencies (pure Zod schemas)
+   ↓
+ports → Depends on domain only
+   ↓
+usecases → Depends on ports and domain
+   ↓
+adapters → Implements ports, depends on domain
+   ↓
+api → Wires everything together
+```
+
+## Common Tasks
+
+### Add a new API endpoint
+
+1. Define input/output schemas in `domain/`
+2. Create use case in `usecases/`
+3. Add to router in `api/`
+
+### Add a new database table
+
+1. Define schema in your module's `adapters/` or `packages/db/src/schema/`
+2. Run `bun run db:generate`
+3. Run `bun run db:migrate`
+
+### Add authentication to an endpoint
+
+```typescript
+import { protectedProcedure } from '@__APP_NAME_KEBAB__/api'
+
+export const myRouter = {
+	protectedRoute: protectedProcedure.input(mySchema).handler(async ({ input, context }) => {
+		const { user } = context // Authenticated user
+		// ...
+	}),
+}
+```
+
+## Scripts
+
+| Command                | Description                            |
+| ---------------------- | -------------------------------------- |
+| `bun run dev`          | Start all dev servers                  |
+| `bun run build`        | Build all packages                     |
+| `bun run check-types`  | Type check all packages                |
+| `bun run lint`         | Run ESLint on all packages             |
+| `bun run lint:fix`     | Fix ESLint issues automatically        |
+| `bun run format`       | Format code with Prettier              |
+| `bun run format:check` | Check formatting without changes       |
+| `bun run db:generate`  | Generate migration from schema changes |
+| `bun run db:migrate`   | Apply pending migrations               |
+| `bun run db:studio`    | Open Drizzle Studio                    |
+
+## Code Quality
+
+This project includes pre-configured code quality tools:
+
+- **ESLint** - TypeScript linting with recommended rules
+- **Prettier** - Code formatting
+- **Husky** - Git hooks for pre-commit checks
+- **lint-staged** - Run linters on staged files only
+
+Pre-commit hooks automatically run `lint-staged` which:
+
+1. Runs ESLint on staged `.ts/.tsx/.js/.jsx` files
+2. Runs Prettier on all staged files
+
+To bypass hooks (not recommended): `git commit --no-verify`
+
+## Environment Variables
+
+See `.env.example` for required variables:
+
+- `DATABASE_URL` - PostgreSQL connection string
+- `BETTER_AUTH_SECRET` - Auth session secret
+- `BETTER_AUTH_URL` - Auth callback URL
+- `PORT` - Server port (default: 3000)
+- `VITE_API_URL` - API URL for frontend
+
+## Related Documentation
+
+- [Kuckit SDK](https://github.com/draphonix/kuckit)
+- [oRPC](https://orpc.dev)
+- [Better-Auth](https://better-auth.com)
+- [Drizzle ORM](https://orm.drizzle.team)
+- [TanStack Router](https://tanstack.com/router)

package/templates/base/apps/server/.env.example

@@ -0,0 +1,18 @@
+# Server Environment Variables
+
+# Database connection
+DATABASE_URL=postgresql://postgres:password@localhost:5432/__APP_NAME_KEBAB__
+
+# Authentication
+BETTER_AUTH_SECRET=your-secret-key-change-in-production
+BETTER_AUTH_URL=http://localhost:3000
+
+# Server configuration
+PORT=3000
+NODE_ENV=development
+CORS_ORIGIN=http://localhost:3001
+
+# Logging (optional)
+LOG_LEVEL=INFO
+ENABLE_FILE_LOGGING=false
+LOG_DIR=./logs

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

@@ -0,0 +1,37 @@
+# AGENTS.md - Server App
+
+> See root [AGENTS.md](../../AGENTS.md) for project overview
+
+## Purpose
+
+Express backend hosting oRPC API, Better-Auth authentication, and the Kuckit module system.
+
+## 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 |
+
+## Adding New Modules
+
+1. Install the module package
+2. Add to `config/modules.ts`:
+
+   ```typescript
+   import { kuckitModule as myModule } from '@__APP_NAME_KEBAB__/my-module'
+
+   export const getModuleSpecs = () => [
+   	{ module: itemsModule },
+   	{ module: myModule }, // Add here
+   ]
+   ```
+
+3. Restart the server
+
+## Environment Variables
+
+See `.env.example` in this directory.

package/templates/base/apps/server/package.json

@@ -1,5 +1,6 @@
 {
-	"name": "__APP_NAME_KEBAB__-server",
+	"name": "@__APP_NAME_KEBAB__/server",
+	"private": true,
 	"type": "module",
 	"scripts": {
 		"build": "tsdown",
@@ -10,11 +11,21 @@
 		"express": "^5.1.0",
 		"cors": "^2.8.5",
 		"dotenv": "^17.2.2",
-		"awilix": "^12.0.5"
+		"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:*"
 	},
 	"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/app.ts

@@ -0,0 +1,20 @@
+import express, { type Express } from 'express'
+import cors from 'cors'
+
+/**
+ * Create and configure Express app
+ */
+export const createApp = (): Express => {
+	const app = express()
+
+	app.use(
+		cors({
+			origin: process.env.CORS_ORIGIN || 'http://localhost:3001',
+			methods: ['GET', 'POST', 'OPTIONS'],
+			allowedHeaders: ['Content-Type', 'Authorization'],
+			credentials: true,
+		})
+	)
+
+	return app
+}

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

@@ -0,0 +1,10 @@
+import { auth } from '@__APP_NAME_KEBAB__/auth'
+import { toNodeHandler } from 'better-auth/node'
+import type { Express } from 'express'
+
+/**
+ * Setup Better-Auth routes
+ */
+export const setupAuth = (app: Express) => {
+	app.all('/api/auth{/*path}', toNodeHandler(auth))
+}

package/templates/base/apps/server/src/config/modules.ts

@@ -0,0 +1,22 @@
+import type { ModuleSpec } from '@kuckit/sdk'
+
+// Import your modules here
+// import { kuckitModule as itemsModule } from '@__APP_NAME_KEBAB__/items-module'
+
+/**
+ * Module specifications for the server application
+ *
+ * Add modules here to configure the server's functionality.
+ * Modules are loaded in order, with dependencies resolved automatically.
+ */
+export const getModuleSpecs = (): ModuleSpec[] => {
+	const modules: ModuleSpec[] = [
+		// Add your modules here:
+		// {
+		//   module: itemsModule,
+		//   config: { ... },
+		// },
+	]
+
+	return modules
+}

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

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

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