create-lego-one 2.0.12 → 2.0.14

package/template/README.md

@@ -0,0 +1,325 @@
+# {APP_NAME}
+
+> {DESCRIPTION}
+
+Built with [Lego-One](https://github.com/your-org/lego-one) - A modular SaaS boilerplate with microkernel architecture.
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Node.js** 20+ - [Download](https://nodejs.org/)
+- **pnpm** 9+ - Install: `npm install -g pnpm`
+- **Git** - [Download](https://git-scm.com/)
+
+### Installation
+
+```bash
+# Install dependencies
+pnpm install
+
+# Set up PocketBase (see PocketBase Setup below)
+# Then start development
+pnpm run dev
+```
+
+Visit **http://localhost:8080** to see your application.
+
+---
+
+## 📁 Project Structure
+
+```
+{APP_NAME}/
+├── host/                          # Main application (Kernel)
+│   ├── src/
+│   │   ├── kernel/               # Core systems (auth, RBAC, state)
+│   │   ├── layout/               # Layout components (Sidebar, Topbar)
+│   │   ├── routes/               # Page routes
+│   │   └── providers/            # Context providers
+│   └── package.json
+│
+├── packages/
+│   └── plugins/
+│       └── @lego/
+│           ├── plugin-dashboard/  # Dashboard plugin (built-in)
+│           ├── plugin-todo/       # Todo plugin (built-in)
+│           └── plugin-*/          # Your custom plugins go here
+│
+├── pocketbase/                    # PocketBase backend
+│   ├── pb_data/                  # Database files (created on first run)
+│   └── README.md                 # PocketBase setup instructions
+│
+├── scripts/                       # Utility scripts
+│   └── create-plugin.js          # Create new plugin: pnpm run create-plugin
+│
+├── docs/                          # Documentation
+│   └── framework/                # Framework documentation for AI assistants
+│
+├── CLAUDE.md                      # AI workflow guide (for vibe coding)
+├── PROMPT.md                      # Session template (for vibe coding)
+└── README.md                      # This file
+```
+
+---
+
+## 🛠️ Development
+
+### Running the Application
+
+```bash
+# Start host and all plugins
+pnpm run dev:all
+
+# Or start individually:
+pnpm run dev:host              # Host only (:8080)
+pnpm run dev:plugins           # All plugins only
+```
+
+**Service URLs:**
+- **Host:** http://localhost:8080
+- **Dashboard Plugin:** http://localhost:3001
+- **Todo Plugin:** http://localhost:3002
+- **PocketBase Admin:** http://localhost:8090/_/
+
+### Creating a New Plugin
+
+```bash
+# Interactive plugin creation
+pnpm run create-plugin
+
+# This will:
+# 1. Prompt for plugin name
+# 2. Create plugin structure in packages/plugins/@lego/
+# 3. Register plugin in host/modern.runtime.ts
+# 4. Add to saas.config.ts
+```
+
+### Building for Production
+
+```bash
+# Build all (host + plugins)
+pnpm run build
+
+# Output: host/dist/ contains production-ready files
+```
+
+---
+
+## 🗄️ PocketBase Setup
+
+PocketBase is the backend database and API for your application.
+
+### First Time Setup
+
+1. **Download PocketBase:**
+   ```bash
+   cd pocketbase
+   
+   # Visit https://pocketbase.io/docs and download for your OS
+   # Or use the setup script:
+   # Windows: Download pocketbase.exe
+   # macOS/Linux: Download pocketbase
+   ```
+
+2. **Start PocketBase:**
+   ```bash
+   cd pocketbase
+   ./pocketbase serve
+   # Or on Windows:
+   ./pocketbase.exe serve
+   ```
+
+3. **Create Admin Account:**
+   - Visit http://localhost:8090/_/
+   - Create your admin account (first user becomes admin)
+
+4. **Import Collections (if needed):**
+   - The framework includes built-in collections for auth, organizations, etc.
+   - Check `pocketbase/pb_migrations/` for migration files
+
+### Production Setup
+
+```bash
+# Production mode
+cd pocketbase
+./pocketbase serve --prod
+```
+
+**Important:** Change default admin credentials in production!
+
+---
+
+## 📚 Documentation
+
+### For Development
+
+- **[Framework Structure](./docs/framework/setup/01-framework-structure.md)** - Architecture overview
+- **[Plugin Development](./docs/framework/setup/07-plugin-development.md)** - Creating custom plugins
+- **[Hooks API](./docs/framework/setup/11-hooks-api.md)** - Available kernel hooks
+- **[Components API](./docs/framework/setup/12-components-api.md)** - UI component library
+
+### For AI-Assisted Development (Vibe Coding)
+
+- **[CLAUDE.md](./CLAUDE.md)** - Complete AI workflow guide
+- **[PROMPT.md](./PROMPT.md)** - Session template for AI assistants
+- **[Documentation Index](./docs/framework/setup/00-index.md)** - Complete documentation index
+
+**How to use:**
+1. Read `CLAUDE.md` to understand the framework architecture
+2. Use `PROMPT.md` template for each development session
+3. AI assistants will read documentation automatically
+
+---
+
+## 🔌 Built-in Plugins
+
+### Dashboard (`@lego/plugin-dashboard`)
+- Organization statistics
+- Recent activity feed
+- Quick actions
+- **Route:** `/dashboard`
+
+### Todo (`@lego/plugin-todo`)
+- Full CRUD operations
+- Priority levels
+- Due dates
+- Multi-tenancy support
+- **Route:** `/todos`
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+pnpm test
+
+# Unit and component tests
+pnpm --filter './host' test
+
+# E2E tests (requires dev server)
+pnpm test:e2e
+
+# Type checking
+pnpm run typecheck
+```
+
+---
+
+## 🚢 Deployment
+
+### Docker Deployment
+
+```bash
+# Build Docker image
+docker build -t {APP_NAME} .
+
+# Run with Docker Compose
+docker-compose up -d
+```
+
+### Environment Variables
+
+Copy `.env.example` to `.env` and configure:
+
+```env
+# PocketBase
+POCKETBASE_URL=http://localhost:8090
+
+# Application
+NODE_ENV=production
+```
+
+---
+
+## 🔄 Updating Framework
+
+Update your application with the latest framework changes:
+
+```bash
+# Update framework files (preserves your custom code)
+npx create-lego-one@latest update
+
+# Dry run to preview changes
+npx create-lego-one@latest update --dry-run
+```
+
+**What gets updated:**
+- ✅ New plugins (added without overwriting yours)
+- ✅ Kernel improvements (preserves your customizations)
+- ✅ Dependencies (merged with your custom scripts)
+- ❌ Your plugins (never overwritten)
+- ❌ Your configs (`saas.config.ts`, `modern.config.ts`)
+
+---
+
+## 📝 Code Quality
+
+```bash
+# Lint code
+pnpm run lint
+
+# Fix linting issues
+pnpm run lint:fix
+
+# Format code
+pnpm run format
+
+# Check formatting
+pnpm run format:check
+```
+
+---
+
+## 🎨 Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| **Framework** | Modern.js with Rspack |
+| **Micro-Frontends** | Garfish |
+| **UI** | React 18, Tailwind CSS, Radix UI |
+| **State** | Zustand + TanStack Query v5 |
+| **Backend** | PocketBase |
+| **Language** | TypeScript (strict mode) |
+| **Testing** | Vitest + Playwright |
+
+---
+
+## 🤝 Contributing
+
+This is your application! Customize it as needed:
+
+1. **Create plugins** - Add features as plugins in `packages/plugins/@lego/`
+2. **Customize kernel** - Modify `host/src/kernel/` for core changes
+3. **Add routes** - Add pages in `host/src/routes/`
+4. **Extend UI** - Use or customize components in `host/src/kernel/components/`
+
+---
+
+## 📖 Learn More
+
+- **[Lego-One Framework](https://github.com/your-org/lego-one)** - Framework repository
+- **[Modern.js Docs](https://modernjs.dev/)** - Framework documentation
+- **[PocketBase Docs](https://pocketbase.io/docs)** - Backend documentation
+- **[Garfish Docs](https://www.garfishjs.org/)** - Micro-frontend engine
+
+---
+
+## 🆘 Support
+
+- **Documentation:** Check `docs/` directory
+- **Issues:** [GitHub Issues](https://github.com/your-org/lego-one/issues)
+- **Discord:** [Community Chat](https://discord.gg/lego-one)
+
+---
+
+## 📄 License
+
+MIT License - See [LICENSE](./LICENSE) for details.
+
+---
+
+**Happy Coding! 🎉**

package/template/docker-compose.yml

@@ -0,0 +1,48 @@
+version: '3.8'
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "80:80"
+      - "8090:8090"
+    environment:
+      - VITE_POCKETBASE_URL=http://localhost:8090
+      - VITE_APP_NAME=Lego-One
+      - VITE_APP_URL=http://localhost
+      - VITE_PLUGINS_ENABLED=true
+      - VITE_ENABLE_DEVTOOLS=false
+    volumes:
+      - pb_data:/data/pb
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:80"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # Optional: Add PostgreSQL for production instead of SQLite
+  # postgres:
+  #   image: postgres:15-alpine
+  #   environment:
+  #     POSTGRES_DB: legoone
+  #     POSTGRES_USER: legoone
+  #     POSTGRES_PASSWORD: changeme
+  #   volumes:
+  #     - postgres_data:/var/lib/postgresql/data
+  #   restart: unless-stopped
+
+  # Optional: Redis for caching/sessions
+  # redis:
+  #   image: redis:7-alpine
+  #   volumes:
+  #     - redis_data:/data
+  #   restart: unless-stopped
+
+volumes:
+  pb_data:
+  # postgres_data:
+  # redis_data:

package/template/docker-entrypoint.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+set -e
+
+# Start PocketBase in background
+echo "Starting PocketBase..."
+/usr/local/bin/pocketbase serve --dir=/data/pb > /var/log/pocketbase.log 2>&1 &
+
+# Wait for PocketBase to be ready
+echo "Waiting for PocketBase to start..."
+sleep 5
+
+# Check if PocketBase is running
+if ! pgrep -f "pocketbase serve" > /dev/null; then
+    echo "ERROR: PocketBase failed to start"
+    cat /var/log/pocketbase.log
+    exit 1
+fi
+
+echo "PocketBase started successfully"
+
+# Start nginx in foreground
+echo "Starting nginx..."
+nginx -g 'daemon off;'

package/template/docs/checkpoints/.template.md

@@ -0,0 +1,64 @@
+# Checkpoint: [Title]
+
+**Type:** [Bugfix / Feature / Enhancement]
+**Date:** [YYYY-MM-DD]
+**Status:** [In Progress / Completed / Blocked]
+
+## Overview
+
+[Brief description of the task, bug, or feature]
+
+## Task Definition
+
+**Original Request:**
+- [User's original request or description of the issue]
+
+**Acceptance Criteria:**
+- [ ] [Criteria 1]
+- [ ] [Criteria 2]
+- [ ] [Criteria 3]
+
+## Implementation
+
+### Files Modified
+- `path/to/file.ext` - [Description of changes]
+
+### Files Created
+- `path/to/new-file.ext` - [Description of purpose]
+
+### Implementation Steps
+1. [Step 1 description]
+2. [Step 2 description]
+3. [Step 3 description]
+
+## Testing
+
+### Test Cases
+- [ ] [Test case 1]
+- [ ] [Test case 2]
+- [ ] [Test case 3]
+
+### Test Results
+[Results of testing - what works, what doesn't]
+
+## Issues Encountered
+
+| Issue | Solution | Status |
+|-------|----------|--------|
+| [Description] | [Solution applied] | [Resolved / Ongoing] |
+
+## Notes
+
+[Additional notes, edge cases, or considerations]
+
+## Next Steps
+
+[What needs to be done next]
+
+---
+
+**Completion Checklist:**
+- [ ] Code implemented
+- [ ] Tests passing
+- [ ] Documentation updated
+- [ ] Checkpoint file complete

package/template/docs/checkpoints/framework/01-infrastructure-setup.md

@@ -0,0 +1,132 @@
+# Checkpoint: Phase 1 - Infrastructure Setup
+
+**Date:** 2026-01-23
+**Plan:** `docs/framework/plans/01-infrastructure-setup.md`
+**Status:** ✅ COMPLETED
+
+---
+
+## Files Created
+
+### Root Configuration Files
+- `package.json` - Root package.json with monorepo scripts and dev dependencies
+- `pnpm-workspace.yaml` - pnpm workspace configuration
+- `pnpm-lock.yaml` - Lock file (auto-generated)
+- `.npmrc` - npm configuration
+- `.gitignore` - Git ignore patterns
+- `tsconfig.json` - Root TypeScript configuration with project references
+- `tsconfig.base.json` - Base TypeScript configuration
+- `.eslintrc.js` - ESLint configuration
+- `.eslintignore` - ESLint ignore patterns
+- `.prettierrc` - Prettier configuration
+- `.prettierignore` - Prettier ignore patterns
+
+### Environment Configuration
+- `.env.development` - Development environment variables
+- `.env.production` - Production environment variables
+- `.env.example` - Environment variable template
+- `src/env/env.schema.ts` - Zod validation schema for environment variables
+
+### Scripts
+- `scripts/create-plugin.js` - Plugin scaffolding CLI script
+
+### Documentation
+- `README.md` - Already exists (comprehensive project documentation)
+
+---
+
+## Active State
+
+### Dependencies Installed
+- `@types/node` ^20.11.0
+- `@typescript-eslint/eslint-plugin` ^7.0.0
+- `@typescript-eslint/parser` ^7.0.0
+- `eslint` ^8.57.0
+- `eslint-config-prettier` ^9.1.0
+- `prettier` ^3.2.0
+- `prettier-plugin-tailwindcss` ^0.5.0
+- `typescript` ^5.3.0
+
+### Available Scripts
+- `pnpm run dev` - Start host application
+- `pnpm run dev:host` - Start host application
+- `pnpm run dev:plugins` - Start all plugins
+- `pnpm run dev:all` - Start host and all plugins
+- `pnpm run build` - Build all workspaces
+- `pnpm run lint` - Lint all workspaces
+- `pnpm run lint:fix` - Fix linting issues
+- `pnpm run format` - Format code with Prettier
+- `pnpm run format:check` - Check code formatting
+- `pnpm run typecheck` - Type check all workspaces
+- `pnpm run test` - Run all tests
+- `pnpm run test:e2e` - Run E2E tests
+- `pnpm run clean` - Clean build artifacts and node_modules
+- `pnpm run create-plugin` - Create a new plugin scaffold
+
+---
+
+## Pending Tasks
+
+### Next Phase: PocketBase Setup
+- **Plan File:** `docs/framework/plans/02-pocketbase-setup.md`
+- **Prerequisites:** None (Phase 1 completed)
+- **Overview:**
+  - Download and setup PocketBase
+  - Configure collections (organizations, users, roles, permissions)
+  - Set up API rules for multitenancy
+  - Create seed data script
+
+---
+
+## Verification Results
+
+### File Structure Verification
+✅ `package.json` - Created
+✅ `pnpm-workspace.yaml` - Created
+✅ `.npmrc` - Created
+✅ `.gitignore` - Created
+✅ `tsconfig.json` - Created
+✅ `tsconfig.base.json` - Created
+✅ `.eslintrc.js` - Created
+✅ `.eslintignore` - Created
+✅ `.prettierrc` - Created
+✅ `.prettierignore` - Created
+✅ `.env.development` - Created
+✅ `.env.production` - Created
+✅ `.env.example` - Created
+✅ `scripts/create-plugin.js` - Created
+✅ `src/env/env.schema.ts` - Created
+✅ `README.md` - Already exists (kept)
+
+### Dependencies Installation
+✅ All dependencies installed successfully
+✅ `node_modules` directory created
+✅ `pnpm-lock.yaml` generated
+
+### TypeScript Configuration
+✅ Base config created with strict mode enabled
+✅ Project references configured for host and plugins
+✅ Path aliases configured (@/*)
+
+### Code Quality Tools
+✅ ESLint configured with TypeScript support
+✅ Prettier configured with Tailwind plugin
+✅ Git ignore patterns configured
+
+---
+
+## Gap Analysis
+
+Against Research Documents:
+- `docs/framework/research/00-modernjs-audit.md` - Aligned with Modern.js monorepo structure
+- `docs/framework/research/01-system-blueprint.md` - Following microkernel architecture setup
+
+All planned items for Phase 1 have been implemented and verified.
+
+---
+
+## Notes
+
+- The existing README.md was more comprehensive than the plan's template, so it was preserved
+- Plugin scaffolding script uses Modern.js conventions as specified in research
+- Environment configuration uses Vite-style prefix (VITE_) for consistency with Modern.js