create-kuckit-app 0.1.1 → 0.2.0

package/templates/base/.claude/skills/kuckit/references/MODULE-DEVELOPMENT.md

@@ -0,0 +1,581 @@
+# Kuckit Module Development Reference
+
+Complete guide for developing Kuckit modules.
+
+## Module Structure
+
+### Generated Module Layout
+
+```
+packages/billing-module/
+├── src/
+│   ├── module.ts              # Server module definition
+│   ├── index.ts               # Public exports
+│   ├── client/
+│   │   ├── module.ts          # Client module definition
+│   │   └── index.ts           # Client exports
+│   └── server/
+│       ├── schema/
+│       │   └── index.ts       # Drizzle schema
+│       ├── repositories/
+│       │   └── invoice.ts     # Repository implementations
+│       └── use-cases/
+│           └── create-invoice.ts
+├── package.json
+└── tsconfig.json
+```
+
+### package.json Metadata
+
+```json
+{
+	"name": "@acme/billing-module",
+	"version": "1.0.0",
+	"type": "module",
+	"kuckit": {
+		"id": "acme.billing",
+		"server": "./dist/module.js",
+		"client": "./dist/client/module.js",
+		"schema": "./src/server/schema/index.ts"
+	},
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		},
+		"./client": {
+			"import": "./dist/client/index.js",
+			"types": "./dist/client/index.d.ts"
+		}
+	},
+	"peerDependencies": {
+		"@kuckit/sdk": ">=0.1.0"
+	}
+}
+```
+
+---
+
+## Server Module Definition
+
+### Full Example
+
+```typescript
+// src/module.ts
+import {
+	defineKuckitModule,
+	asClass,
+	asFunction,
+	asValue,
+	type RegisterContext,
+	type BootstrapContext,
+} from '@kuckit/sdk'
+import { DrizzleInvoiceRepository } from './server/repositories/invoice'
+import { makeCreateInvoiceUseCase } from './server/use-cases/create-invoice'
+import { createBillingRouter } from './server/api/router'
+
+// Module configuration interface
+interface BillingModuleConfig {
+	currency: string
+	taxRate: number
+	enableNotifications: boolean
+}
+
+// Default configuration
+const defaultConfig: BillingModuleConfig = {
+	currency: 'USD',
+	taxRate: 0.1,
+	enableNotifications: true,
+}
+
+export const kuckitModule = defineKuckitModule<BillingModuleConfig>({
+	// Required: Unique module identifier
+	id: 'acme.billing',
+
+	// Optional: Display name for UI
+	displayName: 'Billing',
+
+	// Optional: Module description
+	description: 'Invoice and payment processing',
+
+	// Optional: Semantic version
+	version: '1.0.0',
+
+	// Optional: Module dependencies (other module IDs)
+	dependencies: ['kuckit.users'],
+
+	// Register DI dependencies
+	register(ctx: RegisterContext<BillingModuleConfig>) {
+		const config = { ...defaultConfig, ...ctx.config }
+
+		ctx.container.register({
+			// Scoped = new instance per request
+			invoiceRepository: asClass(DrizzleInvoiceRepository).scoped(),
+
+			// Singleton = shared instance
+			billingConfig: asValue(config),
+
+			// Factory function
+			createInvoice: asFunction(makeCreateInvoiceUseCase).scoped(),
+		})
+	},
+
+	// Register API routes
+	registerApi(ctx) {
+		ctx.addApiRegistration({
+			type: 'rpc-router',
+			name: 'billing',
+			router: createBillingRouter(ctx.container),
+		})
+	},
+
+	// Startup logic (after all modules registered)
+	onBootstrap(ctx: BootstrapContext<BillingModuleConfig>) {
+		const logger = ctx.container.resolve('logger')
+		const config = { ...defaultConfig, ...ctx.config }
+		logger.info(`Billing module started with currency: ${config.currency}`)
+
+		// Subscribe to events
+		const eventBus = ctx.container.resolve('eventBus')
+		eventBus.subscribe('user.created', async (event) => {
+			logger.info(`New user created: ${event.userId}`)
+		})
+	},
+
+	// Cleanup logic (on shutdown)
+	onShutdown(ctx) {
+		const logger = ctx.container.resolve('logger')
+		logger.info('Billing module shutting down')
+	},
+})
+```
+
+### Lifecycle Hooks
+
+| Hook               | When Called                  | Purpose                            |
+| ------------------ | ---------------------------- | ---------------------------------- |
+| `register(ctx)`    | Module loading               | Register DI dependencies           |
+| `registerApi(ctx)` | After register               | Register API routes                |
+| `onBootstrap(ctx)` | After all modules registered | Startup logic, event subscriptions |
+| `onShutdown(ctx)`  | Container disposal           | Cleanup resources                  |
+
+### Context Objects
+
+**RegisterContext:**
+
+```typescript
+interface RegisterContext<TConfig> {
+	container: AwilixContainer
+	config: TConfig
+	env: 'development' | 'production' | 'test'
+}
+```
+
+**BootstrapContext:**
+
+```typescript
+interface BootstrapContext<TConfig> {
+	container: AwilixContainer
+	config: TConfig
+	env: string
+	logger: Logger
+}
+```
+
+---
+
+## Client Module Definition
+
+### Full Example
+
+```typescript
+// src/client/module.ts
+import { defineKuckitClientModule } from '@kuckit/sdk-react'
+import { CreditCard, FileText, Settings } from 'lucide-react'
+
+// Lazy load components
+const BillingDashboard = React.lazy(() => import('./pages/Dashboard'))
+const InvoicesPage = React.lazy(() => import('./pages/Invoices'))
+const InvoiceDetail = React.lazy(() => import('./pages/InvoiceDetail'))
+const BillingSettings = React.lazy(() => import('./pages/Settings'))
+
+export const kuckitClientModule = defineKuckitClientModule({
+	// Must match server module ID
+	id: 'acme.billing',
+
+	// Route registrations
+	routes: [
+		{
+			path: '/billing',
+			component: BillingDashboard,
+			meta: { title: 'Billing Dashboard' },
+		},
+		{
+			path: '/billing/invoices',
+			component: InvoicesPage,
+			meta: { title: 'Invoices' },
+		},
+		{
+			path: '/billing/invoices/$invoiceId',
+			component: InvoiceDetail,
+			meta: { title: 'Invoice Details' },
+		},
+		{
+			path: '/billing/settings',
+			component: BillingSettings,
+			meta: { title: 'Billing Settings' },
+		},
+	],
+
+	// Navigation items
+	navItems: [
+		{
+			label: 'Billing',
+			href: '/billing',
+			icon: CreditCard,
+			children: [
+				{ label: 'Dashboard', href: '/billing' },
+				{ label: 'Invoices', href: '/billing/invoices', icon: FileText },
+				{ label: 'Settings', href: '/billing/settings', icon: Settings },
+			],
+		},
+	],
+
+	// UI slots (for shell integration)
+	slots: {
+		'header.actions': HeaderActions,
+		'sidebar.footer': BillingStatus,
+	},
+})
+```
+
+### Route Definition
+
+```typescript
+interface RouteDefinition {
+	path: string // TanStack Router path
+	component: React.ComponentType // Page component
+	meta?: {
+		title?: string // Page title
+		requiresAuth?: boolean // Auth required
+		permissions?: string[] // Required permissions
+	}
+}
+```
+
+### Navigation Item Definition
+
+```typescript
+interface NavItem {
+	label: string // Display text
+	href: string // Route path
+	icon?: React.ComponentType // Icon component
+	children?: NavItem[] // Nested items
+	badge?: string | number // Badge content
+	hidden?: boolean | (() => boolean)
+}
+```
+
+---
+
+## DI Registration Patterns
+
+### Awilix Helpers
+
+```typescript
+import { asClass, asFunction, asValue } from '@kuckit/sdk'
+
+// Class registration (scoped = new per request)
+invoiceRepository: asClass(DrizzleInvoiceRepository).scoped()
+
+// Class registration (singleton = shared)
+emailService: asClass(EmailService).singleton()
+
+// Factory function
+createInvoice: asFunction(({ invoiceRepository, logger }) => {
+	return new CreateInvoiceUseCase(invoiceRepository, logger)
+}).scoped()
+
+// Plain value
+billingConfig: asValue({ currency: 'USD', taxRate: 0.1 })
+```
+
+### Resolving Dependencies
+
+```typescript
+// In a use case factory
+export function makeCreateInvoiceUseCase({ invoiceRepository, logger, eventBus }) {
+	return async function createInvoice(input: CreateInvoiceInput) {
+		const invoice = await invoiceRepository.create(input)
+		await eventBus.publish('invoice.created', { invoiceId: invoice.id })
+		logger.info(`Invoice created: ${invoice.id}`)
+		return invoice
+	}
+}
+
+// In a class constructor
+export class DrizzleInvoiceRepository {
+	constructor(private deps: { db: DrizzleInstance; logger: Logger }) {}
+
+	async findById(id: string) {
+		return this.deps.db.query.invoices.findFirst({
+			where: eq(invoices.id, id),
+		})
+	}
+}
+```
+
+---
+
+## API Registration
+
+### oRPC Router Example
+
+```typescript
+// src/server/api/router.ts
+import { createORPCRouter, createProcedure } from '@kuckit/api'
+import type { AwilixContainer } from 'awilix'
+
+export function createBillingRouter(container: AwilixContainer) {
+	return createORPCRouter({
+		// List invoices
+		list: createProcedure()
+			.input(listInvoicesSchema)
+			.query(async ({ input, ctx }) => {
+				const invoiceRepository = container.resolve('invoiceRepository')
+				return invoiceRepository.findAll(input)
+			}),
+
+		// Get single invoice
+		get: createProcedure()
+			.input(z.object({ id: z.string() }))
+			.query(async ({ input }) => {
+				const invoiceRepository = container.resolve('invoiceRepository')
+				return invoiceRepository.findById(input.id)
+			}),
+
+		// Create invoice
+		create: createProcedure()
+			.input(createInvoiceSchema)
+			.mutation(async ({ input }) => {
+				const createInvoice = container.resolve('createInvoice')
+				return createInvoice(input)
+			}),
+	})
+}
+```
+
+### Registration in Module
+
+```typescript
+registerApi(ctx) {
+  ctx.addApiRegistration({
+    type: 'rpc-router',
+    name: 'billing',  // Accessible at /api/billing/*
+    router: createBillingRouter(ctx.container),
+  })
+}
+```
+
+---
+
+## Database Schema
+
+### Drizzle Schema Example
+
+```typescript
+// src/server/schema/index.ts
+import { pgTable, uuid, text, timestamp, numeric } from 'drizzle-orm/pg-core'
+import { users } from '@kuckit/db'
+
+export const invoices = pgTable('invoices', {
+	id: uuid('id').primaryKey().defaultRandom(),
+	userId: uuid('user_id')
+		.references(() => users.id)
+		.notNull(),
+	amount: numeric('amount', { precision: 10, scale: 2 }).notNull(),
+	currency: text('currency').default('USD').notNull(),
+	status: text('status').default('pending').notNull(),
+	createdAt: timestamp('created_at').defaultNow().notNull(),
+	updatedAt: timestamp('updated_at').defaultNow().notNull(),
+})
+
+export const invoiceItems = pgTable('invoice_items', {
+	id: uuid('id').primaryKey().defaultRandom(),
+	invoiceId: uuid('invoice_id')
+		.references(() => invoices.id)
+		.notNull(),
+	description: text('description').notNull(),
+	quantity: numeric('quantity', { precision: 10, scale: 2 }).notNull(),
+	unitPrice: numeric('unit_price', { precision: 10, scale: 2 }).notNull(),
+})
+```
+
+### Schema Discovery
+
+The CLI automatically discovers schemas from:
+
+1. `kuckit.schema` field in package.json
+2. `src/server/schema/index.ts` (convention)
+3. `src/schema/index.ts` (convention)
+
+---
+
+## Event System
+
+### Publishing Events
+
+```typescript
+onBootstrap(ctx) {
+  const eventBus = ctx.container.resolve('eventBus')
+
+  // Publish an event
+  await eventBus.publish('invoice.created', {
+    invoiceId: '123',
+    userId: '456',
+    amount: 100.00,
+  })
+}
+```
+
+### Subscribing to Events
+
+```typescript
+onBootstrap(ctx) {
+  const eventBus = ctx.container.resolve('eventBus')
+
+  // Subscribe to events from other modules
+  eventBus.subscribe('user.created', async (event) => {
+    const logger = ctx.container.resolve('logger')
+    logger.info(`New user created, initializing billing: ${event.userId}`)
+  })
+
+  eventBus.subscribe('payment.received', async (event) => {
+    const invoiceRepository = ctx.container.resolve('invoiceRepository')
+    await invoiceRepository.markPaid(event.invoiceId)
+  })
+}
+```
+
+---
+
+## Testing Modules
+
+### Test Container Setup
+
+```typescript
+import { createTestContainer } from '@kuckit/sdk/testing'
+import { asValue } from '@kuckit/sdk'
+import { kuckitModule } from '../src/module'
+
+describe('BillingModule', () => {
+	let container: AwilixContainer
+
+	beforeEach(async () => {
+		container = await createTestContainer({
+			modules: [{ module: kuckitModule, config: { currency: 'USD' } }],
+			overrides: {
+				// Mock external dependencies
+				emailService: asValue({ send: vi.fn() }),
+				clock: asValue(new FakeClock()),
+			},
+		})
+	})
+
+	afterEach(async () => {
+		await disposeContainer(container)
+	})
+
+	it('creates an invoice', async () => {
+		const createInvoice = container.resolve('createInvoice')
+		const invoice = await createInvoice({
+			userId: 'user-123',
+			amount: 100.0,
+		})
+		expect(invoice.id).toBeDefined()
+	})
+})
+```
+
+### Mocking Services
+
+```typescript
+// Mock logger
+const mockLogger = {
+	info: vi.fn(),
+	warn: vi.fn(),
+	error: vi.fn(),
+	debug: vi.fn(),
+}
+
+// Mock database
+const mockDb = {
+	query: {
+		invoices: {
+			findFirst: vi.fn(),
+			findMany: vi.fn(),
+		},
+	},
+	insert: vi.fn(),
+}
+
+container = await createTestContainer({
+	overrides: {
+		logger: asValue(mockLogger),
+		db: asValue(mockDb),
+	},
+})
+```
+
+---
+
+## Best Practices
+
+### Module ID Naming
+
+```
+organization.modulename
+
+Examples:
+- kuckit.users
+- acme.billing
+- mycompany.analytics
+```
+
+### Dependency Injection
+
+- Use `scoped()` for request-specific services (repositories, use cases)
+- Use `singleton()` for shared services (config, email client)
+- Use `asValue()` for configuration objects
+- Always inject dependencies via constructor/factory params
+
+### Error Handling
+
+```typescript
+import { ModuleError } from '@kuckit/sdk'
+
+export class InvoiceNotFoundError extends ModuleError {
+	constructor(invoiceId: string) {
+		super(`Invoice not found: ${invoiceId}`, 'INVOICE_NOT_FOUND')
+	}
+}
+```
+
+### Logging
+
+```typescript
+onBootstrap(ctx) {
+  const logger = ctx.container.resolve('logger')
+
+  // Use structured logging
+  logger.info('Module started', {
+    moduleId: 'acme.billing',
+    config: ctx.config,
+  })
+
+  // Log levels: debug, info, warn, error
+  logger.debug('Detailed debug info')
+  logger.warn('Warning message')
+  logger.error('Error occurred', { error: err })
+}
+```

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

