create-lego-one 2.0.10 → 2.0.13

package/template/docs/checkpoints/framework/phase-11-testing.md

@@ -0,0 +1,264 @@
+# Phase 11: Testing - Complete
+
+## Overview
+
+Implemented a comprehensive testing setup for the Lego-One SaaS boilerplate with Vitest for unit testing and Playwright for E2E testing. Established test infrastructure, utilities, and baseline tests for key components.
+
+## Test Statistics
+
+- **Test Files:** 6
+- **Total Tests:** 32
+- **Passing:** 32 (100%)
+- **Coverage:** 11.8% statements, 5.75% branches, 10% functions, 12.4% lines
+
+## File Structure
+
+```
+host/
+├── vitest.config.ts
+├── playwright.config.ts
+├── src/
+│   ├── test/
+│   │   ├── setup.ts
+│   │   └── utils.tsx
+│   ├── kernel/
+│   │   └── __tests__/
+│   │       ├── rbac-hooks.test.tsx
+│   │       ├── rbac-utils.test.ts
+│   │       └── lib-utils.test.ts
+│   └── kernel/components/
+│       └── __tests__/
+│           ├── Button.test.tsx
+│           ├── Input.test.tsx
+│           └── Badge.test.tsx
+└── e2e/
+    ├── auth.spec.ts
+    └── layout.spec.ts
+```
+
+## Testing Stack
+
+### Unit Testing
+- **Vitest** v4.0.18 - Fast unit test framework
+- **@testing-library/react** v16.3.2 - React component testing
+- **@testing-library/user-event** v14.6.1 - User interaction simulation
+- **@testing-library/jest-dom** v6.9.1 - Custom Jest matchers
+- **@vitest/coverage-v8** v4.0.18 - Code coverage reporting
+- **jsdom** v27.4.0 - DOM simulation
+
+### E2E Testing
+- **@playwright/test** v1.58.0 - Cross-browser E2E testing
+- **Browsers:** Chromium, Firefox, WebKit
+
+## Test Files Created
+
+### Unit Tests
+
+1. **rbac-hooks.test.tsx** (4 tests)
+   - useCurrentOrganization state management
+   - Query client clearing on organization change
+   - useUserPermissions authentication checks
+
+2. **rbac-utils.test.ts** (4 tests)
+   - initializeFirstOrganization with existing org
+   - initializeFirstOrganization creates new org
+   - initializeFirstOrganization error handling
+   - initializeFirstOrganization edge cases (no email)
+
+3. **lib-utils.test.ts** (7 tests)
+   - cn() class merging
+   - cn() with conditional classes
+   - cn() with undefined/null values
+   - cn() Tailwind conflict resolution
+   - cn() empty input handling
+   - cn() with arrays
+   - cn() with objects
+
+4. **Button.test.tsx** (5 tests)
+   - Children rendering
+   - onClick handler
+   - Disabled state
+   - Variant classes (default, destructive, outline, ghost)
+   - Size classes (default, sm, lg, icon)
+
+5. **Input.test.tsx** (6 tests)
+   - Element rendering
+   - Text input handling
+   - onChange callback
+   - Disabled state
+   - Custom className
+   - Standard input props
+
+6. **Badge.test.tsx** (6 tests)
+   - Children rendering
+   - Default variant
+   - Secondary variant
+   - Destructive variant
+   - Outline variant
+   - Custom className
+
+### E2E Tests
+
+1. **auth.spec.ts** (4 tests)
+   - Sign in page visibility
+   - Sign in form elements
+   - Validation errors
+   - Password visibility toggle
+
+2. **layout.spec.ts** (4 tests)
+   - Sidebar rendering
+   - Top bar rendering
+   - Navigation links
+   - Mobile responsiveness
+
+## Configuration Files
+
+### vitest.config.ts
+```typescript
+- jsdom environment
+- Global test setup
+- Coverage reporting with v8
+- Path aliases (@ -> src)
+- Custom test file pattern
+```
+
+### playwright.config.ts
+```typescript
+- Multi-browser testing (Chromium, Firefox, WebKit)
+- Automatic web server startup
+- HTML reporter
+- Trace on retry
+- Reuse existing server in dev
+```
+
+### test/setup.ts
+```typescript
+- @testing-library/jest-dom setup
+- Auto cleanup after each test
+- PocketBase mocking
+- Window bridge mocking (__LEGO_KERNEL_STATE__, __LEGO_CHANNEL_BUS__)
+- IntersectionObserver mocking
+- ResizeObserver mocking
+- matchMedia mocking
+```
+
+### test/utils.tsx
+```typescript
+- Custom render() with QueryClient and Router providers
+- Mock data generators (mockUser, mockOrganization, mockAuthState)
+- setupMockState() and clearMockState() helpers
+```
+
+## NPM Scripts
+
+```json
+{
+  "test": "vitest",
+  "test:ui": "vitest --ui",
+  "test:coverage": "vitest --coverage",
+  "test:e2e": "playwright test",
+  "test:e2e:ui": "playwright test --ui",
+  "test:e2e:debug": "playwright test --debug"
+}
+```
+
+## Coverage Breakdown
+
+### 100% Coverage
+- `components/ui/badge.tsx`
+- `components/ui/button.tsx`
+- `components/ui/input.tsx`
+- `rbac/utils.ts`
+
+### Partial Coverage
+- `rbac/hooks.ts` - 9.3% (only organization and permissions hooks tested)
+- `lib/utils.ts` - 6.25% (only cn() function tested)
+- `channels/ChannelBus.ts` - 7% (basic mocking in setup)
+- `shared-state/store.ts` - 22.72% (Zustand store partially tested)
+
+### No Coverage Yet
+- `rbac/service.ts` - Complex PocketBase service layer
+- `channels/plugin-hooks.ts` - Plugin channel hooks
+- `auth/` modules - Authentication hooks and services
+- `providers/` - React context providers
+- `plugins/` - Plugin system components
+
+## Testing Patterns
+
+### Hook Testing
+```typescript
+- Use renderHook from @testing-library/react
+- Mock PocketBase with vi.mock
+- Create QueryClient for each test
+- Test both success and error states
+- Verify query invalidation
+```
+
+### Component Testing
+```typescript
+- Use render() from @testing-library/react
+- Use userEvent for realistic interactions
+- Test props (variant, size, disabled, etc.)
+- Verify className application
+- Test event handlers
+```
+
+### E2E Testing
+```typescript
+- Use page.goto() for navigation
+- Use locators for element selection
+- Test user flows (sign in, navigation)
+- Test responsive behavior
+- Use filters for dynamic elements
+```
+
+## Next Steps for Coverage
+
+### High Priority
+1. **RBAC Service** - Test PocketBase CRUD operations
+2. **Auth Hooks** - Test authentication flow hooks
+3. **Plugin System** - Test plugin loader and slot injection
+
+### Medium Priority
+1. **Channel Hooks** - Test channel subscription/messaging
+2. **Providers** - Test context provider behavior
+3. **Layout Components** - Test Sidebar, Topbar, main layout
+
+### Lower Priority
+1. **UI Components** - Add tests for remaining components
+2. **Pages** - Test page-level components and routing
+
+## Notes
+
+- Tests are fast (1.26s for 32 tests)
+- UI component tests are slower due to React rendering
+- Coverage baseline established for future development
+- E2E tests require dev server to run
+- Mock setup handles PocketBase and window bridge
+- Tests use Vitest's watch mode for development
+- Coverage report generated in `coverage/index.html`
+
+## Running Tests
+
+```bash
+# Unit tests (watch mode)
+pnpm test
+
+# Unit tests (single run)
+pnpm test --run
+
+# Test UI
+pnpm test:ui
+
+# Coverage
+pnpm test:coverage
+
+# E2E tests (requires dev server)
+pnpm test:e2e
+
+# E2E UI
+pnpm test:e2e:ui
+
+# E2E debug
+pnpm test:e2e:debug
+```

