create-lego-one 2.0.12 → 2.0.14

package/template/docs/framework/setup/README.md

@@ -0,0 +1,548 @@
+# Lego-One Setup Guide
+
+**AI-Friendly Documentation for Vibe Coding**
+
+Complete guide for installing, configuring, and extending Lego-One. This documentation is optimized for AI agents to understand and execute tasks efficiently.
+
+---
+
+## Quick Reference for AI Agents
+
+When an AI agent is asked to work with Lego-One, follow this priority:
+
+1. **Read `00-index.md` first** - This is the main entry point with complete documentation index
+2. **Read relevant numbered files** based on your task (see table below)
+3. **Review existing plugins** in `packages/plugins/@lego/` for code patterns
+4. **Follow the established conventions** - consistency is critical
+5. **Write checkpoints** for all work in `/docs/checkpoints/`
+
+---
+
+## Documentation Structure
+
+Read these files **sequentially** for complete framework understanding:
+
+### Getting Started (Read First)
+
+| # | File | Description |
+|---|------|-------------|
+| 00 | [`00-index.md`](./00-index.md) | **MAIN ENTRY POINT** - Complete AI documentation index |
+| 01 | [`01-framework-structure.md`](./01-framework-structure.md) | Project structure, architecture, file locations |
+| 02 | [`02-development-workflow.md`](./02-development-workflow.md) | How to work on this framework (dev, build, test) |
+| 03 | [`03-environment-setup.md`](./03-environment-setup.md) | Environment variables, dependencies, prerequisites |
+
+### Core Concepts
+
+| # | File | Description |
+|---|------|-------------|
+| 04 | [`04-kernel-architecture.md`](./04-kernel-architecture.md) | Host/Kernel system, core infrastructure |
+| 05 | [`05-plugin-system.md`](./05-plugin-system.md) | Plugin architecture, Garfish, micro-frontends |
+| 06 | [`06-communication-patterns.md`](./06-communication-patterns.md) | Window bridge, channel bus, plugin-host communication |
+
+### Development Patterns
+
+| # | File | Description |
+|---|------|-------------|
+| 07 | [`07-plugin-development.md`](./07-plugin-development.md) | Complete guide to creating plugins |
+| 08 | [`08-component-library.md`](./08-component-library.md) | UI components, styling, design system |
+| 09 | [`09-data-integration.md`](./09-data-integration.md) | PocketBase, multi-tenancy, data fetching |
+| 10 | [`10-auth-rbac.md`](./10-auth-rbac.md) | Authentication, authorization, permissions |
+
+### API Reference
+
+| # | File | Description |
+|---|------|-------------|
+| 11 | [`11-hooks-api.md`](./11-hooks-api.md) | All kernel hooks (auth, RBAC, state, channels) |
+| 12 | [`12-components-api.md`](./12-components-api.md) | UI component library reference |
+| 13 | [`13-deployment-guide.md`](./13-deployment-guide.md) | Production deployment instructions |
+
+---
+
+## Quick Start
+
+### For End Users (Creating a New Project)
+
+```bash
+# Create a new Lego-One application
+pnpm create lego-one my-saas-app
+
+cd my-saas-app
+
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm run dev
+```
+
+The application will be available at http://localhost:8080
+
+**Default credentials:**
+- Email: `admin@example.com`
+- Password: `admin123`
+
+### For Developers (Working on Framework)
+
+#### Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+- **Node.js** 20 or higher ([Download](https://nodejs.org/))
+- **pnpm** 9 or higher ([Install](https://pnpm.io/installation))
+- **Git** ([Download](https://git-scm.com/))
+- (Optional) **Docker** and **Docker Compose** for containerized deployment
+
+#### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/your-org/lego-one.git
+cd lego-one
+```
+
+#### Step 2: Install Dependencies
+
+```bash
+pnpm install
+```
+
+This installs all dependencies for the host and included plugins.
+
+#### Step 3: Configure Environment
+
+Create your environment file:
+
+```bash
+cp .env.development.example .env.development
+```
+
+Edit `.env.development` with your settings. Default configuration works for local development:
+
+```bash
+# PocketBase (local)
+VITE_POCKETBASE_URL=http://127.0.0.1:8090
+
+# Application
+VITE_APP_URL=http://localhost:8080
+```
+
+#### Step 4: Start PocketBase
+
+PocketBase is the backend database. Start it in a separate terminal:
+
+```bash
+cd pocketbase
+
+# Download PocketBase if not present
+# Visit https://pocketbase.io/docs/
+# Download the binary for your OS and extract it
+
+./pocketbase serve
+```
+
+Or use Docker:
+
+```bash
+docker-compose up pocketbase
+```
+
+PocketBase will:
+- Start on http://127.0.0.1:8090
+- Run migrations automatically
+- Create seed data (admin user, demo org)
+
+#### Step 5: Start Development
+
+```bash
+pnpm run dev
+```
+
+This starts the host application on http://localhost:8080.
+
+Open your browser and navigate to http://localhost:8080
+
+**Default credentials:**
+- Email: `admin@example.com`
+- Password: `admin123`
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `VITE_POCKETBASE_URL` | PocketBase API URL | `http://127.0.0.1:8090` |
+| `VITE_APP_URL` | Application base URL | `http://localhost:8080` |
+| `VITE_ENABLE_DEV_TOOLS` | Enable React DevTools | `true` (dev only) |
+
+### Plugin Configuration
+
+Plugins are enabled/disabled in `host/src/saas.config.ts`:
+
+```typescript
+export const saasConfig = {
+  plugins: [
+    { name: '@lego/plugin-dashboard', enabled: true },
+    { name: '@lego/plugin-todo', enabled: true },
+  ],
+};
+```
+
+Change `enabled: false` to disable a plugin.
+
+### Organization Setup
+
+After first login:
+1. An organization is auto-created for you
+2. You are assigned the "Owner" role
+3. Use the organization selector in the topbar to switch organizations
+
+---
+
+## Development
+
+### Running All Services
+
+To run the host and all plugins on separate ports:
+
+```bash
+pnpm run dev:all
+```
+
+This starts:
+- **Host:** http://localhost:8080
+- **Dashboard Plugin:** http://localhost:3001
+- **Todo Plugin:** http://localhost:3002
+
+### Running Individual Services
+
+**Host only:**
+```bash
+pnpm run dev:host
+```
+
+**Dashboard plugin only:**
+```bash
+cd packages/plugins/@lego/plugin-dashboard
+pnpm run dev
+```
+
+**Todo plugin only:**
+```bash
+cd packages/plugins/@lego/plugin-todo
+pnpm run dev
+```
+
+### Running Tests
+
+```bash
+# All tests
+pnpm test
+
+# Unit and component tests only
+pnpm test:run
+
+# E2E tests
+pnpm test:e2e
+
+# With coverage report
+pnpm test:coverage
+```
+
+### Linting and Formatting
+
+```bash
+# Lint all code
+pnpm run lint
+
+# Format code
+pnpm run format
+```
+
+---
+
+## Plugins
+
+See [`07-plugin-development.md`](./07-plugin-development.md) for creating custom plugins.
+
+### Included Plugins
+
+**Dashboard Plugin** (`@lego/plugin-dashboard`)
+- Organization statistics
+- Recent activity feed
+- Quick actions
+- Location: `/dashboard`
+
+**Todo Plugin** (`@lego/plugin-todo`)
+- Full CRUD for tasks
+- Priority levels
+- Due dates
+- Filtering and search
+- Location: `/todos`
+
+### Enabling/Disabling Plugins
+
+**Via Config File:**
+
+Edit `host/src/saas.config.ts` and set `enabled: false`
+
+**Via Admin UI:**
+
+Navigate to Settings → Plugins and toggle the plugin.
+
+---
+
+## Production Deployment
+
+### Building for Production
+
+```bash
+# Build all (recommended)
+pnpm run build
+
+# Build host only
+pnpm run build:host
+```
+
+Output directory: `host/dist/`
+
+### Docker Deployment
+
+```bash
+# Build and start with Docker Compose
+docker-compose -f docker-compose.prod.yml up -d --build
+```
+
+See [`13-deployment-guide.md`](./13-deployment-guide.md) for detailed deployment instructions.
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**"Cannot connect to PocketBase"**
+- Ensure PocketBase is running: `./pocketbase serve`
+- Check `VITE_POCKETBASE_URL` in .env file
+- Verify no firewall blocking port 8090
+
+**"Module not found" errors**
+- Clear cache: `pnpm run clean`
+- Reinstall: `rm -rf node_modules && pnpm install`
+
+**"Port already in use"**
+```bash
+# Find and kill process on port 8080
+lsof -ti:8080 | xargs kill -9  # macOS/Linux
+netstat -ano | findstr :8080    # Windows
+```
+
+**Plugin not loading**
+- Check browser console for errors
+- Verify plugin is enabled in `saas.config.ts`
+- Ensure plugin dev server is running (dev mode)
+- Check `modern.runtime.ts` has plugin registered
+
+**Hot reload not working**
+- Clear browser cache
+- Restart dev server
+- Check for syntax errors in your code
+
+### Getting Help
+
+If you're still stuck:
+
+1. Read [`02-development-workflow.md`](./02-development-workflow.md) troubleshooting section
+2. Review [Implementation Plans](../plans/)
+3. Examine [Existing Plugins](../../packages/plugins/)
+4. Open an issue on GitHub
+
+---
+
+## For AI Agents
+
+### Critical Information for Task Execution
+
+When working with Lego-One, AI agents should understand these core concepts:
+
+**Architecture Pattern:**
+- **Host/Kernel** (`host/`) - Core application with auth, RBAC, state management
+- **Plugins** (`packages/plugins/@lego/`) - Feature modules loaded by host
+- **Communication** - Window bridge pattern: `window.__LEGO_KERNEL_STATE__` and `window.__LEGO_CHANNEL_BUS__`
+
+**File Location Conventions:**
+```
+host/src/
+├── kernel/           # Core systems (auth, RBAC, state, channels)
+├── layout/           # Layout components (Sidebar, Topbar, Shell)
+├── routes/           # Page routes
+├── providers/        # Context providers
+└── test/            # Test setup
+
+packages/plugins/@lego/plugin-<name>/
+├── src/
+│   ├── components/   # Plugin components
+│   ├── hooks/        # Data fetching hooks
+│   ├── pages/        # Plugin pages
+│   ├── plugin.config.ts  # Plugin configuration
+│   └── plugin.ts     # Entry point
+```
+
+**Plugin Development Checklist:**
+1. Read `00-index.md` first
+2. Read `07-plugin-development.md` for complete guide
+3. Review existing plugins (Dashboard, Todo) for patterns
+4. Create all required files in correct structure
+5. Register plugin in `host/src/modern.runtime.ts`
+6. Enable in `host/src/saas.config.ts`
+7. Test thoroughly
+8. Write checkpoint in `/docs/checkpoints/`
+
+**Key Hooks and APIs:**
+- `usePocketBase()` - Access PocketBase client
+- `useCurrentOrganization()` - Get current organization context
+- `useUserPermissions()` - Get user permissions
+- `useGlobalKernelState()` - Access kernel state
+- `useToastChannel()` - Show toast notifications
+- `window.__LEGO_KERNEL_STATE__` - Read-only kernel state access
+- `window.__LEGO_CHANNEL_BUS__` - Event publishing/subscribing
+
+**Import Path Conventions:**
+```typescript
+// From host kernel
+import { usePocketBase } from '@/kernel/providers/PocketBaseProvider';
+import { useCurrentOrganization } from '@/kernel/hooks/useCurrentOrganization';
+import { Button } from '@/kernel/components/ui/Button';
+
+// Window bridge (in plugins)
+const kernelState = window.__LEGO_KERNEL_STATE__;
+const channelBus = window.__LEGO_CHANNEL_BUS__;
+```
+
+**Testing Commands:**
+```bash
+# Run all tests
+pnpm test
+
+# Unit and component tests
+pnpm --filter './host' test
+
+# E2E tests (requires dev server running)
+pnpm test:e2e
+
+# Coverage report
+pnpm test:coverage
+```
+
+**Build Commands:**
+```bash
+# Build all
+pnpm run build
+
+# Build host only
+pnpm --filter './host' build
+
+# Build specific plugin
+pnpm --filter './packages/plugins/@lego/plugin-dashboard' build
+```
+
+**Version Management (Framework Maintainers):**
+```bash
+# Patch release (bug fixes)
+pnpm run version:patch
+
+# Minor release (new features)
+pnpm run version:minor
+
+# Major release (breaking changes)
+pnpm run version:major
+
+# Full release workflow
+pnpm run release
+```
+
+### Common AI Task Patterns
+
+**Creating a Plugin:**
+1. Use the CLI: `pnpm run create-plugin <plugin-name>` or create manually
+2. Follow the exact structure of existing plugins
+3. Copy patterns from Todo Plugin for CRUD features
+4. Copy patterns from Dashboard Plugin for display features
+5. Always create: types.ts, schemas.ts, hooks/, components/, pages/
+6. Register in `modern.runtime.ts` and `saas.config.ts`
+
+**Adding UI Components:**
+1. Check if component exists in `host/src/kernel/components/ui/`
+2. Use existing components: Button, Input, Badge, Dialog, etc.
+3. Follow Tailwind CSS naming conventions
+4. Ensure responsive design (mobile-first)
+
+**Data Operations:**
+1. Use `usePocketBase()` hook for API access
+2. Use TanStack Query for data fetching (via custom hooks)
+3. Always scope queries to current organization
+4. Handle loading and error states
+5. Show toast notifications for actions
+
+**Multi-Tenancy:**
+1. All data must be scoped to organization
+2. Use `useCurrentOrganization()` to get org context
+3. Filter PocketBase queries: `filter: 'organizationId = "${orgId}"'`
+4. Set API rules in PocketBase for data isolation
+
+**Testing:**
+1. Write unit tests for hooks and utilities
+2. Write component tests for UI components
+3. Mock PocketBase and window bridge in tests
+4. Use test setup in `host/src/test/setup.ts`
+
+### Important Constraints
+
+**DO NOT:**
+- Skip reading documentation before coding
+- Create circular dependencies between host and plugins
+- Import directly from host kernel in plugins (use window bridge)
+- Skip TypeScript strict mode compliance
+- Forget to handle loading and error states
+- Create components without responsive design
+- Skip testing before completion
+- Forget to write checkpoints for your work
+
+**ALWAYS:**
+- Read relevant documentation first
+- Follow existing file structures and naming conventions
+- Use window bridge for host-plugin communication
+- Implement proper error handling
+- Test in both dev and production modes
+- Document complex logic
+- Use established UI components
+- Write checkpoints in `/docs/checkpoints/`
+
+### Quick Decision Tree
+
+```
+Task: Create a new feature
+├─ Is it a CRUD feature? → Follow Todo Plugin pattern (file 07)
+├─ Is it display only? → Follow Dashboard Plugin pattern (file 07)
+├─ Does it need backend storage? → Create PocketBase collection
+├─ Does it need authentication? → Add protected route
+└─ Is it a calculation? → Create hook with pure functions
+
+Task: Fix a bug
+├─ In host kernel? → Edit files in host/src/kernel/
+├─ In plugin? → Edit files in packages/plugins/@lego/plugin-<name>/
+├─ UI related? → Check components and layout
+└─ Data related? → Check hooks and PocketBase queries
+```
+
+---
+
+## Next Steps
+
+- Start with [`00-index.md`](./00-index.md) for complete documentation overview
+- Explore the [Dashboard Plugin](../../packages/plugins/@lego/plugin-dashboard)
+- Explore the [Todo Plugin](../../packages/plugins/@lego/plugin-todo)
+- Read [`07-plugin-development.md`](./07-plugin-development.md) for plugin creation
+- Check [`11-hooks-api.md`](./11-hooks-api.md) for kernel hooks reference
+- Review [`13-deployment-guide.md`](./13-deployment-guide.md) for deployment

package/template/host/package.json

@@ -1,6 +1,6 @@
 {
   "name": "host",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "private": true,
   "type": "module",
   "scripts": {

package/template/nginx.conf

@@ -0,0 +1,72 @@
+user nginx;
+worker_processes auto;
+error_log /var/log/nginx/error.log warn;
+pid /var/run/nginx.pid;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" "$http_x_forwarded_for"';
+
+    access_log /var/log/nginx/access.log main;
+
+    sendfile on;
+    tcp_nopush on;
+    keepalive_timeout 65;
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json;
+
+    server {
+        listen 80;
+        server_name _;
+        root /usr/share/nginx/html;
+        index index.html;
+
+        # Security headers
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header X-XSS-Protection "1; mode=block" always;
+
+        # Main application
+        location / {
+            try_files $uri $uri/ /index.html;
+        }
+
+        # API proxy to PocketBase
+        location /api/ {
+            proxy_pass http://localhost:8090/;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_set_header Host $host;
+            proxy_cache_bypass $http_upgrade;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+        # Static assets caching
+        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+        }
+
+        # PocketBase admin UI (optional, for development)
+        location /_pb/ {
+            proxy_pass http://localhost:8090/_/;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_set_header Host $host;
+        }
+    }
+}

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lego-one",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "private": true,
   "description": "Microkernel SaaS OS with Modern.js + Garfish + PocketBase",
   "type": "module",

package/template/packages/plugins/@lego/plugin-dashboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lego/plugin-dashboard",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "private": true,
   "type": "module",
   "scripts": {

package/template/packages/plugins/@lego/plugin-todo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lego/plugin-todo",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "private": true,
   "type": "module",
   "scripts": {