create-kuckit-app 0.1.1 → 0.2.1

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,351 @@
+# 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
+```
+
+## 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
+
+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