create-lego-one 2.0.10 → 2.0.13

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/e2e/auth.spec.ts

@@ -0,0 +1,38 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Authentication', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+  });
+
+  test('should show sign in page when not authenticated', async ({ page }) => {
+    await expect(page.locator('h1')).toContainText('Sign In');
+  });
+
+  test('should show sign in form', async ({ page }) => {
+    await expect(page.locator('input[type="email"]')).toBeVisible();
+    await expect(page.locator('input[type="password"]')).toBeVisible();
+    await expect(page.locator('button[type="submit"]')).toBeVisible();
+  });
+
+  test('should show validation errors for empty form', async ({ page }) => {
+    await page.click('button[type="submit"]');
+
+    // Should show validation errors
+    const emailInput = page.locator('input[type="email"]');
+    await expect(emailInput).toBeFocused();
+  });
+
+  test('should toggle password visibility', async ({ page }) => {
+    const passwordInput = page.locator('input[type="password"]');
+    const toggleButton = page.locator('button').filter({ hasText: /show/i }).first();
+
+    await passwordInput.fill('testpassword');
+
+    // Click show password button
+    if (await toggleButton.isVisible()) {
+      await toggleButton.click();
+      await expect(passwordInput).toHaveAttribute('type', 'text');
+    }
+  });
+});

package/template/host/e2e/layout.spec.ts

@@ -0,0 +1,38 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Layout & Navigation', () => {
+  test.beforeEach(async ({ page }) => {
+    // Mock authentication state
+    await page.goto('/');
+  });
+
+  test('should render sidebar', async ({ page }) => {
+    const sidebar = page.locator('aside').first();
+    await expect(sidebar).toBeVisible();
+  });
+
+  test('should render top bar', async ({ page }) => {
+    const topbar = page.locator('header').first();
+    await expect(topbar).toBeVisible();
+  });
+
+  test('should show navigation links', async ({ page }) => {
+    // Check for common navigation items
+    const dashboardLink = page.locator('a, button').filter({ hasText: /dashboard/i });
+    if (await dashboardLink.count() > 0) {
+      await expect(dashboardLink.first()).toBeVisible();
+    }
+  });
+
+  test('should be responsive on mobile', async ({ page }) => {
+    // Set mobile viewport
+    await page.setViewportSize({ width: 375, height: 667 });
+
+    // Check if mobile menu is available
+    const mobileMenuButton = page.locator('button').filter({ hasText: /menu/i });
+    if (await mobileMenuButton.isVisible()) {
+      await mobileMenuButton.click();
+      // Mobile menu should be open
+    }
+  });
+});

package/template/host/modern.config.ts

@@ -0,0 +1,19 @@
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { garfishPlugin } from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  // Enable Rspack for high-performance builds
+  tools: {
+    rspack: (config) => {
+      return config;
+    },
+  },
+
+  // Enable file-based routing for the host kernel
+  runtime: {
+    router: true,
+  },
+
+  // Register Garfish plugin for micro-frontend capabilities
+  plugins: [appTools(), garfishPlugin()],
+});