create-lego-one 2.0.12 → 2.0.13

package/template/docs/checkpoints/framework/02-pocketbase-setup.md

@@ -0,0 +1,155 @@
+# Checkpoint: Phase 2 - PocketBase Setup
+
+**Date:** 2026-01-23
+**Plan:** `docs/framework/plans/02-pocketbase-setup.md`
+**Status:** ✅ COMPLETED
+
+---
+
+## Files Created
+
+### PocketBase Binary and Setup
+- `pocketbase/pocketbase.exe` - PocketBase v0.22.0 binary for Windows
+- `pocketbase/.gitignore` - Git ignore patterns for pb_data/ and pb_public/
+- `pocketbase/pb_migrations/` - Migrations directory
+
+### PocketBase Library (`host/src/lib/pocketbase/`)
+- `types.ts` - PocketBase field types and collection interfaces
+- `migrations.ts` - Migration runner utilities
+- `client.ts` - PocketBase client singleton
+- `index.ts` - Barrel export for all pocketbase utilities
+
+### Collections (`host/src/lib/pocketbase/collections/`)
+- `users.ts` - Users auth collection with multi-tenancy rules
+- `organizations.ts` - Organizations collection for multi-tenancy
+- `roles.ts` - Roles collection for RBAC
+- `permissions.ts` - Permissions collection for granular access control
+- `user_roles.ts` - Junction table for user-role assignments
+- `audit_logs.ts` - Audit log collection
+- `todos.ts` - Todos collection (example plugin data)
+- `index.ts` - Collections registry
+
+### Seed Data (`host/src/lib/pocketbase/seed/`)
+- `roles.ts` - System roles (Owner, Admin, Member, Guest)
+- `permissions.ts` - System permissions for all resources
+
+### Seed and Migration Logic
+- `host/src/lib/pocketbase/seed.ts` - Database seeding function
+
+### Kernel (`host/src/kernel/`)
+- `use-migrations.ts` - React hook for running migrations on startup
+
+### Providers (`host/src/providers/`)
+- `PocketBaseProvider.tsx` - React context provider for PocketBase client
+
+### Configuration
+- `saas.config.ts` - Initial SaaS plugin configuration
+
+---
+
+## Active State
+
+### Collections Created (7 total)
+1. **users** (auth) - User accounts with organization membership
+2. **organizations** - Multi-tenant organizations
+3. **roles** - RBAC roles
+4. **permissions** - RBAC permissions
+5. **user_roles** - User-role junction table
+6. **audit_logs** - Audit trail for all actions
+7. **todos** - Sample plugin data (Todo plugin)
+
+### Multi-Tenancy Rules
+All collections implement organization-based data isolation using API rules:
+- `listRule` - Users can only see records in their organization
+- `viewRule` - Users can only view records in their organization
+- `createRule` - Varies by resource and user role
+- `updateRule` - Users can update their own records (varies by resource)
+- `deleteRule` - Varies by resource and user role
+
+### RBAC System
+- 4 system roles: Owner, Admin, Member, Guest
+- 19 system permissions covering:
+  - User management (view, create, update, delete)
+  - Role management (view, create, update, delete)
+  - Permission management (view, create, delete)
+  - Organization settings (update)
+  - Audit logs (view)
+  - Todo management (view, manage)
+  - Plugin management (view, manage)
+
+### Seed Data
+On first run (development):
+- Creates admin user with credentials from .env
+- Creates demo organization
+- Creates all system roles and permissions
+- Assigns Owner role to admin
+- Creates 3 sample todos
+
+---
+
+## Pending Tasks
+
+### Next Phase: Host Kernel
+- **Plan File:** `docs/framework/plans/03-host-kernel.md`
+- **Prerequisites:** Phase 2 completed
+- **Overview:**
+  - Initialize Modern.js host app
+  - Create shared state management (Zustand)
+  - Create layout components
+  - Set up routing
+  - Configure Garfish for micro-frontends
+
+---
+
+## Verification Results
+
+### PocketBase Binary
+✅ `pocketbase/pocketbase.exe` - Downloaded and verified version 0.22.0
+✅ `pocketbase/.gitignore` - Created
+✅ `pocketbase/pb_migrations/` - Directory created
+
+### Collections
+✅ `users.ts` - Auth collection with organization relation
+✅ `organizations.ts` - Base collection with owner relation
+✅ `roles.ts` - Base collection with isSystem flag
+✅ `permissions.ts` - Base collection with resource/action fields
+✅ `user_roles.ts` - Junction table with userId, roleId, organizationId
+✅ `audit_logs.ts` - Base collection with action, entityType, entityId
+✅ `todos.ts` - Base collection with priority, dueDate, completed
+
+### Migrations
+✅ `types.ts` - All field types defined (bool, number, text, email, url, date, autodate, select, json, relation)
+✅ `migrations.ts` - Migration runner with collection creation logic
+✅ `collections/index.ts` - Collections registry
+
+### Seed Data
+✅ `seed/roles.ts` - 4 system roles defined
+✅ `seed/permissions.ts` - 19 system permissions defined
+✅ `seed.ts` - Seed function with admin, org, roles, permissions, todos
+
+### Client Initialization
+✅ `client.ts` - Singleton pattern with getPocketBase() and getPocketBaseAdmin()
+✅ `PocketBaseProvider.tsx` - React context provider with usePocketBase() hook
+
+### Kernel Integration
+✅ `kernel/use-migrations.ts` - React hook for running migrations on startup
+
+---
+
+## Gap Analysis
+
+Against Research Documents:
+- `docs/framework/research/02-data-migration-protocol.md` - Follows migration pattern with startup hook
+- `docs/framework/research/01-system-blueprint.md` - Multi-tenancy API rules implemented as specified
+
+All planned items for Phase 2 have been implemented and verified.
+
+---
+
+## Notes
+
+- PocketBase binary downloaded for Windows (pocketbase.exe)
+- SaaS config uses TypeScript types instead of `@lego/kernel/config` since that doesn't exist yet
+- Migration hook will be integrated into host app in Phase 3
+- All collections use organization-based multi-tenancy with proper API rules
+- RBAC system fully implemented with roles and permissions

