create-kuckit-app 0.1.0 → 0.2.0

package/templates/base/.claude/skills/kuckit/SKILL.md

@@ -0,0 +1,436 @@
+---
+name: kuckit
+description: Comprehensive Kuckit framework development assistant for building modular full-stack TypeScript applications. Use for any Kuckit-related questions including SDK usage, module development, CLI commands, Clean Architecture patterns, DI container setup, infrastructure deployment, and troubleshooting. Works with @kuckit/sdk, @kuckit/cli, and the entire kuckit ecosystem.
+---
+
+# Kuckit Framework Skill
+
+This skill provides comprehensive assistance for developing applications with the Kuckit framework - a full-stack TypeScript monorepo implementing Clean Architecture with a modular plugin system.
+
+## When to Use This Skill
+
+Use this skill when you need help with:
+
+- Creating or modifying Kuckit modules (server and client)
+- Understanding the Kuckit SDK and DI container
+- Using Kuckit CLI commands
+- Implementing Clean Architecture patterns
+- Working with the module system lifecycle
+- Database operations with Drizzle ORM
+- Infrastructure deployment to GCP
+- Troubleshooting Kuckit applications
+
+## Project Location
+
+The Kuckit codebase is located at the project root (where this skill is installed).
+
+## Quick Reference
+
+### Core Documentation Files
+
+| Document        | Path                            | Description                      |
+| --------------- | ------------------------------- | -------------------------------- |
+| Architecture    | `docs/ARCHITECTURE.md`          | System architecture and diagrams |
+| Index           | `docs/INDEX.md`                 | Documentation navigation         |
+| Troubleshooting | `docs/TROUBLESHOOTING.md`       | Common issues and solutions      |
+| CLI Docs        | `packages/kuckit-cli/AGENTS.md` | CLI command reference            |
+| SDK README      | `packages/sdk/README.md`        | SDK quick start                  |
+
+### Package Structure
+
+```
+packages/
+├── sdk/                  # Backend DI container & module system
+├── sdk-react/            # Frontend module system
+├── kuckit-cli/           # CLI tooling
+├── create-kuckit-app/    # Project scaffolding
+├── domain/               # Business entities (no dependencies)
+├── application/          # Use cases and business logic
+├── contracts/            # DTOs and Zod schemas
+├── infrastructure/       # Repository implementations
+├── api/                  # oRPC procedures
+├── db/                   # Drizzle ORM schemas
+├── auth/                 # Better-Auth configuration
+├── infra/                # Pulumi infrastructure
+├── users-module/         # Reference module implementation
+├── landing-module/       # Landing page module
+└── cli-auth-module/      # CLI authentication module
+```
+
+---
+
+## CLI Commands
+
+### Module Management
+
+```bash
+# Generate a new module
+bunx kuckit generate module <name>
+bunx kuckit generate module billing --org acme --dir packages
+
+# Install and wire a module
+bunx kuckit add <package>
+bunx kuckit add @acme/billing-module --skip-install
+
+# Search npm for modules
+bunx kuckit search <keyword>
+bunx kuckit search billing --limit 20 --json
+
+# Find unregistered modules
+bunx kuckit discover
+bunx kuckit discover --json --interactive
+
+# Validate project setup
+bunx kuckit doctor
+```
+
+### Database Commands
+
+```bash
+bunx kuckit db push      # Push schemas to database
+bunx kuckit db generate  # Generate migrations
+bunx kuckit db studio    # Open Drizzle Studio
+```
+
+### Authentication Commands
+
+```bash
+bunx kuckit auth login   # OAuth device flow login
+bunx kuckit auth logout  # Clear credentials
+bunx kuckit auth whoami  # Show current user
+```
+
+### Infrastructure Commands
+
+```bash
+# Initialize infrastructure
+bunx kuckit infra init --provider gcp --project <id> --region us-central1 --env dev
+
+# Deploy to Cloud Run
+bunx kuckit infra deploy --env dev
+bunx kuckit infra deploy --env dev --preview  # Preview only
+
+# Database operations
+bunx kuckit infra db:push --env dev
+bunx kuckit infra db:migrate --env dev
+
+# Management
+bunx kuckit infra status    # Show state
+bunx kuckit infra logs -f   # Stream logs
+bunx kuckit infra rollback  # Rollback revision
+bunx kuckit infra destroy   # Destroy resources
+bunx kuckit infra repair    # Fix state issues
+```
+
+---
+
+## Module Development
+
+### Server Module Definition
+
+```typescript
+// src/module.ts
+import { defineKuckitModule, asClass, asFunction } from '@kuckit/sdk'
+
+interface BillingModuleConfig {
+	currency: string
+	taxRate: number
+}
+
+export const kuckitModule = defineKuckitModule<BillingModuleConfig>({
+	id: 'acme.billing',
+	displayName: 'Billing',
+	description: 'Invoice and payment processing',
+	version: '1.0.0',
+
+	// Register DI dependencies
+	register(ctx) {
+		ctx.container.register({
+			invoiceRepository: asClass(DrizzleInvoiceRepository).scoped(),
+			paymentService: asFunction(makePaymentService).singleton(),
+		})
+	},
+
+	// Register API routes
+	registerApi(ctx) {
+		ctx.addApiRegistration({
+			type: 'rpc-router',
+			name: 'billing',
+			router: createBillingRouter(ctx.container),
+		})
+	},
+
+	// Startup logic
+	onBootstrap(ctx) {
+		const logger = ctx.container.resolve('logger')
+		logger.info(`Billing module initialized with currency: ${ctx.config.currency}`)
+	},
+
+	// Shutdown logic
+	onShutdown(ctx) {
+		ctx.logger.info('Billing module stopped')
+	},
+})
+```
+
+### Client Module Definition
+
+```typescript
+// src/client/module.ts
+import { defineKuckitClientModule } from '@kuckit/sdk-react'
+
+export const kuckitClientModule = defineKuckitClientModule({
+	id: 'acme.billing',
+
+	routes: [
+		{ path: '/billing', component: BillingPage },
+		{ path: '/billing/invoices', component: InvoicesPage },
+	],
+
+	navItems: [{ label: 'Billing', href: '/billing', icon: CreditCard }],
+})
+```
+
+### Module package.json Metadata
+
+```json
+{
+	"name": "@acme/billing-module",
+	"kuckit": {
+		"id": "acme.billing",
+		"server": "./dist/module.js",
+		"client": "./dist/client/module.js",
+		"schema": "./src/server/schema/index.ts"
+	}
+}
+```
+
+---
+
+## SDK Core Services
+
+After `createKuckitContainer()`, these services are available:
+
+| Token              | Type               | Description                    |
+| ------------------ | ------------------ | ------------------------------ |
+| `config`           | `CoreConfig`       | Application configuration      |
+| `db`               | Drizzle instance   | Database query builder         |
+| `dbPool`           | `Pool`             | Raw PostgreSQL connection pool |
+| `logger`           | `Logger`           | Structured logging             |
+| `eventBus`         | `EventBus`         | Pub/sub event system           |
+| `clock`            | `Clock`            | Time abstraction (testable)    |
+| `cacheStore`       | `CacheStore`       | Key-value cache                |
+| `rateLimiterStore` | `RateLimiterStore` | Rate limiting                  |
+| `auth`             | Auth utilities     | Authentication helpers         |
+
+### Container Usage
+
+```typescript
+import { createKuckitContainer, loadKuckitModules, disposeContainer } from '@kuckit/sdk'
+
+// Create container with core services
+const container = await createKuckitContainer({
+	config: {
+		databaseUrl: process.env.DATABASE_URL!,
+		enableFileLogging: false,
+		logDir: './logs',
+		logLevel: 'INFO',
+		env: 'development',
+	},
+})
+
+// Load modules
+await loadKuckitModules({
+	container,
+	env: 'development',
+	modules: [
+		{ module: usersModule, config: { enableCaching: true } },
+		{ package: '@acme/billing-module' },
+	],
+	onApiRegistrations: (registrations) => {
+		// Wire API routes to your framework
+	},
+})
+
+// Resolve services
+const logger = container.resolve('logger')
+const userRepo = container.resolve('userRepository')
+
+// Cleanup on shutdown
+await disposeContainer(container)
+```
+
+---
+
+## Clean Architecture Layers
+
+### Dependency Rules
+
+```
+domain         <- (no deps, pure business logic)
+    ^
+    |
+application    <- (imports domain only)
+    ^
+    |
+infrastructure <- (imports domain, external libs)
+    ^
+    |
+api            <- (imports domain, application, contracts)
+    ^
+    |
+sdk            <- (imports all core packages)
+    ^
+    |
+server/web     <- (imports sdk and above)
+```
+
+### Package Responsibilities
+
+| Layer          | Package                   | Responsibility                     |
+| -------------- | ------------------------- | ---------------------------------- |
+| Domain         | `packages/domain`         | Business entities, port interfaces |
+| Domain         | `packages/contracts`      | DTOs, Zod validation schemas       |
+| Application    | `packages/application`    | Use cases, business workflows      |
+| Infrastructure | `packages/infrastructure` | Repository implementations         |
+| Infrastructure | `packages/db`             | Drizzle ORM schemas                |
+| Infrastructure | `packages/auth`           | Better-Auth configuration          |
+| API            | `packages/api`            | oRPC procedures                    |
+| SDK            | `packages/sdk`            | Backend module system              |
+| SDK            | `packages/sdk-react`      | Frontend module system             |
+
+---
+
+## Configuration
+
+### kuckit.config.ts
+
+```typescript
+import { defineConfig } from '@kuckit/sdk'
+
+export default defineConfig({
+	modules: ['@kuckit/users-module', '@acme/billing-module'],
+})
+```
+
+### Configuration Files (search order)
+
+1. `kuckit.config.ts`
+2. `kuckit.config.js`
+3. `.kuckitrc.ts`
+4. `.kuckitrc.js`
+5. `.kuckitrc` (JSON)
+
+### User Credentials
+
+Stored at: `~/.kuckit/config.json`
+
+### Infrastructure State
+
+Stored at: `.kuckit/infra.json`
+
+---
+
+## Common Patterns
+
+### Adding a New Feature
+
+1. Create domain entity in `packages/domain`
+2. Add DTOs/schemas in `packages/contracts`
+3. Implement use case in `packages/application`
+4. Create repository in `packages/infrastructure`
+5. Add oRPC procedure in `packages/api`
+6. Register in module's `register()` hook
+7. Add route in client module
+
+### Resolving Services with Types
+
+```typescript
+import type { Container } from '@kuckit/sdk'
+
+function createService(container: Container) {
+	const logger = container.resolve('logger')
+	const db = container.resolve('db')
+	// ...
+}
+```
+
+### Testing with Mock Services
+
+```typescript
+import { createTestContainer } from '@kuckit/sdk/testing'
+
+const container = await createTestContainer({
+	overrides: {
+		clock: asValue(new FakeClock()),
+		cacheStore: asValue(new InMemoryCacheStore()),
+	},
+})
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue                      | Solution                                                  |
+| -------------------------- | --------------------------------------------------------- |
+| Module not found           | Run `bunx kuckit discover` to find unregistered modules   |
+| Container resolution error | Check module's `register()` hook for missing dependencies |
+| Database connection failed | Verify `DATABASE_URL` environment variable                |
+| CLI auth expired           | Run `bunx kuckit auth login` to refresh token             |
+| Pulumi state issues        | Run `bunx kuckit infra repair --refresh`                  |
+
+### Debugging
+
+```bash
+# Check project setup
+bunx kuckit doctor
+
+# View infrastructure state
+bunx kuckit infra status
+
+# Stream logs
+bunx kuckit infra logs -f --severity ERROR
+```
+
+---
+
+## Key Source Files
+
+### CLI Entry Points
+
+| File                                | Purpose                 |
+| ----------------------------------- | ----------------------- |
+| `packages/kuckit-cli/src/bin.ts`    | CLI entry point         |
+| `packages/kuckit-cli/src/commands/` | Command implementations |
+
+### SDK Core
+
+| File                                        | Purpose                  |
+| ------------------------------------------- | ------------------------ |
+| `packages/sdk/src/core/container.ts`        | DI container setup       |
+| `packages/sdk/src/modules/define-module.ts` | Module definition helper |
+| `packages/sdk/src/modules/loader.ts`        | Module loading logic     |
+
+### Example Modules
+
+| Module          | Path                        |
+| --------------- | --------------------------- |
+| Users Module    | `packages/users-module/`    |
+| Landing Module  | `packages/landing-module/`  |
+| CLI Auth Module | `packages/cli-auth-module/` |
+
+---
+
+## Getting Help
+
+When working with Kuckit:
+
+1. **Read the AGENTS.md** in each package for development rules
+2. **Check ARCHITECTURE.md** for understanding the layer system
+3. **Use `kuckit doctor`** to validate your setup
+4. **Explore reference modules** (users-module) for implementation patterns
+
+For infrastructure issues, check `docs/TROUBLESHOOTING.md`