create-lego-one 2.0.10 → 2.0.13

package/template/docs/framework/setup/01-framework-structure.md

@@ -0,0 +1,308 @@
+# Framework Structure
+
+**Lego-One Architecture and File Organization**
+
+---
+
+## Overview
+
+Lego-One uses a **microkernel architecture** where the Host (Kernel) provides core services and plugins provide features. This separation enables independent plugin development and deployment.
+
+---
+
+## Project Structure
+
+```
+lego-one/
+├── host/                          # Kernel application (main app)
+│   ├── src/
+│   │   ├── kernel/               # Core systems
+│   │   │   ├── shared-state/      # Zustand store + window bridge
+│   │   │   ├── providers/         # PocketBase, Query, Theme
+│   │   │   ├── plugins/           # Plugin system, slots
+│   │   │   ├── channels/          # Garfish channel bus
+│   │   │   ├── auth/              # Authentication logic
+│   │   │   ├── rbac/              # Multitenancy, permissions
+│   │   │   ├── lib/               # Utilities (cn, formatDate)
+│   │   │   └── components/        # Shared UI components
+│   │   ├── layout/                # Layout components
+│   │   │   ├── Shell.tsx          # Main app shell
+│   │   │   ├── Sidebar.tsx        # Left sidebar
+│   │   │   └── Topbar.tsx         # Top navigation bar
+│   │   ├── routes/                # Page routes
+│   │   │   ├── index.tsx          # Home/landing
+│   │   │   ├── login.tsx          # Sign in page
+│   │   │   ├── dashboard.tsx      # Dashboard (placeholder)
+│   │   │   └── settings/          # Settings pages
+│   │   ├── bootstrap.tsx          # App entry point
+│   │   ├── modern.runtime.ts      # Garfish plugin config
+│   │   └── saas.config.ts         # Plugin enable/disable config
+│   ├── modern.config.ts           # Modern.js configuration
+│   ├── tailwind.config.ts         # Tailwind CSS configuration
+│   └── package.json
+│
+├── packages/
+│   ├── plugins/
+│   │   └── @lego/
+│   │       ├── plugin-dashboard/  # Dashboard plugin example
+│   │       │   ├── src/
+│   │       │   │   ├── components/    # Dashboard components
+│   │       │   │   ├── hooks/         # Data fetching hooks
+│   │       │   │   ├── pages/         # Dashboard page
+│   │       │   │   ├── plugin.config.ts # Plugin configuration
+│   │       │   │   └── plugin.ts      # Entry export
+│   │       │   ├── modern.config.ts
+│   │       │   └── package.json
+│   │       │
+│   │       └── plugin-todo/        # Todo plugin example
+│   │           ├── src/
+│   │           │   ├── components/    # Todo components
+│   │           │   ├── hooks/         # CRUD operations
+│   │           │   ├── pages/         # Todo page
+│   │           │   ├── plugin.config.ts # Plugin configuration
+│   │           │   └── plugin.ts      # Entry export
+│   │           ├── modern.config.ts
+│   │           └── package.json
+│   │
+│   └── create-lego-one/           # CLI tool for `pnpm create`
+│       ├── src/
+│       │   └── index.ts            # CLI entry point
+│       ├── template/                # Template files (copied to new projects)
+│       └── package.json
+│
+├── pocketbase/                     # PocketBase data directory
+│   ├── pb_data/                    # SQLite database files
+│   ├── pb_migrations/              # Database migrations
+│   └── pocketbase                  # PocketBase binary
+│
+├── scripts/                        # Automation scripts
+│   ├── create-plugin.js            # Plugin scaffolding script
+│   ├── version.js                 # Version management script
+│   └── deploy.sh                  # Deployment script
+│
+├── docs/
+│   ├── framework/                  # Architecture docs
+│   │   ├── setup/                  # AI documentation (read this!)
+│   │   ├── plans/                  # Implementation plans
+│   │   └── research/               # Architecture research
+│   ├── checkpoints/                # Progress tracking
+│   │   ├── bugfixes/               # Bug fix documentation
+│   │   ├── features/               # Feature implementation docs
+│   │   └── enhancements/           # Enhancement documentation
+│   └── guides/                     # User guides
+│
+├── .env.example                    # Environment variables template
+├── Dockerfile                      # Multi-stage Docker build
+├── docker-compose.yml              # Local development stack
+├── pnpm-workspace.yaml            # pnpm workspace configuration
+├── CLAUDE.md                       # AI workflow rules
+└── package.json                    # Root package configuration
+```
+
+---
+
+## Architecture Layers
+
+### Layer 1: Host (Kernel)
+
+**Purpose:** Provide core infrastructure and services
+
+**Location:** `host/`
+
+**Responsibilities:**
+- User authentication and sessions
+- Multi-tenancy and RBAC
+- Global state management
+- Plugin loading and lifecycle
+- UI layout (sidebar, topbar)
+- Route management
+- Data providers (PocketBase, Query)
+
+**Key Files:**
+```
+host/src/kernel/
+├── shared-state/store.ts          # Zustand global store
+├── providers/PocketBaseProvider.tsx  # PocketBase client
+├── providers/QueryProvider.tsx     # TanStack Query client
+├── auth/                           # Authentication hooks
+├── rbac/                           # Authorization hooks
+├── channels/                       # Event bus
+└── plugins/                        # Plugin system
+```
+
+### Layer 2: Plugins
+
+**Purpose:** Provide feature modules
+
+**Location:** `packages/plugins/@lego/`
+
+**Responsibilities:**
+- Feature-specific UI
+- Feature-specific data operations
+- Feature-specific business logic
+
+**Communication:** Via window bridge (`window.__LEGO_KERNEL_STATE__`, `window.__LEGO_CHANNEL_BUS__`)
+
+### Layer 3: Data Layer
+
+**Purpose:** Backend persistence and API
+
+**Technology:** PocketBase (SQLite with REST API)
+
+**Location:** `pocketbase/`
+
+**Features:**
+- Multi-tenant data isolation
+- User authentication
+- Organization management
+- Role-based access control
+
+---
+
+## Dev vs Production Mode
+
+### Development Mode
+
+Each plugin runs on independent dev server:
+
+| Service | URL | Port |
+|---------|-----|------|
+| Host | http://localhost:8080 | 8080 |
+| Dashboard Plugin | http://localhost:3001 | 3001 |
+| Todo Plugin | http://localhost:3002 | 3002 |
+
+**Benefits:**
+- Hot module replacement (HMR)
+- Independent plugin debugging
+- Fast iteration
+
+### Production Mode
+
+All plugins bundled into host application:
+
+**Output:** `host/dist/` (single bundle)
+
+**Benefits:**
+- One deployment artifact
+- Optimized and minified
+- Code-split by route
+
+---
+
+## Communication Patterns
+
+### Host → Plugin
+
+**Via Window Bridge:**
+```typescript
+// In plugin, access host state
+const kernelState = window.__LEGO_KERNEL_STATE__;
+const user = kernelState?.user;
+const organization = kernelState?.organization;
+```
+
+### Plugin → Host
+
+**Via Channel Bus:**
+```typescript
+// In plugin, publish events
+const channelBus = window.__LEGO_CHANNEL_BUS__;
+channelBus?.publish('lego:toast', {
+  type: 'success',
+  title: 'Success!',
+  description: 'Operation completed',
+});
+```
+
+### Plugin ↔ Plugin
+
+**Via Channel Bus:**
+```typescript
+// Subscribe to events
+const unsubscribe = channelBus?.subscribe('custom:event', (data) => {
+  console.log('Received:', data);
+});
+```
+
+---
+
+## Slot Injection System
+
+**Available Slots:**
+
+| Slot | Location | Purpose |
+|------|----------|---------|
+| `sidebar:top` | Top of sidebar | User menu, logo |
+| `sidebar:nav` | Main navigation | Plugin navigation links |
+| `sidebar:bottom` | Bottom of sidebar | Logout, settings |
+| `topbar:left` | Left side | Breadcrumbs, back button |
+| `topbar:center` | Center | Page title, search |
+| `topbar:right` | Right side | Notifications, user menu |
+| `dashboard:widgets` | Dashboard | Statistics, activity feeds |
+
+**Injection Example:**
+```typescript
+// In plugin.config.ts
+export const pluginConfig: PluginConfig = {
+  slots: [
+    {
+      slot: 'sidebar:nav',
+      component: () => import('./components/SidebarWidget').then(m => m.default),
+      order: 100,
+    },
+  ],
+};
+```
+
+---
+
+## Configuration Files
+
+### host/saas.config.ts
+
+**Purpose:** Enable/disable plugins
+
+```typescript
+export const saasConfig = {
+  plugins: [
+    { name: '@lego/plugin-dashboard', enabled: true },
+    { name: '@lego/plugin-todo', enabled: true },
+  ],
+};
+```
+
+### host/src/modern.runtime.ts
+
+**Purpose:** Register plugins with Garfish
+
+```typescript
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [
+      {
+        name: '@lego/plugin-dashboard',
+        entry: isDev
+          ? 'http://localhost:3001'
+          : () => import('@lego/plugin-dashboard'),
+        activeWhen: '/dashboard',
+      },
+    ],
+  },
+});
+```
+
+---
+
+## Key Files to Reference
+
+| Purpose | File |
+|---------|------|
+| Kernel hooks | `host/src/kernel/hooks/` |
+| Kernel components | `host/src/kernel/components/` |
+| Plugin examples | `packages/plugins/@lego/plugin-dashboard/`, `packages/plugins/@lego/plugin-todo/` |
+| Window bridge types | `packages/plugins/@lego/plugin-todo/src/vite-env.d.ts` |
+| Plugin config | `packages/plugins/@lego/plugin-*/src/plugin.config.ts` |
+
+---
+
+**Next:** Read [`02-development-workflow.md`](./02-development-workflow.md) to understand how to work on this framework.

