create-lego-one 2.0.10 → 2.0.13

package/template/docs/framework/prompts/0-boilerplate-modernjs.md

@@ -0,0 +1,151 @@
+# **Project: Lego-One (The Modern.js SaaS OS)**
+
+**Role:** You are an elite **Software Architect** specializing in the **Modern.js Ecosystem (ByteDance)**, Micro-Frontends (Garfish), and Scalable SaaS Infrastructure.
+
+**Objective:** Create a comprehensive, production-ready architectural blueprint for a modular "All-in-One" SaaS Boilerplate (internal code name: **lego-one**).
+
+**The Core Vision:** This is a **Microkernel Operating System** for SaaS. It separates **Core Infrastructure** (Kernel) from **Business Logic** (Plugins).
+
+* **The Difference:** Unlike a standard Monolith, we are using **Modern.js** to natively handle Micro-Frontends. The Kernel shouldn't just "import" components; it should load them as independent sub-apps or modules where possible, while keeping a unified developer experience.
+
+---
+
+### **1. The Tech Stack (Strict Adherence)**
+
+* **Host Framework:** **Modern.js** (Framework)
+* *Configuration:* Must use the **Rspack** bundler for performance.
+* *Mode:* Enable **Micro-Frontend (MFE)** mode natively.
+
+
+* **Micro-Frontend Engine:** **Garfish** (Built-in to Modern.js).
+* **Language:** TypeScript (Strict Mode).
+* **Backend/Database:** PocketBase.
+* *Constraint:* Use PocketBase **API Rules** for strict Multi-tenancy (Row Level Security).
+
+
+* **State Management:**
+* **Global UI:** Zustand (Shared across Host and Plugins).
+* **Server State:** TanStack Query v5.
+
+
+* **UI System:** Tailwind CSS, Shadcn UI, Radix Primitives.
+* *Note:* Since Shadcn is optimized for Next.js, you must document the specific `postcss`/`tailwind.config.js` setup required to make it work seamlessly in Modern.js.
+
+
+
+---
+
+### **2. Architecture & Functional Requirements**
+
+#### **A. The "Kernel" vs. "Userland" Structure**
+
+* **The Kernel (Host App):**
+* Handles Authentication (Login/Register).
+* Manages the Global Layout (Sidebar, Topbar, Toasts).
+* Loads the `saas.config.ts` to determine which Plugins to fetch.
+
+
+* **The Plugins (Sub-Apps):**
+* **Feature Plugins:** Standalone Modern.js sub-apps (e.g., "Loan Calculator"). They expose specific routes and UI components.
+* **Integration Plugins:** "Drivers" for 3rd party tools (e.g., Stripe, Snowflake).
+
+
+* **Communication:**
+* Define the **Bus System**: How does a Sub-App (Plugin) trigger a Toast in the Host App? How does the Host pass the `currentUser` object to the Sub-App?
+
+
+
+#### **B. The "Update Paradox" (Boilerplate vs. NPM)**
+
+We need to update the Core without breaking the User's custom plugins.
+
+* **Requirement:** Define the update strategy.
+* *Scenario:* A developer starts their project. Two months later, we release `lego-one v2.0` with a new Auth interface.
+* *Question:* Should `lego-one` be an **NPM Dependency** (imported by the host) or a **Git Template**?
+* *Constraint:* Favor an approach where the "Kernel" logic is abstracted as much as possible so updates are painless.
+
+
+
+#### **C. The "Migration Protocol" (PocketBase)**
+
+* **Problem:** PocketBase doesn't have standard SQL migrations for plugins.
+* **Requirement:** Design a startup protocol. When the Host App boots:
+1. It reads `saas.config.ts`.
+2. It detects enabled plugins (e.g., `@lego/plugin-inventory`).
+3. It executes a "Schema Check" against the PocketBase API to ensure the `inventory` collection exists. If not, it creates it programmatically using the Admin API.
+
+
+
+#### **D. UI Slot Injection**
+
+* **Requirement:** Plugins must be able to inject UI into the Host Layout *outside* of their own routes.
+* *Example:* The "Stripe Plugin" is active. It needs to inject a "Billing" link into the **Host's Sidebar** and a "Credit Balance" badge into the **Host's Topbar**.
+* *Task:* Explain how to achieve this using Modern.js/Garfish props or a global "Slot Registry."
+
+
+
+---
+
+### **3. UI/UX Visualization**
+
+The app functions as a "Shell". Use this reference for your planning:
+
+```mermaid
+graph TD
+    subgraph Browser_Window ["Browser Window"]
+        direction TB
+        Shell[Modern.js Host (Kernel)]
+        
+        subgraph Host_UI ["Host UI"]
+            Sidebar[Sidebar Nav]
+            TopBar[Top Bar]
+            Toasts[Sonner Toasts]
+        end
+
+        subgraph Content_Area ["Garfish Router Outlet"]
+            direction LR
+            Dashboard[Dashboard Page]
+            PluginA[Sub-App: Loan Calc]
+            PluginB[Sub-App: Inventory]
+            Settings[Admin Settings]
+        end
+    end
+
+    %% Slot Injection Logic
+    PluginA -.-> |"Injects Link"| Sidebar
+    PluginB -.-> |"Injects Badge"| TopBar
+
+    %% Routing
+    Sidebar -- "/dashboard" --> Dashboard
+    Sidebar -- "/apps/loan" --> PluginA
+
+```
+
+---
+
+### **4. Deliverables & Documentation Structure**
+
+You are required to perform deep analysis. **Do not output a single file.** Generate a comprehensive documentation set. Use the following file structure as your checklist.
+
+**Phase 0: Architecture & Research**
+
+* `docs/research/00-modernjs-audit.md`: **Validate the config.** Confirm exactly how `modern.config.ts` should be set up for the Host vs. the Sub-apps. Address how **Shared Dependencies** (React, Zustand) are handled to prevent double-loading.
+* `docs/research/01-system-blueprint.md`: The high-level diagram of the Host/Consumer relationship.
+* `docs/research/02-data-migration-protocol.md`: The technical design for the PocketBase auto-schema script.
+
+**Phase 1: Implementation Plan**
+
+* `docs/research/03-host-setup.md`: Steps to initialize the Modern.js Host App with Tailwind/Shadcn.
+* `docs/research/04-plugin-architecture.md`: How to create a "Hello World" plugin and register it in the Host.
+* `docs/research/05-slot-injection-pattern.md`: The code pattern for allowing plugins to inject items into the Sidebar/Topbar.
+
+**Phase 2: DevOps**
+
+* `docs/research/06-cli-strategy.md`: How the `pnpm create` command works.
+* `docs/research/07-deployment.md`: How to deploy the Host and Sub-apps (Monorepo vs Polyrepo strategy).
+
+**Instructions for the Output:**
+
+1. **Start with `docs/research/00-modernjs-audit.md**`. I need to see the `modern.config.ts` strategy first.
+2. Be technical. Use specific API names (e.g., `garfish.loadApp`, `runtime.useModule`).
+3. Solve the **Sharing Problem**: How do we share `zustand` state between the Host and the Micro-frontend Plugin?

