create-lego-one 2.0.12 → 2.0.13

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

@@ -0,0 +1,282 @@
+# Lego-One Research Documentation
+
+**Project:** Lego-One (Modern.js SaaS OS)
+**Status:** Research & Implementation Complete
+
+## Overview
+
+This directory contains comprehensive architectural research for building a **Microkernel SaaS Boilerplate** using Modern.js, Garfish (micro-frontends), PocketBase, and modern React tooling.
+
+---
+
+## Document Index
+
+### Phase 0: Architecture & Research
+
+| Document | Description | Status |
+|----------|-------------|--------|
+| [`00-modernjs-audit.md`](./00-modernjs-audit.md) | Modern.js + Garfish configuration, shared dependencies, externals | ✅ |
+| [`01-system-blueprint.md`](./01-system-blueprint.md) | High-level Host/Consumer architecture, communication patterns | ✅ |
+| [`02-data-migration-protocol.md`](./02-data-migration-protocol.md) | PocketBase auto-schema synchronization on startup | ✅ |
+
+### Phase 1: Implementation Plan
+
+| Document | Description | Status |
+|----------|-------------|--------|
+| [`03-host-setup.md`](./03-host-setup.md) | Initialize Modern.js host with Tailwind + Shadcn UI | ✅ |
+| [`04-plugin-architecture.md`](./04-plugin-architecture.md) | Create "Hello World" plugin and register with host | ✅ |
+| [`05-slot-injection-pattern.md`](./05-slot-injection-pattern.md) | UI extension system for plugins to inject into host layout | ✅ |
+
+### Phase 2: DevOps
+
+| Document | Description | Status |
+|----------|-------------|--------|
+| [`06-cli-strategy.md`](./06-cli-strategy.md) | `pnpm create lego-one` CLI tool implementation | ✅ |
+| [`07-deployment.md`](./07-deployment.md) | Deploy host and plugins (Monorepo vs Polyrepo) | ✅ |
+
+---
+
+## Key Architectural Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| **Framework** | Modern.js | Native Garfish support, Rspack performance |
+| **Micro-Frontends** | Garfish | Built into Modern.js, mature ecosystem |
+| **State Management** | Zustand | Lightweight, works across MFE boundaries |
+| **Backend** | PocketBase | Single binary, multi-tenancy via API Rules |
+| **Distribution** | npm CLI + Git Template | Easy project creation, user control over updates |
+| **Repo Structure** | Monorepo | Shared deps, coordinated changes, easier onboarding |
+| **Dev Deployment** | Separate servers per plugin | Independent plugin development |
+| **Prod Deployment** | Single server (plugins bundled) | One app, one deployment, simpler operations |
+| **Version Management** | Automated semantic versioning | Patch/minor/major releases with git tags |
+
+---
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|-----------|
+| **Framework** | Modern.js + Rspack |
+| **MFE Engine** | Garfish |
+| **UI** | React 18 + Tailwind CSS + Shadcn UI + Radix Primitives |
+| **State** | Zustand + TanStack Query v5 |
+| **Backend** | PocketBase |
+| **Language** | TypeScript (strict) |
+| **CLI** | Commander + Prompts + Chalk |
+| **Distribution** | npm registry |
+| **Versioning** | Automated scripts (patch/minor/major) |
+
+---
+
+## Distribution & Publishing
+
+### CLI Distribution
+
+Lego-One is distributed via npm as a create CLI:
+
+```bash
+# Create a new Lego-One application
+pnpm create lego-one my-saas-app
+
+# Or using npx
+npx create-lego-one my-saas-app
+```
+
+**CLI Package:** `create-lego-one`
+- **Location:** `packages/create-lego-one/`
+- **Entry Point:** `dist/index.js` (built from `src/index.ts`)
+- **Template:** Copied from monorepo root during CLI execution
+- **Dependencies:** prompts, commander, chalk, ora, fs-extra, validate-npm-package-name
+
+### Version Management
+
+Automated version bumping scripts:
+
+```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
+
+# Pre-release (beta/alpha)
+pnpm run version:pre
+
+# Full release workflow (build, test, version, publish, push)
+pnpm run release
+```
+
+**Script:** `scripts/version.js`
+- Updates root `package.json`
+- Updates `host/package.json`
+- Updates all plugin `package.json` files
+- Creates git tag automatically
+- Follows semantic versioning
+
+### Publishing to npm
+
+```bash
+# Build CLI package
+cd packages/create-lego-one
+pnpm run build
+
+# Publish to npm (from root)
+pnpm run publish:cli
+
+# Or manually
+cd packages/create-lego-one
+npm publish --access public
+```
+
+**Configuration:** `.npmrc`
+- `access=public` - Public scope packages
+- `provenance=true` - Cryptographic proof of publisher identity
+- `engine-strict=true` - Enforce Node.js version requirements
+
+### Update Strategy for Users
+
+Users of Lego-One can update their framework installation:
+
+```bash
+# Update Lego-One to latest version
+pnpm update lego-one
+
+# Or update create-lego-one CLI
+pnpm update create-lego-one
+
+# Or specific version
+pnpm update lego-one@latest
+```
+
+**Plugin Isolation:**
+- Custom plugins in `packages/plugins/@custom/` are never overwritten
+- Framework updates only affect `@lego/*` packages
+- Users maintain full control over custom code
+
+---
+
+## Architecture Summary
+
+### Microkernel Pattern
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     Host (Kernel)                        │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
+│  │   Auth      │  │  RBAC       │  │   State     │    │
+│  │   System    │  │  System     │  │  Management │    │
+│  └─────────────┘  └─────────────┘  └─────────────┘    │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
+│  │    UI       │  │   Channels  │  │    Slot     │    │
+│  │   Layout    │  │    Bus      │  │  Injection  │    │
+│  └─────────────┘  └─────────────┘  └─────────────┘    │
+└─────────────────────────────────────────────────────────┘
+                           │
+                           │ via Garfish + Window Bridge
+                           │
+        ┌──────────────────┼──────────────────┐
+        │                  │                  │
+┌───────▼────────┐ ┌───────▼────────┐ ┌───────▼────────┐
+│ Dashboard      │ │     Todo       │ │  Custom        │
+│ Plugin         │ │     Plugin     │ │  Plugins       │
+└────────────────┘ └────────────────┘ └────────────────┘
+```
+
+### Communication Patterns
+
+**Host → Plugin:**
+- Window bridge state (`window.__LEGO_KERNEL_STATE__`)
+- Channel bus for events (`window.__LEGO_CHANNEL_BUS__`)
+- Slot injection for UI components
+
+**Plugin → Host:**
+- Read kernel state via window bridge
+- Publish events via channel bus
+- Inject UI into predefined slots
+
+**Plugin ↔ Plugin:**
+- Via channel bus events
+- No direct dependencies
+
+---
+
+## Development Workflow
+
+### For Framework Maintainers
+
+1. **Make changes** to host, kernel, or built-in plugins
+2. **Bump version** using `pnpm run version:patch/minor/major`
+3. **Build and test** using `pnpm run build && pnpm test`
+4. **Publish CLI** using `pnpm run publish:cli`
+5. **Push to git** with tag for version tracking
+
+### For End Users
+
+1. **Create new project:** `pnpm create lego-one my-app`
+2. **Develop custom plugins** in `packages/plugins/@custom/`
+3. **Update framework:** `pnpm update lego-one` (custom plugins preserved)
+4. **Build for production:** `pnpm run build`
+5. **Deploy:** Use provided Dockerfile or custom deployment
+
+---
+
+## File Structure
+
+```
+lego-one/
+├── host/                          # Kernel application
+│   ├── src/
+│   │   ├── kernel/               # Core systems
+│   │   ├── layout/               # UI layout
+│   │   ├── routes/               # Page routes
+│   │   └── providers/            # Context providers
+│   └── package.json
+│
+├── packages/
+│   ├── plugins/
+│   │   └── @lego/
+│   │       ├── plugin-dashboard/  # Built-in plugins
+│   │       └── plugin-todo/
+│   │
+│   └── create-lego-one/           # CLI for `pnpm create`
+│       ├── src/                   # CLI source
+│       ├── template/              # (Optional) bundled template
+│       └── package.json
+│
+├── scripts/
+│   ├── version.js                # Version management
+│   └── create-plugin.js          # Plugin scaffolding
+│
+├── docs/
+│   ├── framework/                # Architecture docs
+│   ├── api/                      # API references
+│   ├── guides/                   # User guides
+│   └── checkpoints/              # Phase completion tracking
+│
+├── .npmrc                        # npm publishing config
+├── pnpm-workspace.yaml           # Monorepo config
+└── package.json                  # Root package config
+```
+
+---
+
+## Next Steps
+
+1. **Review:** Review all research documents
+2. **Setup:** Follow the setup guide in `/docs/framework/setup/README.md`
+3. **Develop:** Create custom plugins using AI instructions
+4. **Deploy:** Use the deployment guide for production
+
+---
+
+## Sources
+
+- [Modern.js Documentation](https://modernjs.dev/)
+- [Garfish Documentation](https://www.garfishjs.org/)
+- [PocketBase Documentation](https://pocketbase.io/docs/)
+- [npm Publishing](https://docs.npmjs.com/cli/v9/commands/npm-publish)
+- [Semantic Versioning](https://semver.org/)
+- [pnpm Workspaces](https://pnpm.io/workspaces)

package/template/docs/framework/setup/00-index.md

@@ -0,0 +1,210 @@
+# AI Development Documentation
+
+**Lego-One Framework - AI "Vibe Coding" Reference**
+
+> This documentation is optimized for AI agents working on the Lego-One framework. Read sequentially for complete context.
+
+---
+
+## Documentation Index
+
+Read these files in order for complete framework understanding:
+
+### Getting Started
+
+| # | File | Description |
+|---|------|-------------|
+| 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` | UI components, styling, design system *(TODO)* |
+| 09 | `09-data-integration.md` | PocketBase, multi-tenancy, data fetching *(TODO)* |
+| 10 | `10-auth-rbac.md` | Authentication, authorization, permissions *(TODO)* |
+
+### 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 |
+
+### Core Concepts (TODO)
+
+| # | File | Description |
+|---|------|-------------|
+| 04 | `04-kernel-architecture.md` | Host/Kernel system, core infrastructure |
+| 05 | `05-plugin-system.md` | Plugin architecture, Garfish, micro-frontends |
+| 06 | `06-communication-patterns.md` | Window bridge, channel bus, plugin-host communication |
+
+---
+
+## Quick Reference for AI Agents
+
+### When Starting Any Task
+
+1. **ALWAYS read `/docs/framework/setup/00-index.md` first** (this file)
+2. **Read relevant files** from the index above based on your task
+3. **Follow established patterns** - consistency is critical
+4. **Write checkpoints** for every task/bugfix/feature in `/docs/checkpoints/`
+
+### Task → Documentation Mapping
+
+| Task Type | Read First | Reference |
+|-----------|-----------|----------|
+| Create new plugin | `07-plugin-development.md` | Dashboard/Todo plugins |
+| Add UI components | `08-component-library.md` | Existing components |
+| Fix auth issues | `10-auth-rbac.md` | Kernel auth system |
+| Add data features | `09-data-integration.md` | Todo plugin patterns |
+| Debug issues | `02-development-workflow.md` | Troubleshooting section |
+
+### Critical 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 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 your work in checkpoints
+
+---
+
+## File Location Conventions
+
+```
+lego-one/
+├── host/src/kernel/          # Core systems (auth, RBAC, state, channels)
+├── host/src/layout/          # Layout components (Sidebar, Topbar, Shell)
+├── host/src/routes/          # Page routes
+├── host/src/providers/       # Context providers
+└── packages/plugins/@lego/   # Feature modules
+```
+
+### Kernel Structure
+
+```
+host/src/kernel/
+├── shared-state/     # Zustand store + window bridge
+├── providers/        # PocketBase, Query, Theme providers
+├── plugins/          # Plugin system, slot injection
+├── channels/         # Garfish channel bus
+├── auth/             # Authentication logic
+├── rbac/             # Multitenancy, permissions
+├── lib/              # Utilities (cn, formatDate)
+└── components/       # Shared UI components
+```
+
+### Plugin Structure
+
+```
+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
+```
+
+---
+
+## Key Hooks and APIs
+
+| Hook/Api | Purpose | Location |
+|----------|---------|----------|
+| `usePocketBase()` | Access PocketBase client | `host/src/kernel/providers/` |
+| `useCurrentOrganization()` | Get current organization context | `host/src/kernel/hooks/` |
+| `useUserPermissions()` | Get user permissions | `host/src/kernel/hooks/` |
+| `useGlobalKernelState()` | Access kernel state | `host/src/kernel/shared-state/` |
+| `window.__LEGO_KERNEL_STATE__` | Read-only kernel state access | Global window object |
+| `window.__LEGO_CHANNEL_BUS__` | Event publishing/subscribing | Global window object |
+
+---
+
+## 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
+# 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
+```
+
+---
+
+## Before You Code
+
+Use this 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? → Read file 09 (Data Integration)
+├─ Does it need authentication? → Read file 10 (Auth/RBAC)
+└─ 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 (file 08)
+└─ Data related? → Check hooks and PocketBase queries (file 09)
+```
+
+---
+
+**Next:** Read [`01-framework-structure.md`](./01-framework-structure.md) to understand the project layout.