package/template/docs/framework/setup/02-development-workflow.md

@@ -0,0 +1,405 @@
+# Development Workflow
+
+**How to Work on the Lego-One Framework**
+
+---
+
+## Overview
+
+This guide covers the complete development workflow for Lego-One, including running, building, testing, and debugging the framework.
+
+---
+
+## Quick Start Commands
+
+```bash
+# Start everything (host + all plugins)
+pnpm run dev:all
+
+# Start host only
+pnpm run dev:host
+
+# Start specific plugin
+cd packages/plugins/@lego/plugin-dashboard && pnpm run dev
+
+# Build everything
+pnpm run build
+
+# Run tests
+pnpm test
+
+# E2E tests
+pnpm test:e2e
+```
+
+---
+
+## Development Servers
+
+### Running All Services
+
+```bash
+pnpm run dev:all
+```
+
+**Service URLs:**
+- **Host:** http://localhost:8080
+- **Dashboard Plugin:** http://localhost:3001
+- **Todo Plugin:** http://localhost:3002
+- **PocketBase Admin:** http://localhost:8090/_/
+
+### Running Individual Services
+
+**Host only:**
+```bash
+pnpm run dev:host
+# or
+cd host && pnpm run dev
+```
+
+**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
+```
+
+### PocketBase Setup
+
+Start PocketBase in a separate terminal:
+
+```bash
+cd pocketbase
+
+# Start PocketBase (development mode)
+./pocketbase serve
+
+# Or in production mode
+./pocketbase serve --prod
+```
+
+**Default Admin Credentials:**
+- Email: `admin@example.com`
+- Password: `admin123`
+
+⚠️ **Important:** Change default credentials in production!
+
+---
+
+## Building for Production
+
+### Build Commands
+
+```bash
+# Build all (recommended)
+pnpm run build
+
+# Build host only
+pnpm run build:host
+# or
+pnpm --filter './host' build
+
+# Build specific plugin
+pnpm --filter './packages/plugins/@lego/plugin-dashboard' build
+```
+
+### Build Output
+
+Output directory: `host/dist/`
+
+**Production mode characteristics:**
+- All plugins bundled into host
+- Code-split by route
+- Optimized and minified
+- Source maps included
+
+---
+
+## Testing
+
+### Unit and Component Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run tests in watch mode
+pnpm --filter './host' test
+
+# Test with coverage
+pnpm test:coverage
+
+# Test UI mode
+pnpm --filter './host' test:ui
+```
+
+### E2E Tests
+
+```bash
+# Run E2E tests (requires dev server running)
+pnpm test:e2e
+```
+
+### Test Files Location
+
+```
+host/src/
+├── kernel/
+│   └── __tests__/           # Unit tests for kernel modules
+├── components/
+│   └── __tests__/           # Component tests
+└── test/
+    ├── setup.ts             # Test setup and mocks
+    └── utils.tsx            # Test utilities
+```
+
+---
+
+## Common Development Tasks
+
+### Adding a New Plugin
+
+1. **Use the CLI** (if available):
+```bash
+pnpm run create-plugin my-plugin
+```
+
+2. **Or create manually:**
+```bash
+mkdir -p packages/plugins/@lego/plugin-my-plugin
+cd packages/plugins/@lego/plugin-my-plugin
+# Create plugin structure (see file 07: Plugin Development)
+```
+
+3. **Register plugin:**
+- Add to `host/src/modern.runtime.ts`
+- Add to `host/src/saas.config.ts`
+
+### Adding a New PocketBase Collection
+
+1. **Define collection schema** in `pocketbase/pb_migrations/`
+2. **Include multi-tenancy fields:**
+```javascript
+{
+  name: 'mycollection',
+  fields: [
+    { name: 'organizationId', type: 'relation', required: true },
+    { name: 'ownerId', type: 'relation', required: true },
+    // ... your fields
+  ],
+}
+```
+3. **Set API rules** for organization isolation:
+```
+listRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations'
+viewRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations'
+createRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations'
+updateRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations && ownerId = @request.auth.id'
+deleteRule: '@request.auth.id != "" && organizationId = @request.auth.membership.organizations && ownerId = @request.auth.id'
+```
+
+### Debugging Plugin Not Loading
+
+**Symptoms:** Plugin doesn't appear in navigation
+
+**Solutions:**
+1. Check plugin is enabled in `host/src/saas.config.ts`
+2. Check `plugin.config.ts` has correct structure
+3. Check browser console for errors
+4. Verify plugin dev server is running (dev mode)
+5. Check `modern.runtime.ts` has plugin registered
+6. Verify `activeWhen` path matches route
+
+### Hot Module Replacement Not Working
+
+**Solutions:**
+1. Clear browser cache
+2. Restart dev server
+3. Check for syntax errors in your code
+4. Verify Modern.js config includes `@modern-js/plugin-garfish`
+
+---
+
+## Environment Variables
+
+### Development (.env.development)
+
+```bash
+# PocketBase (local)
+VITE_POCKETBASE_URL=http://127.0.0.1:8090
+
+# Application
+VITE_APP_URL=http://localhost:8080
+
+# Features
+VITE_ENABLE_DEV_TOOLS=true
+```
+
+### Production (.env.production)
+
+```bash
+# PocketBase (production)
+VITE_POCKETBASE_URL=https://pb.yourdomain.com
+
+# Application
+VITE_APP_URL=https://yourdomain.com
+
+# Features
+VITE_ENABLE_DEV_TOOLS=false
+```
+
+---
+
+## Troubleshooting
+
+### "Cannot connect to PocketBase"
+
+**Solutions:**
+1. Ensure PocketBase is running: `./pocketbase serve`
+2. Check `VITE_POCKETBASE_URL` in .env file
+3. Verify no firewall blocking port 8090
+
+### "Module not found" errors
+
+**Solutions:**
+1. Clear cache: `pnpm run clean`
+2. 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
+```
+
+### TypeScript Errors
+
+**Common Issues:**
+- Test files included in build → Add to `tsconfig.json` exclude
+- Import path incorrect → Check path mapping in tsconfig
+- Missing type definitions → Create `.d.ts` file
+
+---
+
+## Linting and Formatting
+
+```bash
+# Lint all code
+pnpm run lint
+
+# Format code
+pnpm run format
+
+# Type check
+pnpm run typecheck
+```
+
+---
+
+## Performance Tips
+
+### During Development
+
+1. **Close unused browser tabs** - Reduces memory usage
+2. **Restart dev server periodically** - Prevents memory leaks
+3. **Use code splitting** - Lazy load routes
+
+### For Production
+
+1. **Analyze bundle size:**
+```bash
+pnpm run build
+# Check dist/static/js/ sizes
+```
+
+2. **Enable compression** in nginx:
+```nginx
+gzip on;
+gzip_types text/plain text/css application/json application/javascript;
+```
+
+3. **Implement caching:**
+```nginx
+location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
+  expires 1y;
+  add_header Cache-Control "public, immutable";
+}
+```
+
+---
+
+## Debug Mode
+
+### Enable Debug Logging
+
+```typescript
+// In development, log everything
+if (import.meta.env.DEV) {
+  console.log('Debug info:', data);
+}
+```
+
+### Browser DevTools
+
+1. **React DevTools** - Component tree inspection
+2. **Redux DevTools** - State inspection (if using Redux)
+3. **Network tab** - API request debugging
+4. **Console** - Error messages and warnings
+
+---
+
+## Version Management
+
+### Bumping Version
+
+```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
+```
+
+### Publishing
+
+```bash
+# Publish CLI to npm
+pnpm run publish:cli
+```
+
+---
+
+## Checkpoint Workflow
+
+**IMPORTANT:** For every task, bugfix, or feature, create a checkpoint file:
+
+1. **Create checkpoint** in appropriate directory:
+```bash
+# For bugfixes
+docs/checkpoints/bugfixes/01-issue-description.md
+
+# For features
+docs/checkpoints/features/01-feature-name.md
+
+# For enhancements
+docs/checkpoints/enhancements/01-enhancement-name.md
+```
+
+2. **Use the template** from `docs/checkpoints/.template.md`
+
+3. **Update status** as you progress
+
+4. **Mark complete** when done
+
+---
+
+**Next:** Read [`03-environment-setup.md`](./03-environment-setup.md) for environment configuration.