package/template/docs/checkpoints/framework/phase-12-deployment.md

@@ -0,0 +1,294 @@
+# Phase 12: Deployment - Complete
+
+## Overview
+
+Implemented comprehensive deployment configuration for the Lego-One SaaS boilerplate, including Docker containerization, production build configuration, and deployment automation.
+
+## Build Statistics
+
+- **Host Build Size:** 786.5 kB (244.5 kB gzipped)
+- **Build Time:** 35.6s
+- **Status:** ✅ Successful
+
+## File Structure
+
+```
+lego-one/
+├── .env.example              # Environment variables template
+├── .dockerignore             # Docker ignore rules
+├── Dockerfile                # Multi-stage container build
+├── docker-compose.yml        # Local development stack
+├── docker-entrypoint.sh      # Container startup script
+├── nginx.conf                # Nginx configuration
+└── scripts/
+    └── deploy.sh             # Deployment automation script
+```
+
+## Docker Configuration
+
+### Multi-Stage Build
+
+**Stage 1: Host Builder**
+- Base: `node:20-alpine`
+- Installs dependencies with pnpm
+- Builds host application
+
+**Stage 2: Plugin Builder**
+- Builds dashboard plugin
+- Builds todo plugin
+
+**Stage 3: Production**
+- Base: `nginx:alpine`
+- Installs PocketBase v0.22.0
+- Serves static files with nginx
+- Runs PocketBase on port 8090
+
+### Exposed Ports
+- **80** - Nginx (application)
+- **8090** - PocketBase (API)
+
+### Volumes
+- `pb_data:/data/pb` - PocketBase SQLite data persistence
+
+## Nginx Configuration
+
+### Features
+- **Static file serving** with gzip compression
+- **SPA routing** via `try_files`
+- **API proxy** to PocketBase at `/api/`
+- **Cache headers** for static assets (1 year)
+- **Security headers** (X-Frame-Options, X-Content-Type-Options, X-XSS-Protection)
+
+### Compression
+- Text files (text/plain, text/css, text/xml, application/json)
+- JavaScript files
+- Gzip enabled
+
+### Caching
+- Static assets: 1 year, immutable
+- HTML pages: No cache
+
+## Environment Variables
+
+### Required
+```bash
+VITE_POCKETBASE_URL=http://127.0.0.1:8090
+VITE_APP_NAME=Lego-One
+VITE_APP_URL=http://localhost:8080
+VITE_PLUGINS_ENABLED=true
+```
+
+### Optional
+```bash
+VITE_ENABLE_DEVTOOLS=false
+VITE_ENABLE_ANALYTICS=false
+VITE_SENTRY_DSN=<sentry-dsn>
+VITE_GA_ID=<google-analytics-id>
+VITE_STRIPE_PUBLIC_KEY=<stripe-key>
+```
+
+## Deployment Scripts
+
+### deploy.sh
+```bash
+./scripts/deploy.sh [environment]
+```
+
+**Features:**
+- Environment-specific loading
+- Docker image building
+- Container orchestration
+- Health checks
+- Rolling updates
+
+**Usage:**
+```bash
+./scripts/deploy.sh production
+./scripts/deploy.sh staging
+./scripts/deploy.sh development
+```
+
+## Docker Compose
+
+### Services
+- **app** - Main application with embedded PocketBase
+
+### Optional Services (commented out)
+- **postgres** - PostgreSQL database for production
+- **redis** - Redis for caching/sessions
+
+### Health Check
+```yaml
+test: ["CMD", "wget", "-q", "--spider", "http://localhost/80"]
+interval: 30s
+timeout: 10s
+retries: 3
+start_period: 40s
+```
+
+## Container Entrypoint
+
+The `docker-entrypoint.sh` script:
+1. Starts PocketBase in background
+2. Waits for PocketBase to initialize (5s)
+3. Verifies PocketBase is running
+4. Starts nginx in foreground
+
+## TypeScript Configuration Updates
+
+### Excluded from Production Build
+```json
+{
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/__tests__",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "src/test"
+  ]
+}
+```
+
+## Docker Ignore Patterns
+
+Excluded from Docker build context:
+- Dependencies (node_modules)
+- Build outputs (dist, build, .next)
+- Environment files (.env, .env.local)
+- Test files and coverage
+- IDE files (.vscode, .idea)
+- Documentation
+- CI/CD configs
+
+## Deployment Commands
+
+### Local Development
+```bash
+# Start containers
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop containers
+docker-compose down
+
+# Rebuild containers
+docker-compose up -d --build
+```
+
+### Production Deployment
+```bash
+# Build and deploy
+./scripts/deploy.sh production
+
+# Manual Docker build
+docker build -t lego-one:latest .
+docker run -p 80:80 -p 8090:8090 -v pb_data:/data/pb lego-one:latest
+```
+
+### Container Management
+```bash
+# View running containers
+docker ps
+
+# View container logs
+docker logs <container-id>
+
+# Execute command in container
+docker exec -it <container-id> sh
+
+# Stop container
+docker stop <container-id>
+
+# Remove container
+docker rm <container-id>
+```
+
+## PocketBase Data Persistence
+
+### SQLite Location
+- Container: `/data/pb/pb_data.db`
+- Host volume: `pb_data` named volume
+
+### Backup Commands
+```bash
+# Backup data
+docker cp <container-id>:/data/pb ./backup/
+
+# Restore data
+docker cp ./backup/ <container-id>:/data/pb/
+```
+
+## Production Considerations
+
+### Security
+1. **Environment Variables** - Never commit .env files
+2. **Database** - Use PostgreSQL in production (not SQLite)
+3. **HTTPS** - Use reverse proxy (nginx, Traefik) with SSL
+4. **Firewall** - Only expose necessary ports
+5. **Secrets** - Use secret management (Docker secrets, AWS Secrets Manager)
+
+### Scaling
+1. **Horizontal Scaling** - Deploy multiple app instances behind load balancer
+2. **Database** - External PostgreSQL instance
+3. **Session Storage** - External Redis for sessions
+4. **File Storage** - S3 or compatible for user uploads
+5. **CDN** - CloudFront/Cloudflare for static assets
+
+### Monitoring
+1. **Logging** - Centralized logging (ELK, Loki)
+2. **Metrics** - Prometheus + Grafana
+3. **APM** - Sentry, DataDog, or New Relic
+4. **Health Checks** - `/health` endpoint
+5. **Uptime** - UptimeRobot, Pingdom
+
+## Deployment Platforms
+
+### Supported
+- **Docker** - Self-hosted Docker/Docker Compose
+- **Kubernetes** - Helm charts (to be created)
+- **Cloud Providers** - AWS, GCP, Azure (via container registries)
+
+### Recommended
+- **Vercel** - For frontend (host + plugins)
+- **Railway** - For PocketBase + PostgreSQL
+- **Render** - Full-stack deployment
+- **DigitalOcean App Platform** - Simple PaaS
+
+## Build Optimization
+
+### Current Size Breakdown
+- `lib-polyfill`: 246.2 kB (83.8 kB gzipped)
+- `lib-react`: 140.0 kB (45.2 kB gzipped)
+- Chunk `381`: 314.4 kB (93.8 kB gzipped)
+- `main.js`: 30.2 kB (9.7 kB gzipped)
+- `main.css`: 44.4 kB (7.2 kB gzipped)
+
+### Future Optimizations
+1. Code splitting by route
+2. Dynamic imports for plugins
+3. Tree shaking for unused dependencies
+4. Bundle analysis (webpack-bundle-analyzer)
+5. CSS purging (unused Tailwind classes)
+
+## Next Steps
+
+1. **CI/CD Pipeline** - GitHub Actions workflow
+2. **Kubernetes** - Helm charts for K8s deployment
+3. **Monitoring** - Prometheus + Grafana setup
+4. **Backup Scripts** - Automated PocketBase backups
+5. **SSL/TLS** - Let's Encrypt integration
+6. **CDN** - CloudFront setup for static assets
+
+## Notes
+
+- Multi-stage Docker build reduces final image size
+- Nginx serves static files efficiently
+- PocketBase embedded in same container (simplifies deployment)
+- For production, consider separate containers for app and database
+- Docker volumes ensure data persistence across container restarts
+- Health checks ensure container is running properly