package/template/docs/checkpoints/framework/03-host-kernel.md

@@ -0,0 +1,170 @@
+# Checkpoint: Phase 3 - Host Kernel
+
+**Date:** 2026-01-23
+**Plan:** `docs/framework/plans/03-host-kernel.md`
+**Status:** ✅ COMPLETED
+
+---
+
+## Files Created
+
+### Host Application Configuration
+- `host/package.json` - Host package with Modern.js dependencies
+- `host/tsconfig.json` - TypeScript configuration with path aliases
+- `host/modern.config.ts` - Modern.js configuration with Garfish plugin
+- `host/.gitignore` - Host-specific gitignore
+
+### Tailwind CSS Configuration
+- `host/tailwind.config.ts` - Tailwind config with Shadcn-compatible theme
+- `host/postcss.config.js` - PostCSS configuration
+- `host/src/global.css` - Global CSS with CSS variables for theming
+
+### Source Files (`host/src/`)
+- `App.tsx` - Root App component with Outlet
+- `index.ts` - Entry point importing Garfish and bootstrap
+- `bootstrap.tsx` - Bootstrap file with provider setup
+- `modern.runtime.ts` - Modern.js runtime config for Garfish apps
+
+### Kernel (`host/src/kernel/`)
+- `index.ts` - Kernel barrel export
+- `shared-state/types.ts` - Global state type definitions
+- `shared-state/store.ts` - Zustand store with devtools and persist
+- `shared-state/bridge.ts` - Window bridge for plugin access
+- `shared-state/index.ts` - Shared state barrel export
+- `providers/PocketBaseProvider.tsx` - PocketBase context provider
+- `providers/QueryProvider.tsx` - TanStack Query provider
+- `providers/ThemeProvider.tsx` - Theme provider for dark mode
+- `providers/index.ts` - Providers barrel export
+- `lib/utils.ts` - Utility functions (cn, getInitials, formatDate)
+- `lib/cn.ts` - cn function export
+- `components/ui/skeleton.tsx` - Skeleton loading component
+
+### Layout (`host/src/layout/`)
+- `Shell.tsx` - Main layout wrapper component
+- `Sidebar.tsx` - Collapsible sidebar with navigation
+- `Topbar.tsx` - Top bar with mobile menu toggle and user avatar
+- `MobileMenu.tsx` - Mobile menu overlay
+- `index.ts` - Layout barrel export
+
+### Routes (`host/src/routes/`)
+- `_.tsx` - Plugin wrapper route with Shell layout
+- `index.tsx` - Home page with feature cards
+- `dashboard._.tsx` - Dashboard plugin route wrapper
+
+---
+
+## Active State
+
+### Dependencies Installed
+Key dependencies:
+- `@modern-js/runtime` ^2.60.0 - Modern.js runtime
+- `@modern-js/app-tools` ^2.60.0 - Modern.js build tools
+- `@modern-js/plugin-garfish` ^2.60.0 - Garfish micro-frontend plugin
+- `garfish` ^1.19.0 - Micro-frontend framework
+- `@garfish/hooks` ^1.19.0 - Garfish React hooks
+- `zustand` ^5.0.1 - State management
+- `@tanstack/react-query` ^5.59.0 - Server state management
+- `pocketbase` ^0.21.5 - Backend SDK
+- `lucide-react` ^0.454.0 - Icon library
+- `tailwindcss` ^3.4.15 - CSS framework
+- `tailwindcss-animate` ^1.0.7 - Tailwind animations
+
+### Global State (Zustand)
+- Auth state: user, token, isAuthenticated, organization
+- UI state: theme, sidebarOpen, mobileMenuOpen
+- Toast notifications system
+- Loading state
+- Persisted to localStorage (theme, sidebarOpen, token)
+
+### Theme System
+- Light/dark mode support via CSS variables
+- System theme detection
+- Shadcn UI compatible color scheme
+- CSS custom properties for consistent theming
+
+### Routing
+- File-based routing via Modern.js
+- Plugin route wrappers (/dashboard, /todos)
+- Home page with feature highlights
+- Shell layout applied to all routes
+
+### Garfish Configuration
+- Development: Plugins run on separate servers (localhost:3001, :3002)
+- Production: Plugins bundled via dynamic import
+- Plugin apps configured for @lego/plugin-dashboard and @lego/plugin-todo
+
+### Layout Structure
+- Collapsible sidebar (desktop: 64px/16px, mobile: 256px slide-in)
+- Top bar with mobile menu toggle
+- Mobile menu overlay
+- User avatar display
+- Navigation items: Home, Dashboard, Todos, Settings
+
+---
+
+## Pending Tasks
+
+### Next Phase: Auth System
+- **Plan File:** `docs/framework/plans/04-auth-system.md`
+- **Prerequisites:** Phase 3 completed
+- **Overview:**
+  - Create login/register pages
+  - Implement authentication hooks
+  - Session management
+  - Protected route wrapper
+
+---
+
+## Verification Results
+
+### Host Application
+✅ `package.json` - Created with all dependencies
+✅ `tsconfig.json` - Created with path aliases
+✅ `modern.config.ts` - Created with Garfish plugin
+✅ Dependencies installed (932 packages)
+
+### Tailwind CSS
+✅ `tailwind.config.ts` - Created with Shadcn theme
+✅ `postcss.config.js` - Created
+✅ `global.css` - Created with CSS variables
+
+### Kernel System
+✅ `shared-state/` - Types, store, bridge created
+✅ `providers/` - PocketBase, Query, Theme providers created
+✅ `lib/utils.ts` - Utility functions created
+✅ `components/ui/skeleton.tsx` - Skeleton component created
+
+### Layout Components
+✅ `Shell.tsx` - Main layout wrapper
+✅ `Sidebar.tsx` - Navigation sidebar with collapse
+✅ `Topbar.tsx` - Top bar with user actions
+✅ `MobileMenu.tsx` - Mobile menu overlay
+
+### Routes
+✅ `_.tsx` - Plugin wrapper route
+✅ `index.tsx` - Home page
+✅ `dashboard._.tsx` - Dashboard plugin route
+
+### Bootstrap
+✅ `bootstrap.tsx` - Provider setup with StrictMode
+✅ `index.ts` - Entry point with Garfish import
+
+---
+
+## Gap Analysis
+
+Against Research Documents:
+- `docs/framework/research/03-host-setup.md` - Following host kernel setup pattern
+- `docs/framework/research/05-slot-injection-pattern.md` - Will be implemented in plugin system phase
+
+All planned items for Phase 3 have been implemented and verified.
+
+---
+
+## Notes
+
+- Garfish version adjusted to 1.19.0 (latest available)
+- `@modern-js/runtime/garfish` dependency removed - garfish export is from @modern-js/runtime
+- React peer dependency warnings from react-server-dom-webpack (not critical)
+- All files use correct path aliases (@/*, @lego/kernel/*)
+- Shared state bridge registered to window for plugin access

package/template/docs/checkpoints/framework/04-auth-system.md

@@ -0,0 +1,163 @@
+# Checkpoint: Phase 4 - Auth System
+
+**Date:** 2026-01-23
+**Plan:** `docs/framework/plans/04-auth-system.md`
+**Status:** ✅ COMPLETED
+
+---
+
+## Files Created
+
+### Auth System (`host/src/kernel/auth/`)
+- `types.ts` - Auth interfaces (LoginCredentials, RegisterData, User, AuthResponse, AuthError, SessionData)
+- `schemas.ts` - Zod validation schemas (loginSchema, registerSchema)
+- `service.ts` - AuthService class with login, register, logout, profile management
+- `hooks.ts` - React hooks (useAuth, useCurrentUser, useRequireAuth)
+- `ProtectedRoute.tsx` - Protected route wrapper component
+- `index.ts` - Auth module barrel export
+
+### Auth Components (`host/src/kernel/auth/components/`)
+- `LoginForm.tsx` - Login form with validation and error handling
+- `LogoutButton.tsx` - Logout button with dropdown menu
+
+### UI Components (`host/src/kernel/components/ui/`)
+- `button.tsx` - Button component with variants (default, destructive, outline, secondary, ghost, link)
+- `input.tsx` - Input component with consistent styling
+- `label.tsx` - Label component for form fields
+- `card.tsx` - Card components (Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter)
+- `alert.tsx` - Alert components (Alert, AlertTitle, AlertDescription)
+- `dropdown-menu.tsx` - Dropdown menu components (Radix UI based)
+- `skeleton.tsx` - Skeleton loading component (created in Phase 3)
+
+### Routes (`host/src/routes/`)
+- `login.tsx` - Login page route
+
+### Modified Files
+- `host/package.json` - Added @hookform/resolvers, react-hook-form, zod
+- `host/src/layout/Topbar.tsx` - Updated to use LogoutButton
+
+---
+
+## Active State
+
+### Dependencies Added
+- `@hookform/resolvers` ^3.9.0 - Zod resolver for react-hook-form
+- `react-hook-form` ^7.53.0 - Form validation
+- `zod` ^3.22.0 - Schema validation
+
+### Auth Service Features
+- `login(credentials)` - Authenticate with email/password
+- `register(data, organizationId)` - Register new user (admin only)
+- `logout()` - Clear auth session
+- `getCurrentUser()` - Get authenticated user
+- `getToken()` - Get auth token
+- `refreshToken()` - Refresh auth token (no-op for PocketBase)
+- `updateProfile(userId, data)` - Update user profile
+- `changePassword(oldPassword, newPassword)` - Change user password
+- `requestPasswordReset(email)` - Request password reset
+- `confirmPasswordReset(token, password)` - Confirm password reset
+- `isAuthenticated()` - Check auth status
+- `onAuthChange(callback)` - Listen to auth state changes
+
+### Auth Hooks
+- `useAuth()` - Main auth hook with state and actions
+  - Returns: user, isAuthenticated, isLoading, login, register, logout, error
+- `useCurrentUser()` - Get current user data
+  - Returns: user, isLoading, isAuthenticated
+- `useRequireAuth()` - Require auth or redirect
+  - Returns: user, isAuthenticated, isLoading, shouldRedirect
+
+### Form Validation
+- Login: email (email validation), password (min 8 chars)
+- Register: email, password (min 8, uppercase, lowercase, number), passwordConfirm (match), name (min 2)
+
+### UI Components Created
+- Button with 6 variants and 4 sizes
+- Input with consistent styling
+- Label for form fields
+- Card components for layout
+- Alert for error/success messages
+- DropdownMenu for user menu
+- Skeleton for loading states
+
+### Login Flow
+1. User navigates to `/login`
+2. Enters email and password
+3. Form validates with Zod
+4. On submit, calls `login()` via AuthService
+5. On success, redirects to `/dashboard`
+6. On failure, shows error alert
+
+### Logout Flow
+1. Click user avatar in topbar
+2. Dropdown menu appears with user info
+3. Click "Log out"
+4. `logout()` clears PocketBase auth store
+5. Redirects to `/login`
+
+---
+
+## Pending Tasks
+
+### Next Phase: Multitenancy & RBAC
+- **Plan File:** `docs/framework/plans/05-multitenancy-rbac.md`
+- **Prerequisites:** Phase 4 completed
+- **Overview:**
+  - Organizations management
+  - Users management
+  - Roles management
+  - Permissions management
+  - Audit logging
+
+---
+
+## Verification Results
+
+### Auth System
+✅ `types.ts` - Auth interfaces defined
+✅ `schemas.ts` - Zod validation schemas
+✅ `service.ts` - AuthService class with all methods
+✅ `hooks.ts` - React hooks (useAuth, useCurrentUser, useRequireAuth)
+✅ `ProtectedRoute.tsx` - Protected route wrapper
+✅ `index.ts` - Barrel export
+
+### Components
+✅ `LoginForm.tsx` - Login form with react-hook-form + Zod
+✅ `LogoutButton.tsx` - Logout with dropdown menu
+
+### UI Components
+✅ `button.tsx` - 6 variants, 4 sizes
+✅ `input.tsx` - Consistent styling
+✅ `label.tsx` - Form field labels
+✅ `card.tsx` - 5 card components
+✅ `alert.tsx` - Alert with variants
+✅ `dropdown-menu.tsx` - Full Radix UI implementation
+
+### Routes
+✅ `login.tsx` - Login page with redirect logic
+
+### Dependencies
+✅ `@hookform/resolvers` ^3.9.0 installed
+✅ `react-hook-form` ^7.53.0 installed
+✅ `zod` ^3.22.0 installed
+
+---
+
+## Gap Analysis
+
+Against Research Documents:
+- `docs/framework/research/01-system-blueprint.md` - Following admin-seeded auth pattern
+- `docs/framework/research/02-data-migration-protocol.md` - Users collection ready for auth
+
+All planned items for Phase 4 have been implemented and verified.
+
+---
+
+## Notes
+
+- Admin-only registration (no public signup)
+- Session persistence via PocketBase auth store + localStorage
+- Form validation uses react-hook-form + Zod + @hookform/resolvers
+- All Shadcn UI components use Radix UI primitives where applicable
+- ProtectedRoute component redirects to `/login` by default
+- Login page shows default credentials hint for development