@@ -0,0 +1,112 @@
+# Kuckit Package Reference
+
+Quick reference for all packages in the Kuckit monorepo.
+
+## Package Locations
+
+| Package                 | Path                                                                 | Description                          |
+| ----------------------- | -------------------------------------------------------------------- | ------------------------------------ |
+| @kuckit/sdk             | `/Users/themrb/Documents/personal/kuckit/packages/sdk`               | Backend DI container & module system |
+| @kuckit/sdk-react       | `/Users/themrb/Documents/personal/kuckit/packages/sdk-react`         | Frontend module system               |
+| @kuckit/cli             | `/Users/themrb/Documents/personal/kuckit/packages/kuckit-cli`        | CLI tooling                          |
+| create-kuckit-app       | `/Users/themrb/Documents/personal/kuckit/packages/create-kuckit-app` | Project scaffolding                  |
+| @kuckit/domain          | `/Users/themrb/Documents/personal/kuckit/packages/domain`            | Business entities                    |
+| @kuckit/application     | `/Users/themrb/Documents/personal/kuckit/packages/application`       | Use cases                            |
+| @kuckit/contracts       | `/Users/themrb/Documents/personal/kuckit/packages/contracts`         | DTOs & Zod schemas                   |
+| @kuckit/infrastructure  | `/Users/themrb/Documents/personal/kuckit/packages/infrastructure`    | Repository implementations           |
+| @kuckit/api             | `/Users/themrb/Documents/personal/kuckit/packages/api`               | oRPC procedures                      |
+| @kuckit/db              | `/Users/themrb/Documents/personal/kuckit/packages/db`                | Drizzle ORM schemas                  |
+| @kuckit/auth            | `/Users/themrb/Documents/personal/kuckit/packages/auth`              | Better-Auth config                   |
+| @kuckit/infra           | `/Users/themrb/Documents/personal/kuckit/packages/infra`             | Pulumi infrastructure                |
+| @kuckit/users-module    | `/Users/themrb/Documents/personal/kuckit/packages/users-module`      | Reference module                     |
+| @kuckit/landing-module  | `/Users/themrb/Documents/personal/kuckit/packages/landing-module`    | Landing page module                  |
+| @kuckit/cli-auth-module | `/Users/themrb/Documents/personal/kuckit/packages/cli-auth-module`   | CLI auth module                      |
+
+## Key Files Per Package
+
+### @kuckit/sdk
+
+| File                           | Purpose                       |
+| ------------------------------ | ----------------------------- |
+| `src/index.ts`                 | Public exports                |
+| `src/core/container.ts`        | DI container creation         |
+| `src/core/core.module.ts`      | Core services registration    |
+| `src/modules/define-module.ts` | `defineKuckitModule()` helper |
+| `src/modules/loader.ts`        | Module loading logic          |
+| `src/modules/types.ts`         | Module type definitions       |
+| `src/config/loader.ts`         | Configuration loading         |
+| `src/schema/registry.ts`       | Schema registry               |
+
+### @kuckit/cli
+
+| File                              | Purpose                        |
+| --------------------------------- | ------------------------------ |
+| `src/bin.ts`                      | CLI entry point (Commander.js) |
+| `src/commands/generate-module.ts` | Module scaffolding             |
+| `src/commands/add-module.ts`      | Module installation            |
+| `src/commands/discover-module.ts` | Module discovery               |
+| `src/commands/doctor.ts`          | Project validation             |
+| `src/commands/auth.ts`            | Authentication commands        |
+| `src/commands/db.ts`              | Database commands              |
+| `src/commands/infra/*.ts`         | Infrastructure commands        |
+| `src/lib/credentials.ts`          | Token storage                  |
+| `src/lib/sdk-loader.ts`           | Dynamic SDK loading            |
+
+### @kuckit/sdk-react
+
+| File                                  | Purpose                  |
+| ------------------------------------- | ------------------------ |
+| `src/modules/define-client-module.ts` | Client module definition |
+| `src/modules/loader.ts`               | Client module loading    |
+| `src/registries/route-registry.ts`    | Route management         |
+| `src/registries/nav-registry.ts`      | Navigation management    |
+| `src/registries/slot-registry.ts`     | UI slot management       |
+| `src/context/*.ts`                    | React context providers  |
+
+## Import Patterns
+
+```typescript
+// SDK imports
+import {
+	createKuckitContainer,
+	loadKuckitModules,
+	defineKuckitModule,
+	asClass,
+	asFunction,
+	asValue,
+	disposeContainer,
+} from '@kuckit/sdk'
+
+// React SDK imports
+import {
+	defineKuckitClientModule,
+	loadKuckitClientModules,
+	KuckitNavProvider,
+	useKuckitNav,
+} from '@kuckit/sdk-react'
+
+// CLI programmatic usage
+import { generateModule, addModule, discoverModules } from '@kuckit/cli'
+
+// Domain imports (from within the monorepo)
+import { User, type UserPort } from '@kuckit/domain'
+
+// Contracts imports
+import { CreateUserInput, UserDTO, createUserSchema } from '@kuckit/contracts'
+```
+
+## Package Dependencies
+
+### What Each Package Can Import
+
+| Package        | Allowed Imports                |
+| -------------- | ------------------------------ |
+| domain         | (none - pure business logic)   |
+| contracts      | zod                            |
+| application    | domain                         |
+| infrastructure | domain, external libs          |
+| api            | domain, application, contracts |
+| sdk            | all core packages, awilix      |
+| sdk-react      | sdk types                      |
+| server         | ALL packages                   |
+| web            | sdk-react, contracts           |