create-lego-one 2.0.12 → 2.0.13

package/template/docs/framework/setup/03-environment-setup.md

@@ -0,0 +1,215 @@
+# Environment Setup
+
+**Prerequisites and Configuration**
+
+---
+
+## Prerequisites
+
+### Required Software
+
+| Software | Version | Purpose |
+|----------|---------|---------|
+| **Node.js** | 20+ | Runtime environment |
+| **pnpm** | 9+ | Package manager |
+| **Git** | Latest | Version control |
+| **PocketBase** | 0.22+ | Backend database |
+
+### Optional Software
+
+| Software | Purpose |
+|----------|---------|
+| **Docker** | Containerized deployment |
+| **Docker Compose** | Multi-container orchestration |
+
+---
+
+## Installation
+
+### Installing Node.js
+
+**Download:** https://nodejs.org/
+
+**Verify installation:**
+```bash
+node --version  # Should be v20+
+```
+
+### Installing pnpm
+
+```bash
+npm install -g pnpm
+```
+
+**Verify installation:**
+```bash
+pnpm --version  # Should be 9+
+```
+
+### Installing PocketBase
+
+1. **Download:** https://pocketbase.io/docs/
+2. **Extract** to `pocketbase/` directory
+3. **Verify:**
+```bash
+cd pocketbase
+./pocketbase --version
+```
+
+---
+
+## Project Setup
+
+### Clone Repository
+
+```bash
+git clone https://github.com/your-org/lego-one.git
+cd lego-one
+```
+
+### Install Dependencies
+
+```bash
+pnpm install
+```
+
+This installs dependencies for the host and all plugins.
+
+---
+
+## Environment Variables
+
+### Development (.env.development)
+
+Create `.env.development`:
+
+```bash
+# PocketBase (local)
+VITE_POCKETBASE_URL=http://127.0.0.1:8090
+
+# Application
+VITE_APP_URL=http://localhost:8080
+VITE_APP_NAME=Lego-One
+
+# Features
+VITE_ENABLE_DEV_TOOLS=true
+
+# External Services (Optional)
+# VITE_SENTRY_DSN=https://your-sentry-dsn
+# VITE_GA_ID=G-XXXXXXXXXX
+```
+
+### Production (.env.production)
+
+Create `.env.production`:
+
+```bash
+# PocketBase (production)
+VITE_POCKETBASE_URL=https://pb.yourdomain.com
+
+# Application
+VITE_APP_URL=https://yourdomain.com
+VITE_APP_NAME=Your App Name
+
+# Features
+VITE_ENABLE_DEV_TOOLS=false
+
+# External Services (Optional)
+VITE_SENTRY_DSN=https://your-sentry-dsn
+VITE_GA_ID=G-XXXXXXXXXX
+```
+
+---
+
+## Starting Development
+
+### Start PocketBase
+
+In a separate terminal:
+
+```bash
+cd pocketbase
+./pocketbase serve
+```
+
+**PocketBase will:**
+- Start on http://127.0.0.1:8090
+- Run migrations automatically
+- Create seed data
+
+### Start Application
+
+```bash
+# Start all services
+pnpm run dev:all
+
+# Or start host only
+pnpm run dev:host
+```
+
+**Application URLs:**
+- Host: http://localhost:8080
+- Dashboard: http://localhost:3001
+- Todo: http://localhost:3002
+- PocketBase Admin: http://localhost:8090/_/
+
+**Default Credentials:**
+- Email: `admin@example.com`
+- Password: `admin123`
+
+⚠️ **Change default credentials in production!**
+
+---
+
+## IDE Setup
+
+### VS Code
+
+**Recommended Extensions:**
+- ESLint
+- Prettier
+- Tailwind CSS IntelliSense
+- TypeScript Vue Plugin (Volar)
+
+**Settings (.vscode/settings.json):**
+```json
+{
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "tailwindCSS.experimental.classRegex": [
+    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
+  ]
+}
+```
+
+---
+
+## Troubleshooting
+
+### Port Already in Use
+
+```bash
+# Find process on port 8080
+lsof -ti:8080 | xargs kill -9  # macOS/Linux
+netstat -ano | findstr :8080    # Windows
+```
+
+### Dependencies Not Installing
+
+```bash
+# Clear cache and reinstall
+rm -rf node_modules
+rm -rf .cache
+pnpm install
+```
+
+### PocketBase Not Starting
+
+**Solutions:**
+1. Check port 8090 is available
+2. Verify PocketBase binary is executable
+3. Check pocketbase/pb_data/ directory exists
+
+---
+
+**Next:** Read [`04-kernel-architecture.md`](./04-kernel-architecture.md) to understand the kernel system.

