create-kuckit-app 2.0.2 → 2.1.0

package/templates/base/docs/MODULE_CSS.md

@@ -0,0 +1,343 @@
+# Module CSS Aggregator Pattern
+
+This guide covers how Kuckit handles CSS from modules, including how module authors should structure their styles and how app developers can manage module CSS imports.
+
+## Overview
+
+Kuckit uses a **CSS aggregator pattern** to manage styles from multiple modules. Instead of manually adding CSS imports for each module, the CLI automatically injects imports into a centralized aggregator file when you run `kuckit add`.
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        apps/web/src/index.css                       │
+│  ─────────────────────────────────────────────────────────────────  │
+│  @import "./kuckit-modules.css";   ◄── Single import                │
+│  @import "tailwindcss";                                             │
+└─────────────────────────────────────────────────────────────────────┘
+                                │
+                                ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                   apps/web/src/kuckit-modules.css                   │
+│  ─────────────────────────────────────────────────────────────────  │
+│  /* KUCKIT_MODULE_STYLES_START */                                   │
+│  @import "@kuckit/docs-module/styles.css";      ◄── Auto-injected   │
+│  @import "@acme/billing-module/styles.css";     ◄── by CLI          │
+│  /* KUCKIT_MODULE_STYLES_END */                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### How It Works
+
+1. **Module declares styles** via `kuckit.styles` in `package.json`
+2. **CLI injects import** into the aggregator when you run `kuckit add <module>`
+3. **App imports aggregator** once in `index.css`
+4. **Tailwind scans modules** via `@source` directives in each module's CSS
+
+---
+
+## Module Author Guide
+
+If you're building a Kuckit module with UI components, follow this guide to ensure your styles work correctly.
+
+### 1. Create a Styles File
+
+Create `src/styles.css` in your module with Tailwind source directives:
+
+```css
+/* src/styles.css */
+
+/* Tell Tailwind to scan this module's components for class names */
+@source "./client/**/*.tsx";
+@source "./ui/**/*.tsx";
+
+/* Optional: Add module-specific styles */
+.my-module-card {
+	@apply rounded-lg border bg-card p-4;
+}
+```
+
+> **Note**: The `@source` directive tells Tailwind where to look for class names when generating CSS. Without it, Tailwind won't include your component's utility classes.
+
+### 2. Export the Styles in package.json
+
+Add the styles file to your package exports and declare it in the `kuckit` metadata:
+
+```json
+{
+	"name": "@acme/billing-module",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./client": {
+			"types": "./src/client/index.ts",
+			"default": "./src/client/index.ts"
+		},
+		"./styles.css": "./src/styles.css"
+	},
+	"publishConfig": {
+		"exports": {
+			".": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"./client": {
+				"types": "./dist/client/index.d.ts",
+				"default": "./dist/client/index.js"
+			},
+			"./styles.css": "./dist/styles.css"
+		}
+	},
+	"kuckit": {
+		"id": "acme.billing",
+		"server": ".",
+		"client": "./client",
+		"styles": "./styles.css"
+	}
+}
+```
+
+### 3. Align Published Paths
+
+The `@source` paths must be valid **after publishing**. When your module is published:
+
+- Source files move from `src/` to `dist/`
+- The `@source` path is relative to where `styles.css` ends up
+
+**Development** (`src/styles.css`):
+
+```css
+@source "./client/**/*.tsx";
+```
+
+**Published** (`dist/styles.css`):
+
+```css
+@source "./client/**/*.tsx"; /* Still works if client/ is in dist/ */
+```
+
+> **Tip**: Use flat structure like `dist/client/` rather than deeply nested paths to avoid path mismatches.
+
+### 4. Include CSS in Build
+
+Ensure your build tool copies the CSS file to `dist/`. With `tsdown`:
+
+```json
+{
+	"scripts": {
+		"build": "tsdown && cp src/styles.css dist/"
+	}
+}
+```
+
+Or configure `tsdown` to handle CSS:
+
+```ts
+// tsdown.config.ts
+export default {
+	entry: ['src/index.ts', 'src/client/index.ts'],
+	format: ['esm'],
+	dts: true,
+	// CSS is copied via package.json "files" field
+}
+```
+
+---
+
+## App Developer Guide
+
+### New Projects
+
+New projects created with `create-kuckit` include the aggregator file pre-configured. No additional setup is needed—just run `kuckit add <module>` and the CLI handles everything.
+
+### How `kuckit add` Works
+
+When you run:
+
+```bash
+bunx kuckit add @acme/billing-module
+```
+
+The CLI:
+
+1. Installs the package
+2. Reads `kuckit.styles` from the module's `package.json`
+3. Injects `@import "@acme/billing-module/styles.css";` into `kuckit-modules.css`
+4. Wires server and client modules
+
+### Manual Installation
+
+If you're not using `kuckit add`, manually add the import to your aggregator:
+
+```css
+/* apps/web/src/kuckit-modules.css */
+
+/* KUCKIT_MODULE_STYLES_START */
+@import '@kuckit/docs-module/styles.css';
+@import '@acme/billing-module/styles.css'; /* Add this line */
+/* KUCKIT_MODULE_STYLES_END */
+```
+
+---
+
+## Troubleshooting
+
+### Missing Styles
+
+**Symptom**: Module components render without styling (unstyled buttons, missing colors).
+
+**Causes and fixes**:
+
+1. **Module not in aggregator**
+
+   ```bash
+   # Check if import exists
+   grep "billing-module" apps/web/src/kuckit-modules.css
+   ```
+
+   If missing, add it manually or re-run `kuckit add`.
+
+2. **Missing `@source` directive in module**
+
+   The module's `styles.css` must include `@source` directives pointing to its components:
+
+   ```css
+   @source "./client/**/*.tsx";
+   ```
+
+3. **Path mismatch after publishing**
+
+   If using a published module, ensure `@source` paths align with the `dist/` structure.
+
+4. **Tailwind not scanning node_modules**
+
+   In Tailwind v4, add this to your app's CSS:
+
+   ```css
+   @source "../../node_modules/@acme/billing-module/dist/**/*.{js,ts,tsx}";
+   ```
+
+### Duplicate Imports
+
+**Symptom**: CSS import appears twice in the aggregator.
+
+The CLI is idempotent—it checks for existing imports before adding. If you see duplicates:
+
+1. One may be inside markers, one outside
+2. Remove the duplicate outside the markers
+
+```css
+/* KUCKIT_MODULE_STYLES_START */
+@import '@acme/billing-module/styles.css';
+/* KUCKIT_MODULE_STYLES_END */
+
+/* Remove this duplicate if present: */
+/* @import "@acme/billing-module/styles.css"; */
+```
+
+### Aggregator File Missing
+
+**Symptom**: CLI warns "CSS aggregator not found".
+
+Create the aggregator file manually:
+
+```bash
+mkdir -p apps/web/src
+cat > apps/web/src/kuckit-modules.css << 'EOF'
+/**
+ * Kuckit Module CSS Aggregator
+ *
+ * Module CSS imports are automatically added here by `kuckit add`.
+ * Do not remove the marker comments.
+ */
+
+/* KUCKIT_MODULE_STYLES_START */
+/* KUCKIT_MODULE_STYLES_END */
+EOF
+```
+
+Then import it in your main CSS:
+
+```css
+/* apps/web/src/index.css */
+@import './kuckit-modules.css';
+@import 'tailwindcss';
+```
+
+### Migration from Manual Imports
+
+If your existing project has scattered module imports:
+
+1. **Create the aggregator** (see above)
+2. **Move module imports** from `index.css` to between the markers
+3. **Remove duplicate `@source`** directives (modules should include their own)
+4. **Test** by running `bun run dev` and verifying styles load
+
+Before:
+
+```css
+/* index.css - OLD */
+@import '@kuckit/docs-module/styles.css';
+@source "../../node_modules/@kuckit/docs-module/src/**/*.tsx";
+@import 'tailwindcss';
+```
+
+After:
+
+```css
+/* index.css - NEW */
+@import './kuckit-modules.css';
+@import 'tailwindcss';
+```
+
+```css
+/* kuckit-modules.css - NEW */
+/* KUCKIT_MODULE_STYLES_START */
+@import '@kuckit/docs-module/styles.css';
+/* KUCKIT_MODULE_STYLES_END */
+```
+
+---
+
+## Reference
+
+### Marker Comments
+
+The CLI uses these markers to identify where to inject imports:
+
+```css
+/* KUCKIT_MODULE_STYLES_START */
+/* ...imports go here... */
+/* KUCKIT_MODULE_STYLES_END */
+```
+
+Do not modify or remove these markers.
+
+### Module Metadata Schema
+
+```typescript
+interface KuckitMetadata {
+	id: string // e.g., "acme.billing"
+	server?: string // Server module path
+	client?: string // Client module path
+	styles?: string // CSS file path (e.g., "./styles.css")
+}
+```
+
+### CLI Behavior
+
+| Scenario                   | CLI Action                            |
+| -------------------------- | ------------------------------------- |
+| Module has `kuckit.styles` | Injects import into aggregator        |
+| Import already exists      | Skips (idempotent)                    |
+| Aggregator file missing    | Warns with manual instructions        |
+| CSS file doesn't exist     | Warns and skips injection             |
+| No `kuckit.styles`         | No CSS handling (backward compatible) |
+
+---
+
+## Related Documentation
+
+- [Module Development Guide](../packages/sdk/docs/MODULE_DEVELOPMENT.md)
+- [CLI Reference](../packages/kuckit-cli/AGENTS.md)
+- [@kuckit/docs-module](../packages/docs-module/SETUP.md) - Example module with CSS