package/template/docs/framework/research/00-modernjs-audit.md

@@ -0,0 +1,488 @@
+# Modern.js Configuration Audit
+
+**Project:** Lego-One (Modern.js SaaS OS)
+**Document:** 00 - Modern.js Configuration Strategy
+**Status:** Research Phase
+
+## Executive Summary
+
+This document validates the `modern.config.ts` configuration strategy for the Lego-One Microkernel architecture using Modern.js with Garfish micro-frontend support and Rspack bundler.
+
+---
+
+## 1. Host App Configuration (The "Kernel")
+
+### 1.1 Base Configuration
+
+**File:** `host/modern.config.ts`
+
+```typescript
+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, { appendPlugins }) => {
+      // Rspack is enabled by default in Modern.js v2+
+      return config;
+    },
+  },
+
+  // Enable file-based routing for the host kernel
+  runtime: {
+    router: true,
+  },
+
+  // Register Garfish plugin for micro-frontend capabilities
+  plugins: [appTools(), garfishPlugin()],
+});
+```
+
+### 1.2 Runtime Configuration
+
+**File:** `host/src/modern.runtime.ts`
+
+```typescript
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+// Development vs Production configuration
+const isDev = import.meta.env.MODE === 'development';
+
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [
+      {
+        name: '@lego/plugin-dashboard',
+        // Dev: Separate server │ Prod: Bundled via dynamic import
+        entry: isDev
+          ? 'http://localhost:3001'
+          : () => import('@lego/plugin-dashboard'),
+        activeWhen: '/dashboard',
+      },
+      {
+        name: '@lego/plugin-loan-calculator',
+        entry: isDev
+          ? 'http://localhost:3002'
+          : () => import('@lego/plugin-loan-calculator'),
+        activeWhen: '/apps/loan',
+      },
+      {
+        name: '@lego/plugin-inventory',
+        entry: isDev
+          ? 'http://localhost:3003'
+          : () => import('@lego/plugin-inventory'),
+        activeWhen: '/apps/inventory',
+      },
+    ],
+  },
+});
+```
+
+**Key Configuration Points:**
+- `activeWhen`: Defines the route prefix that triggers each sub-app load
+- `entry` (Development): URL to separate dev server (e.g., `http://localhost:3001`)
+- `entry` (Production): Dynamic import function - Modern.js bundles plugin into host
+- Apps are loaded dynamically based on route matching
+
+**Development Workflow:**
+```bash
+# Terminal 1: Host
+cd host && pnpm run dev  # :8080
+
+# Terminal 2: Plugin (optional, for independent development)
+cd packages/plugins/@lego/plugin-dashboard && pnpm run dev  # :3001
+```
+
+**Production:**
+```bash
+# Single build bundles everything
+pnpm run build
+
+# Deploy host/dist/ only - plugins are already bundled inside!
+```
+
+### 1.3 Shared Dependencies Configuration
+
+**File:** `host/src/bootstrap.tsx` (or in `App.tsx` / `main.tsx`)
+
+```typescript
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { create } from 'zustand';
+import Garfish from 'garfish';
+
+// Initialize Zustand store for shared global state
+export const useGlobalStore = create((set) => ({
+  currentUser: null,
+  setCurrentUser: (user) => set({ currentUser: user }),
+  theme: 'light',
+  setTheme: (theme) => set({ theme }),
+}));
+
+// Register shared dependencies via Garfish.setExternal
+// This allows sub-apps to use the same React, ReactDOM, and Zustand instances
+Garfish.setExternal({
+  react: React,
+  'react-dom': ReactDOM,
+  '@lego/kernel-state': {
+    useGlobalStore,
+  },
+});
+```
+
+**IMPORTANT:** Garfish externals configuration is handled differently in Modern.js. The `@modern-js/plugin-garfish` automatically handles shared dependencies through Modern.js's Module Federation layer. The `Garfish.setExternal` call above is for **application-level state sharing** (Zustand store), not framework dependencies.
+
+---
+
+## 2. Sub-App (Plugin) Configuration
+
+### 2.1 Base Plugin Configuration
+
+**File:** `plugins/@lego/plugin-loan-calculator/modern.config.ts`
+
+```typescript
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { garfishPlugin } from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  dev: {
+    port: 3002, // Each plugin gets its own dev port
+  },
+
+  runtime: {
+    router: true,
+  },
+
+  // CRITICAL: Mark this as a micro-frontend sub-app
+  deploy: {
+    microFrontend: true,
+  },
+
+  plugins: [appTools(), garfishPlugin()],
+});
+```
+
+### 2.2 Plugin Entry Point
+
+**File:** `plugins/@lego/plugin-loan-calculator/src/App.tsx`
+
+```typescript
+import { BrowserRouter, Routes, Route } from '@modern-js/runtime/router';
+
+// The basename prop is automatically provided by Garfish/Modern.js
+export default function PluginApp({ basename }: { basename: string }) {
+  return (
+    <BrowserRouter basename={basename}>
+      <Routes>
+        <Route index element={<LoanCalculator />} />
+        <Route path="settings" element={<CalculatorSettings />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+### 2.3 Accessing Shared State from Plugin
+
+**File:** `plugins/@lego/plugin-loan-calculator/src/components/LoanCalculator.tsx`
+
+```typescript
+import { useGarfish } from '@garfish/hooks';
+import { useCallback } from 'react';
+
+export function LoanCalculator() {
+  // Access shared state from host app
+  const { appInfo } = useGarfish();
+
+  const getGlobalState = useCallback(() => {
+    // The host app's useGlobalStore is available via Garfish's external system
+    return window.__LEGO_KERNEL_STATE__?.useGlobalStore;
+  }, []);
+
+  return (
+    <div>
+      <h1>Loan Calculator</h1>
+      {/* Plugin content */}
+    </div>
+  );
+}
+```
+
+---
+
+## 3. Shared Dependencies Strategy
+
+### 3.1 The Sharing Problem
+
+**Problem:** How do we share `zustand` state between the Host and the Micro-frontend Plugin without double-loading React?
+
+**Solution:** Modern.js + Garfish handle this through a **two-layer sharing strategy**:
+
+1. **Framework-Level Sharing (Automatic):** Modern.js's Garfish plugin automatically manages React, ReactDOM, and router sharing. No manual configuration needed.
+
+2. **Application-Level Sharing (Manual):** For business logic state (Zustand stores), use Garfish's `setExternal` API + a global window object pattern.
+
+### 3.2 Implementation: Shared State Bridge
+
+**File:** `host/src/kernel/shared-state-bridge.ts`
+
+```typescript
+import { create } from 'zustand';
+import { devtools } from 'zustand/middleware';
+
+// Define the shape of shared state
+interface GlobalKernelState {
+  // User info
+  currentUser: { id: string; email: string; role: string } | null;
+
+  // UI State
+  theme: 'light' | 'dark';
+  sidebarOpen: boolean;
+
+  // Actions
+  setCurrentUser: (user: GlobalKernelState['currentUser']) => void;
+  setTheme: (theme: GlobalKernelState['theme']) => void;
+  toggleSidebar: () => void;
+}
+
+// Create the store
+export const useGlobalKernelState = create<GlobalKernelState>()(
+  devtools(
+    (set) => ({
+      currentUser: null,
+      theme: 'light',
+      sidebarOpen: true,
+
+      setCurrentUser: (user) => set({ currentUser: user }),
+      setTheme: (theme) => set({ theme }),
+      toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
+    }),
+    { name: 'LegoKernelState' }
+  )
+);
+
+// Export a bridge function for plugins to access the store
+export function registerSharedState() {
+  // Mount to window for plugin access
+  (window as any).__LEGO_KERNEL_STATE__ = {
+    useGlobalKernelState,
+  };
+}
+```
+
+**File:** `host/src/bootstrap.tsx` (updated)
+
+```typescript
+import { registerSharedState } from './kernel/shared-state-bridge';
+
+// Call this during host initialization
+registerSharedState();
+```
+
+### 3.3 Plugin: Accessing Shared State
+
+**File:** `plugins/@lego/plugin-loan-calculator/src/hooks/useKernelState.ts`
+
+```typescript
+import { useEffect, useState } from 'react';
+
+interface KernelState {
+  currentUser: { id: string; email: string; role: string } | null;
+  theme: 'light' | 'dark';
+  sidebarOpen: boolean;
+  setCurrentUser: (user: any) => void;
+  setTheme: (theme: 'light' | 'dark') => void;
+  toggleSidebar: () => void;
+}
+
+// Hook for plugins to access kernel state
+export function useKernelState() {
+  const [state, setState] = useState<KernelState | null>(null);
+
+  useEffect(() => {
+    // Access the shared state bridge
+    const kernelBridge = (window as any).__LEGO_KERNEL_STATE__;
+
+    if (kernelBridge?.useGlobalKernelState) {
+      // Subscribe to state changes
+      const unsubscribe = kernelBridge.useGlobalKernelState.subscribe(
+        (newState: KernelState) => {
+          setState(newState);
+        }
+      );
+
+      // Initialize with current state
+      setState(kernelBridge.useGlobalKernelState.getState());
+
+      return () => unsubscribe?.();
+    }
+  }, []);
+
+  return state;
+}
+```
+
+---
+
+## 4. Preventing Double-Loading
+
+### 4.1 Modern.js Automatic Handling
+
+The `@modern-js/plugin-garfish` automatically prevents double-loading of:
+
+- `react`
+- `react-dom`
+- `@modern-js/runtime` (includes router)
+- `react-router-dom`
+
+**No additional externals configuration needed** in Rspack/Modern.js for these packages.
+
+### 4.2 Custom Shared Dependencies
+
+For custom packages that need to be shared (like UI primitives):
+
+**Host `modern.config.ts`:**
+
+```typescript
+export default defineConfig({
+  // ... other config
+
+  source: {
+    // Define shared modules for plugins
+    alias: {
+      // Plugins will use host's Radix primitives
+      '@radix-ui/react-slot': require.resolve('@radix-ui/react-slot'),
+      '@radix-ui/react-dialog': require.resolve('@radix-ui/react-dialog'),
+    },
+  },
+});
+```
+
+**Plugin `modern.config.ts`:**
+
+```typescript
+export default defineConfig({
+  // ... other config
+
+  source: {
+    // Mark as external - will be provided by host
+    alias: {
+      '@radix-ui/react-slot': false,
+      '@radix-ui/react-dialog': false,
+    },
+  },
+});
+```
+
+---
+
+## 5. Build Configuration for Production
+
+### 5.1 Production Build (Single Server)
+
+```bash
+# From root - builds host + all plugins together
+pnpm run build
+```
+
+Expected output structure:
+```
+host/
+├── dist/
+│   ├── html/
+│   │   └── index.html
+│   ├── static/
+│   │   ├── js/
+│   │   │   ├── main-[hash].js         # Host bundle
+│   │   │   ├── vendor-[hash].js       # Shared deps (React, Zustand)
+│   │   │   └── plugins/               ← PLUGINS BUNDLED HERE
+│   │   │       ├── dashboard-[hash].js
+│   │   │       ├── loan-calc-[hash].js
+│   │   │       └── inventory-[hash].js
+│   │   ├── css/
+│   │   │   └── main-[hash].css
+│   │   └── assets/
+```
+
+**IMPORTANT:** In production, **plugins are bundled into the host's `dist/` folder**. This means:
+- Single deployment (`host/dist/` only)
+- One URL for the entire application
+- Plugins are code-split and loaded on-demand
+- No separate plugin deployments needed
+
+### 5.2 Development Build (Separate Servers)
+
+Each plugin can also build independently for development/testing:
+
+```bash
+cd plugins/@lego/plugin-loan-calculator
+pnpm run build
+```
+
+Expected output structure:
+```
+plugins/@lego/plugin-loan-calculator/
+├── dist/
+│   ├── html/
+│   │   └── index.html
+│   ├── static/
+│   │   ├── js/
+│   │   ├── css/
+│   │   └── assets/
+```
+
+**IMPORTANT:** Each plugin builds as a **standalone application** that can be:
+1. Run independently in development (at `http://localhost:3001`, etc.)
+2. Loaded dynamically by the host in development
+3. Bundled into host for production (via dynamic `import()`)
+
+---
+
+## 6. Key API Names Reference
+
+| API | Purpose | Location |
+|-----|---------|----------|
+| `garfishPlugin()` | Register Garfish MFE support | `modern.config.ts` |
+| `defineRuntimeConfig()` | Configure sub-app list | `modern.runtime.ts` |
+| `useModuleApps()` | Get loaded sub-app components | Component files |
+| `Garfish.setExternal()` | Register shared dependencies | Bootstrap files |
+| `Garfish.loadApp()` | Dynamically load a sub-app | Runtime code |
+| `Garfish.channel` | Inter-app communication bus | Runtime code |
+
+---
+
+## 7. Configuration Checklist
+
+### Host App (Kernel)
+- [ ] Register `garfishPlugin()` in `modern.config.ts`
+- [ ] Enable `runtime.router: true`
+- [ ] Configure `masterApp.apps` in `modern.runtime.ts`
+- [ ] Set up shared state bridge with `Garfish.setExternal()`
+- [ ] Create route entries (`$.tsx`) for each plugin
+- [ ] Configure shared UI primitives (Radix, Zustand)
+
+### Sub-App (Plugin)
+- [ ] Register `garfishPlugin()` in `modern.config.ts`
+- [ ] Set `deploy.microFrontend: true`
+- [ ] Configure unique `dev.port` for each plugin
+- [ ] Export component accepting `basename` prop
+- [ ] Use `@modern-js/runtime/router` with `basename`
+- [ ] Configure external dependencies matching host
+
+---
+
+## 8. Next Steps
+
+1. **`01-system-blueprint.md`**: High-level architecture diagrams
+2. **`02-data-migration-protocol.md`**: PocketBase schema synchronization
+3. **`03-host-setup.md`**: Step-by-step host initialization with Tailwind/Shadcn
+
+---
+
+## References
+
+- [Modern.js Micro Frontend Development Guide](https://modernjs.dev/guides/topic-detail/micro-frontend/c02-development)
+- [Garfish.setExternal API Documentation](https://www.garfishjs.org/api/setExternal.html)
+- [Rspack Module Federation Guide](https://rspack.rs/guide/features/module-federation)
+- [Garfish GitHub Repository](https://github.com/web-infra-dev/garfish)