package/template/docs/framework/setup/04-kernel-architecture.md

@@ -0,0 +1,499 @@
+# Kernel Architecture
+
+**Host/Kernel System Overview**
+
+---
+
+## Overview
+
+The Lego-One Host (Kernel) is the core application that provides all shared services, infrastructure, and layout. Plugins load into the host and use its services via the window bridge pattern.
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                          HOST APPLICATION                          │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                        LAYER 1: Bootstrap                      │ │
+│  │  • Garfish initialization                                     │ │
+│  │  • Provider registration (PocketBase, Query, Theme)            │ │
+│  │  • Channel bus initialization                                 │ │
+│  │  • Plugin loader initialization                               │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                                │                                    │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                    LAYER 2: Providers                          │ │
+│  │  • PocketBaseProvider - Backend client                        │ │
+│  │  • QueryProvider - TanStack Query (server state)              │ │
+│  │  • ThemeProvider - Dark mode, CSS variables                  │ │
+│  │  • SlotProvider - Plugin slot injection system                │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                                │                                    │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                    LAYER 3: Kernel Services                   │ │
+│  │  ┌─────────────┬─────────────┬─────────────┬──────────────┐   │ │
+│  │  │   Auth      │    RBAC     │  Channels   │   Plugins    │   │ │
+│  │  │  System     │   System    │    System   │   System     │   │ │
+│  │  ├─────────────┼─────────────┼─────────────┼──────────────┤   │ │
+│  │  │ Login       │ Orgs        │ ChannelBus  │ PluginStore  │   │ │
+│  │  │ Register    │ Roles       │ Hooks       │ PluginLoader │   │ │
+│  │  │ Protected   │ Permissions │ Events      │ Slots        │   │ │
+│  │  │ Routes      │ Users       │ Integrations│ Registry     │   │ │
+│  │  └─────────────┴─────────────┴─────────────┴──────────────┘   │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                                │                                    │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                   LAYER 4: Shared State                         │ │
+│  │  • Zustand store (user, organization, auth state)             │ │
+│  │  • Window bridge (for plugin access)                          │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                                │                                    │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                   LAYER 5: Layout Components                   │ │
+│  │  • Shell (main container)                                      │ │
+│  │  • Sidebar (navigation)                                        │ │
+│  │  • Topbar (header actions)                                     │ │
+│  │  • Slot components (plugin injection points)                   │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                                │                                    │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                   LAYER 6: UI Component Library                │ │
+│  │  • Radix UI primitives (Button, Dialog, Dropdown, etc.)        │ │
+│  │  • Tailwind CSS styling                                        │ │
+│  │  • Custom components (Toast, Alert, Badge, etc.)               │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                                │                                    │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │                   LAYER 7: Routes (Pages)                      │ │
+│  │  • Sign in / Sign up                                           │ │
+│  │  • Dashboard                                                   │ │
+│  │  • Settings                                                    │ │
+│  │  • Plugin routes (injected by plugins)                         │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────┘
+                                │
+                    ═══════════════════════════════
+                    GARFISH PLUGIN BOUNDARY
+                    ═══════════════════════════════
+                                │
+┌─────────────────────────────────────────────────────────────────────┐
+│                         PLUGINS (Applications)                       │
+│  ┌──────────────┬──────────────┬──────────────┬──────────────┐    │
+│  │  Dashboard   │     Todo     │   Plugin C   │   Plugin D   │    │
+│  │   Plugin     │   Plugin     │              │              │    │
+│  ├──────────────┼──────────────┼──────────────┼──────────────┤    │
+│  │ Statistics   │  CRUD UI     │   Custom     │   Custom     │    │
+│  │ Activity     │  Forms       │   Feature    │   Feature    │    │
+│  │ Quick Actions│  Filtering   │              │              │    │
+│  └──────────────┴──────────────┴──────────────┴──────────────┘    │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Directory Structure
+
+```
+host/src/
+├── bootstrap.tsx              # App initialization, provider setup
+├── App.tsx                    # Root component with routing
+├── modern.config.ts           # Modern.js configuration
+├── modern.runtime.ts          # Garfish plugin registration
+├── saas.config.ts             # Plugin enable/disable config
+│
+├── kernel/                    # CORE KERNEL SYSTEMS
+│   ├── index.ts              # Kernel exports
+│   │
+│   ├── shared-state/         # Global state management
+│   │   ├── store.ts         # Zustand global store
+│   │   └── bridge.ts        # Window bridge registration
+│   │
+│   ├── providers/            # React Context providers
+│   │   ├── PocketBaseProvider.tsx
+│   │   ├── QueryProvider.tsx
+│   │   └── ThemeProvider.tsx
+│   │
+│   ├── auth/                 # Authentication system
+│   │   ├── types.ts
+│   │   ├── hooks.ts
+│   │   ├── components/
+│   │   └── index.ts
+│   │
+│   ├── rbac/                 # Multi-tenancy & RBAC
+│   │   ├── types.ts
+│   │   ├── service.ts
+│   │   ├── hooks.ts
+│   │   ├── components/
+│   │   └── index.ts
+│   │
+│   ├── channels/             # Inter-plugin communication
+│   │   ├── types.ts
+│   │   ├── events.ts
+│   │   ├── ChannelBus.ts
+│   │   ├── hooks.ts
+│   │   ├── ChannelProvider.tsx
+│   │   └── index.ts
+│   │
+│   ├── plugins/              # Plugin system
+│   │   ├── types.ts
+│   │   ├── schemas.ts
+│   │   ├── store.ts
+│   │   ├── loader.ts
+│   │   ├── Slot.tsx
+│   │   ├── SlotProvider.tsx
+│   │   └── index.ts
+│   │
+│   ├── components/           # Shared UI components
+│   │   ├── ui/              # Radix UI primitives
+│   │   └── index.ts
+│   │
+│   └── lib/                  # Utilities
+│       ├── utils.ts         # Helper functions
+│       └── cn.ts            # Class name merger
+│
+├── layout/                   # Layout components
+│   ├── Shell.tsx            # Main app shell
+│   ├── Sidebar.tsx          # Left navigation
+│   └── Topbar.tsx           # Header
+│
+├── routes/                   # Page components
+│   ├── SignIn.tsx
+│   ├── SignUp.tsx
+│   ├── Dashboard.tsx
+│   └── Settings/
+│
+└── test/                     # Test setup
+    ├── setup.ts
+    └── utils.tsx
+```
+
+---
+
+## Core Systems
+
+### 1. Shared State (Zustand)
+
+**Location:** `host/src/kernel/shared-state/`
+
+**Purpose:** Global state accessible by host and plugins via window bridge
+
+**State includes:**
+- `user` - Current authenticated user
+- `organization` - Current selected organization
+- `token` - Authentication token
+- `isAuthenticated` - Auth status flag
+- `sidebarOpen` - Sidebar toggle state
+- `mobileMenuOpen` - Mobile menu state
+
+**Window Bridge:**
+```typescript
+// Plugins can access kernel state:
+window.__LEGO_KERNEL_STATE__?.useGlobalKernelState?.getState()
+
+// Returns: { user, organization, token, isAuthenticated, ... }
+```
+
+---
+
+### 2. Authentication System
+
+**Location:** `host/src/kernel/auth/`
+
+**Features:**
+- Email/password authentication via PocketBase
+- Protected routes (redirects if not authenticated)
+- Token persistence (localStorage)
+- Auto-logout on token expiration
+
+**Key Hooks:**
+```typescript
+const { user, isAuthenticated, login, logout } = useAuth();
+
+// Protected route hook
+useRequireAuth(); // Redirects to /sign-in if not authenticated
+```
+
+**PocketBase Integration:**
+- Uses PocketBase auth store
+- Collection: `users`
+- Token stored in: `localStorage` key `pocketbase_auth`
+
+---
+
+### 3. RBAC System (Multi-Tenancy)
+
+**Location:** `host/src/kernel/rbac/`
+
+**PocketBase Collections:**
+- `organizations` - Tenant data isolation
+- `roles` - System and custom roles
+- `permissions` - Granular permissions
+- `user_roles` - User-role assignments for orgs
+
+**System Roles:**
+| Role | Permissions |
+|------|-------------|
+| `Owner` | Full access (all:all) |
+| `Admin` | Users, roles, todos, settings |
+| `Member` | Todos, read-only access |
+| `Guest` | Read-only todos |
+
+**Key Hooks:**
+```typescript
+// Organization management
+const { organization, setCurrentOrganization } = useCurrentOrganization();
+const { data: organizations } = useOrganizations();
+
+// Permission checking
+const checkPermission = useHasPermission();
+const allowed = await checkPermission('todos', 'write');
+
+// Get user's permissions
+const { data: permissions } = useUserPermissions();
+```
+
+**Data Isolation:**
+```typescript
+// All data queries MUST filter by organization
+pb.collection('todos').getList(1, 50, {
+  filter: `organizationId = "${orgId}"`,
+});
+```
+
+---
+
+### 4. Channel System (Communication)
+
+**Location:** `host/src/kernel/channels/`
+
+**Purpose:** Pub/sub messaging between plugins and host
+
+**Channels:**
+```typescript
+enum ChannelName {
+  TOAST = 'lego:toast',              // Show notifications
+  NAVIGATION = 'lego:navigation',    // Navigate routes
+  STATE_UPDATE = 'lego:state:update',
+  PLUGIN_READY = 'lego:plugin:ready',
+  PLUGIN_ERROR = 'lego:plugin:error',
+  AUTH_CHANGE = 'lego:auth:change',
+  ORGANIZATION_CHANGE = 'lego:organization:change',
+}
+```
+
+**Usage in Plugins:**
+```typescript
+// Publish toast notification
+window.__LEGO_CHANNEL_BUS__?.publish('lego:toast', {
+  type: 'success',
+  title: 'Saved!',
+  description: 'Your changes were saved',
+});
+
+// Subscribe to auth changes
+const unsubscribe = window.__LEGO_CHANNEL_BUS__?.subscribe(
+  'lego:auth:change',
+  (data) => console.log('Auth changed:', data)
+);
+```
+
+**Hooks (for host components):**
+```typescript
+const publishToast = useToastChannel();
+publishToast({ type: 'success', title: 'Done!' });
+
+const publish = usePublish();
+publish({ channel: ChannelName.TOAST, data: {...} });
+```
+
+---
+
+### 5. Plugin System
+
+**Location:** `host/src/kernel/plugins/`
+
+**Features:**
+- Dynamic plugin loading via Garfish
+- Slot injection system (inject UI into sidebar, topbar, etc.)
+- Plugin enable/disable via config
+- Plugin state management (Zustand store)
+
+**Plugin Config:**
+```typescript
+// In: host/src/saas.config.ts
+export const saasConfig = {
+  plugins: [
+    { name: '@lego/plugin-dashboard', enabled: true },
+    { name: '@lego/plugin-todo', enabled: true },
+  ],
+};
+```
+
+**Available Slots:**
+| Slot | Location | Purpose |
+|------|----------|---------|
+| `sidebar:top` | Top of sidebar | Logo, user menu |
+| `sidebar:nav` | Main navigation | Plugin navigation links |
+| `sidebar:bottom` | Bottom of sidebar | Logout, settings |
+| `topbar:left` | Left side | Breadcrumbs |
+| `topbar:center` | Center | Page title |
+| `topbar:right` | Right side | Notifications |
+| `dashboard:widgets` | Dashboard | Statistics cards |
+
+**Slot Usage in Plugin:**
+```typescript
+// In plugin.config.ts
+export const pluginConfig = {
+  slots: [
+    {
+      slot: 'sidebar:nav',
+      component: () => import('./SidebarWidget').then(m => m.default),
+      order: 100,
+    },
+  ],
+};
+```
+
+**Plugin Store:**
+```typescript
+// Get all plugins
+const plugins = usePluginStore((state) => state.plugins);
+
+// Enable/disable plugin
+const { enablePlugin, disablePlugin } = usePluginStore();
+enablePlugin('@lego/plugin-dashboard');
+```
+
+---
+
+## Providers Stack
+
+**Order matters!** From outer to inner:
+
+```typescript
+<BrowserRouter>
+  <ThemeProvider>
+    <QueryProvider>
+      <PocketBaseProvider>
+        <SlotProvider>
+          <ChannelProvider>
+            <App />
+            <Toaster />
+          </ChannelProvider>
+        </SlotProvider>
+      </PocketBaseProvider>
+    </QueryProvider>
+  </ThemeProvider>
+</BrowserRouter>
+```
+
+**Each provider:**
+
+| Provider | Purpose |
+|----------|---------|
+| `BrowserRouter` | React Router v6 routing |
+| `ThemeProvider` | Dark mode, CSS variables |
+| `QueryProvider` | TanStack Query for server state |
+| `PocketBaseProvider` | Backend client, auth persistence |
+| `SlotProvider` | Plugin slot injection context |
+| `ChannelProvider` | Channel bus integrations (toast, etc.) |
+| `Toaster` | Shadcn toast notifications |
+
+---
+
+## Development vs Production Mode
+
+### Development Mode
+```bash
+pnpm run dev:all
+```
+
+- Each plugin runs on **separate dev server**
+  - Host: `http://localhost:8080`
+  - Dashboard: `http://localhost:3001`
+  - Todo: `http://localhost:3002`
+- **Hot Module Replacement (HMR)** enabled
+- Source maps available
+- Independent plugin debugging
+
+### Production Mode
+```bash
+pnpm run build
+```
+
+- All plugins **bundled into host**
+- Code-split by route
+- Single deployment artifact
+- Minified and optimized
+
+---
+
+## Garfish Integration
+
+**Plugin Registration:** `host/src/modern.runtime.ts`
+
+```typescript
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [
+      {
+        name: '@lego/plugin-dashboard',
+        entry: isDev
+          ? 'http://localhost:3001'        // Dev: separate server
+          : () => import('@lego/plugin-dashboard'),  // Prod: bundle
+        activeWhen: '/dashboard',
+      },
+      {
+        name: '@lego/plugin-todo',
+        entry: isDev
+          ? 'http://localhost:3002'
+          : () => import('@lego/plugin-todo'),
+        activeWhen: '/todos',
+      },
+    ],
+  },
+});
+```
+
+---
+
+## Best Practices for AI
+
+**When working with Kernel code:**
+
+1. **DO** modify kernel code when:
+   - Adding new shared services
+   - Fixing kernel bugs
+   - Implementing framework features
+   - User explicitly requests kernel changes
+
+2. **DO NOT** modify kernel code when:
+   - Working on application-specific features
+   - Adding plugin business logic
+   - Implementing custom UI (use plugins instead)
+
+3. **FOLLOW these patterns:**
+   - Use Zod for validation schemas
+   - Use TanStack Query for data fetching
+   - Use Zustand for state management
+   - Export barrel index files
+   - Add TypeScript types for all interfaces
+
+4. **TESTING:**
+   - Unit tests in `__tests__/` folders
+   - Component tests for UI
+   - Mock PocketBase in tests
+   - Test multi-tenancy (org isolation)
+
+5. **NAMING CONVENTIONS:**
+   - Files: `PascalCase.ts` for types/components, `kebab-case` for utilities
+   - Hooks: `useXxx.ts`
+   - Types: `Xxx`, `XxxType`, `XxxProps`, `XxxData`
+   - Constants: `UPPER_SNAKE_CASE`
+   - Interfaces: `PascalCase`
+
+---
+
+**Next:** Read [`05-plugin-system.md`](./05-plugin-system.md) for plugin architecture details.