package/templates/base/docs/MODULE_TESTING.md

@@ -0,0 +1,368 @@
+# Module Testing Guide
+
+> Testing Kuckit modules as standalone npm packages in scaffolded projects
+
+**See also**: [General Testing Guide](./TESTING.md) - Unit and integration testing for Kuckit apps
+
+## Overview
+
+This guide documents the workflow for testing Kuckit modules before publishing to npm. Testing in a scaffolded project provides high confidence that modules work correctly when consumed as external packages.
+
+**Key insight**: Testing with `file:` dependencies in a fresh scaffolded app simulates the real npm install experience, catching issues that unit tests miss.
+
+## Quick Reference
+
+```bash
+# 1. Build CLI tools (from monorepo root)
+cd packages/create-kuckit-app && bun run build && cd ../..
+cd packages/kuckit-cli && bun run build && cd ../..
+
+# 2. Scaffold test app using dist
+node packages/create-kuckit-app/dist/bin.js /tmp/kuckit-test-app --skip-install
+
+# 3. Prepare module (in temp directory)
+cp -r packages/my-module /tmp/my-module-test
+cd /tmp/my-module-test
+# Replace workspace:* with versions, build, etc.
+
+# 4. Install in test app
+cd /tmp/kuckit-test-app
+cp -r /tmp/my-module-test node_modules/@kuckit/my-module
+bun install
+
+# 5. Wire and test
+node /path/to/kuckit/packages/kuckit-cli/dist/bin.js add @kuckit/my-module --skip-install
+bun run db:push
+bun run dev
+```
+
+## Detailed Workflow
+
+### Step 1: Build CLI Tools and Scaffold Test App
+
+Build the CLI tools first (unpublished packages won't work with `bunx`):
+
+```bash
+# From monorepo root
+cd packages/create-kuckit-app && bun run build && cd ../..
+cd packages/kuckit-cli && bun run build && cd ../..
+```
+
+Then scaffold a test app using the built dist:
+
+```bash
+node packages/create-kuckit-app/dist/bin.js /tmp/kuckit-test-app --skip-install
+cd /tmp/kuckit-test-app
+```
+
+### Step 2: Prepare Module for Testing
+
+Copy the module to a temporary location and resolve workspace protocols:
+
+```bash
+# Copy module
+cp -r packages/my-module /tmp/my-module-test
+cd /tmp/my-module-test
+```
+
+#### 2.1 Replace Workspace Protocols
+
+Edit `package.json` to replace `workspace:*` and `catalog:` with actual versions:
+
+```json
+{
+	"peerDependencies": {
+		"@kuckit/sdk": "^2.0.0",
+		"@kuckit/api": "^2.0.0",
+		"drizzle-orm": "^0.44.0"
+	},
+	"dependencies": {
+		"zod": "^3.23.0"
+	}
+}
+```
+
+#### 2.2 Create Standalone tsconfig.json
+
+Remove `extends` that references parent monorepo config:
+
+```json
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"jsx": "react-jsx",
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"declaration": true,
+		"declarationMap": true,
+		"outDir": "dist",
+		"rootDir": "src"
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}
+```
+
+#### 2.3 Build the Module
+
+```bash
+bun add tsdown typescript -d
+bun run tsdown
+```
+
+#### 2.4 Update Package.json Exports
+
+Match exports to build output (tsdown uses `.mjs`/`.d.mts` extensions):
+
+```json
+{
+	"exports": {
+		".": {
+			"types": "./dist/server/module.d.mts",
+			"default": "./dist/server/module.mjs"
+		},
+		"./client": {
+			"types": "./dist/client/index.d.mts",
+			"default": "./dist/client/index.mjs"
+		}
+	}
+}
+```
+
+### Step 3: Install Module in Test App
+
+**Important**: Copy directly into `node_modules` rather than using `file:` protocol. File dependencies resolve from physical path, causing peer dependency resolution failures.
+
+```bash
+cd /tmp/kuckit-test-app
+
+# Install dependencies first
+bun install
+
+# Copy built module into node_modules
+cp -r /tmp/my-module-test node_modules/@kuckit/my-module
+```
+
+### Step 4: Wire Up the Module
+
+Use the CLI to register the module:
+
+```bash
+node /path/to/kuckit/packages/kuckit-cli/dist/bin.js add @kuckit/my-module --skip-install
+```
+
+Or manually add to `kuckit.config.ts`:
+
+```typescript
+export default defineConfig({
+	modules: [
+		{
+			package: '@kuckit/my-module',
+			config: {
+				// Module-specific configuration
+				apiKey: process.env.MY_MODULE_API_KEY ?? 'test_key',
+				environment: 'sandbox',
+			},
+		},
+	],
+})
+```
+
+### Step 5: Verification Commands
+
+Run these in sequence to verify the module works:
+
+```bash
+# 1. Database schema
+bun run db:push
+# Verifies: Drizzle can load module schema exports
+
+# 2. Type checking
+bun run check-types
+# Verifies: TypeScript compilation succeeds
+
+# 3. Server runtime
+bun run dev
+# Verifies: Module loads, DI registers, API routes work
+
+# 4. API endpoints (in another terminal)
+curl http://localhost:3000/api/health
+curl http://localhost:3000/rpc/my-module/list
+
+# 5. Client routes
+# Open browser to http://localhost:5173/my-route
+```
+
+## Common Issues and Solutions
+
+### Issue: Cannot find module 'drizzle-orm/pg-core'
+
+**Symptom**: `drizzle-kit` fails when loading module schema files.
+
+**Cause**: `drizzle-kit` tries to load TypeScript source files instead of compiled JavaScript.
+
+**Solution**: Build the module first so `drizzle-kit` reads compiled `.js` files:
+
+```bash
+cd /tmp/my-module-test
+bun add tsdown typescript -d
+bun run tsdown
+```
+
+### Issue: Cannot find package 'express'
+
+**Symptom**: `ResolveMessage: Cannot find package 'express' from '/tmp/my-module-test/...'`
+
+**Cause**: Modules using Express Router need it as a peer dependency. File dependencies resolve from physical location, not `node_modules`.
+
+**Solution**:
+
+1. Add `express` to `peerDependencies` in module's `package.json`:
+
+   ```json
+   {
+   	"peerDependencies": {
+   		"express": "^4.0.0 || ^5.0.0"
+   	}
+   }
+   ```
+
+2. Copy module into `node_modules` instead of using `file:` protocol:
+   ```bash
+   cp -r /tmp/my-module-test node_modules/@kuckit/my-module
+   ```
+
+### Issue: Module config undefined
+
+**Symptom**: `undefined is not an object (evaluating 'Object.keys(config.something)')`
+
+**Cause**: Module configuration not passed in `kuckit.config.ts`.
+
+**Solution**: Add config block with required fields:
+
+```typescript
+{
+  package: '@kuckit/my-module',
+  config: {
+    apiKey: process.env.API_KEY ?? 'test_key',
+    webhookSecret: process.env.WEBHOOK_SECRET ?? 'test_secret',
+    // All required config fields...
+  },
+}
+```
+
+### Issue: Cannot read file: components/ui/...
+
+**Symptom**: Client build fails with missing UI component errors.
+
+**Cause**: Module uses `@/components/ui/*` imports but host app doesn't have shadcn components.
+
+**Solution**: Install required shadcn/ui components in the host app:
+
+```bash
+cd apps/web
+bunx --bun shadcn@latest init --yes
+bunx --bun shadcn@latest add card badge alert button skeleton --yes
+```
+
+**Best practice**: Document required shadcn components in module's `AGENTS.md`.
+
+### Issue: Build output extension mismatch
+
+**Symptom**: `Module not found` errors for `.js` files when output is `.mjs`.
+
+**Cause**: `package.json` exports reference `.js` but `tsdown` outputs `.mjs`.
+
+**Solution**: Align exports with actual output:
+
+```json
+{
+	"exports": {
+		".": {
+			"types": "./dist/server/module.d.mts",
+			"default": "./dist/server/module.mjs"
+		}
+	}
+}
+```
+
+## Test Checklist
+
+Use this checklist when testing a new module:
+
+```
+Pre-test Setup:
+- [ ] Scaffolded fresh test app
+- [ ] Replaced workspace:* protocols with versions
+- [ ] Created standalone tsconfig.json
+- [ ] Built module successfully
+- [ ] Updated package.json exports to match build output
+- [ ] Copied module to node_modules (not file: protocol)
+
+Verification:
+- [ ] bun run db:push - Schema exports work
+- [ ] bun run check-types - TypeScript compiles
+- [ ] bun run dev - Server loads module
+- [ ] API endpoints respond correctly
+- [ ] Client routes render
+- [ ] Authentication works (if applicable)
+
+Documentation:
+- [ ] Required environment variables documented
+- [ ] Required shadcn components listed
+- [ ] Configuration example in AGENTS.md
+```
+
+## Test Locations
+
+Standard test locations used in the workflow:
+
+| Purpose             | Path                              |
+| ------------------- | --------------------------------- |
+| Scaffolded test app | `/tmp/kuckit-test-app`            |
+| Module copy         | `/tmp/{module-name}-test`         |
+| CLI binary          | `packages/kuckit-cli/dist/bin.js` |
+
+## Environment Variables Template
+
+For modules requiring configuration, create `.env` in the test app:
+
+```bash
+# Database (required by all Kuckit apps)
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kuckit_test
+
+# Auth (required)
+BETTER_AUTH_SECRET=test-secret-change-in-production
+BETTER_AUTH_URL=http://localhost:3000
+
+# Module-specific (example for polar-payments)
+POLAR_ACCESS_TOKEN=polar_at_test
+POLAR_WEBHOOK_SECRET=whsec_test
+POLAR_PLAN_MAPPING={"test_product":"pro"}
+POLAR_ORGANIZATION_ID=org_test
+POLAR_ENVIRONMENT=sandbox
+```
+
+## Cleanup
+
+After testing, stop containers and remove test artifacts:
+
+```bash
+# Stop database container
+cd /tmp/kuckit-test-app
+docker compose down
+
+# Remove test artifacts
+rm -rf /tmp/kuckit-test-app
+rm -rf /tmp/{module-name}-test
+```
+
+## Related Documentation
+
+- [Module Development Guide](../packages/sdk/docs/MODULE_DEVELOPMENT.md)
+- [CLI add command](../packages/kuckit-cli/AGENTS.md#add)
+- [SDK Module System](../packages/sdk/AGENTS.md)