From a8073c50e52989e3c3c2fa21f516ac6a98fc9863 Mon Sep 17 00:00:00 2001
From: mmabdalla <101379618+mmabdalla@users.noreply.github.com>
Date: Mon, 29 Dec 2025 00:38:38 +0200
Subject: [PATCH] Add deployment script and sidebar integration for Super Admin

---
 docs/BOSA_SIDEBAR_INTEGRATION.md | 175 ++++++++++++++++++++++++++++++
 docs/DEPLOYMENT.md               | 154 +++++++++++++++++++++++++++
 docs/UI_TESTING_GUIDE.md         | 176 +++++++++++++++++++++++++++++++
 manifest.yaml                    |   9 ++
 package.json                     |   2 +
 sidebar.json                     |  15 +++
 version.txt                      |  10 +-
 7 files changed, 540 insertions(+), 1 deletion(-)
 create mode 100644 docs/BOSA_SIDEBAR_INTEGRATION.md
 create mode 100644 docs/DEPLOYMENT.md
 create mode 100644 docs/UI_TESTING_GUIDE.md
 create mode 100644 sidebar.json

diff --git a/docs/BOSA_SIDEBAR_INTEGRATION.md b/docs/BOSA_SIDEBAR_INTEGRATION.md
new file mode 100644
index 0000000..895937f
--- /dev/null
+++ b/docs/BOSA_SIDEBAR_INTEGRATION.md
@@ -0,0 +1,175 @@
+# BOSA Sidebar Integration for BP_WB
+
+This document explains how BP_WB integrates with BOSA's sidebar navigation system.
+
+## Sidebar Link Configuration
+
+BP_WB is configured to appear in the BOSA sidebar for Super Admin users only, positioned after the "Themes" link.
+
+## Configuration Files
+
+### 1. Manifest Configuration (`manifest.yaml`)
+
+The sidebar configuration is included in the app's manifest:
+
+```yaml
+sidebar:
+  label: Website Builder
+  url: /bp_wb/
+  icon: pencil-square
+  role: super_admin
+  position: after
+  after: themes
+```
+
+### 2. Sidebar JSON Configuration (`sidebar.json`)
+
+The deployment script also creates a `sidebar.json` file:
+
+```json
+{
+  "sidebar": {
+    "links": [
+      {
+        "label": "Website Builder",
+        "url": "/bp_wb/",
+        "icon": "pencil-square",
+        "role": "super_admin",
+        "position": "after",
+        "after": "themes"
+      }
+    ]
+  }
+}
+```
+
+## BOSA Core Integration Required
+
+For this sidebar link to work, BOSA's core system needs to:
+
+1. **Read sidebar configuration from apps:**
+   - Scan `apps/*/manifest.yaml` for `sidebar` configuration
+   - Or scan `apps/*/sidebar.json` files
+   - Merge app sidebar links with core sidebar links
+
+2. **Filter by role:**
+   - Only show links where `role: "super_admin"` for Super Admin users
+   - Hide links for users without required role
+
+3. **Position links correctly:**
+   - Support `position: "after"` with `after: "themes"` to place link after Themes
+   - Support `position: "before"` for placing before specific links
+   - Support `position: "append"` for adding to end of sidebar
+
+## Implementation Example (for BOSA Core)
+
+```go
+// In BOSA's sidebar rendering code
+func LoadAppSidebarLinks() []SidebarLink {
+    var links []SidebarLink
+    
+    // Scan apps directory
+    appsDir := "./apps"
+    entries, _ := os.ReadDir(appsDir)
+    
+    for _, entry := range entries {
+        if !entry.IsDir() {
+            continue
+        }
+        
+        appPath := filepath.Join(appsDir, entry.Name())
+        
+        // Try manifest.yaml first
+        manifestPath := filepath.Join(appPath, "manifest.yaml")
+        if manifest, err := LoadManifest(manifestPath); err == nil {
+            if manifest.Sidebar != nil {
+                links = append(links, manifest.Sidebar)
+            }
+        }
+        
+        // Fallback to sidebar.json
+        sidebarPath := filepath.Join(appPath, "sidebar.json")
+        if sidebar, err := LoadSidebarConfig(sidebarPath); err == nil {
+            links = append(links, sidebar.Links...)
+        }
+    }
+    
+    return links
+}
+
+func FilterSidebarLinksByRole(links []SidebarLink, userRole string) []SidebarLink {
+    var filtered []SidebarLink
+    
+    for _, link := range links {
+        // Super admin sees all links
+        if userRole == "super_admin" {
+            filtered = append(filtered, link)
+            continue
+        }
+        
+        // Filter by role requirement
+        if link.Role == "" || link.Role == userRole {
+            filtered = append(filtered, link)
+        }
+    }
+    
+    return filtered
+}
+
+func PositionSidebarLinks(coreLinks []SidebarLink, appLinks []SidebarLink) []SidebarLink {
+    // Merge and position links based on position rules
+    // Implementation depends on BOSA's sidebar structure
+}
+```
+
+## Testing the Sidebar Link
+
+1. **Deploy the app:**
+   ```powershell
+   cd D:\dev\projects\BOSA\apps
+   .\deploy_wb.bat
+   ```
+
+2. **Restart BOSA server**
+
+3. **Login as Super Admin**
+
+4. **Verify sidebar:**
+   - Check that "Website Builder" link appears
+   - Verify it's positioned after "Themes"
+   - Click the link to verify it navigates to `/bp_wb/`
+
+5. **Test role filtering:**
+   - Login as non-Super Admin user
+   - Verify "Website Builder" link does NOT appear
+
+## Icon Reference
+
+The sidebar uses the `pencil-square` icon. BOSA should support common icon libraries:
+- Heroicons (recommended)
+- Font Awesome
+- Material Icons
+
+If the icon doesn't appear, check BOSA's icon implementation and update the icon name in `manifest.yaml` or `sidebar.json`.
+
+## Troubleshooting
+
+### Link Not Appearing
+
+1. Verify BOSA core reads sidebar configuration from apps
+2. Check that `sidebar.json` or `manifest.yaml` sidebar config exists
+3. Verify you're logged in as Super Admin
+4. Check BOSA logs for sidebar loading errors
+
+### Wrong Position
+
+1. Verify `position: "after"` and `after: "themes"` are correct
+2. Check that "Themes" link exists in BOSA sidebar
+3. Verify BOSA's positioning logic handles these parameters
+
+### Icon Not Showing
+
+1. Check icon name matches BOSA's icon library
+2. Verify icon library is loaded in BOSA frontend
+3. Update icon name if needed
+
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
new file mode 100644
index 0000000..d6819f4
--- /dev/null
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,154 @@
+# BP_WB Deployment Guide
+
+This guide explains how to deploy the BP_WB Website Builder app to BOSA.
+
+## Quick Deployment
+
+Run the deployment script from the BOSA apps directory:
+
+```powershell
+cd D:\dev\projects\BOSA\apps
+.\deploy_wb.bat
+```
+
+## What the Deployment Script Does
+
+1. **Builds the frontend** - Runs `npm run build:frontend` to create production build
+2. **Copies files** to `D:\dev\projects\BOSA\apps\bp_wb\`:
+   - `manifest.yaml` - App manifest
+   - `server.js` - Node.js server entry point
+   - `package.json` - Dependencies
+   - `backend/` - Backend API code
+   - `migrations/` - Database migrations
+   - `dist/` - Built frontend (React app)
+   - `docs/` - Documentation
+   - `version.txt` - Version information
+3. **Creates sidebar configuration** - Creates `sidebar.json` for Super Admin link
+4. **Installs dependencies** - Runs `npm install --production` in target directory
+
+## Sidebar Link Configuration
+
+The app is configured to appear in the BOSA sidebar for Super Admin users only, positioned after the "Themes" link.
+
+**Configuration in `manifest.yaml`:**
+```yaml
+sidebar:
+  label: Website Builder
+  url: /bp_wb/
+  icon: pencil-square
+  role: super_admin
+  position: after
+  after: themes
+```
+
+**Configuration in `sidebar.json` (created by deployment script):**
+```json
+{
+  "sidebar": {
+    "links": [
+      {
+        "label": "Website Builder",
+        "url": "/bp_wb/",
+        "icon": "pencil-square",
+        "role": "super_admin",
+        "position": "after",
+        "after": "themes"
+      }
+    ]
+  }
+}
+```
+
+## Post-Deployment Steps
+
+1. **Restart BOSA Server:**
+   ```powershell
+   # Stop BOSA server (Ctrl+C)
+   # Then restart
+   cd D:\dev\projects\BOSA
+   bosa serve
+   ```
+
+2. **Verify Installation:**
+   - Check BOSA logs for app loading
+   - Access the app: `http://localhost:3000/bp_wb/`
+   - Verify sidebar link appears for Super Admin users
+
+3. **Check App Status:**
+   ```powershell
+   bosa ps
+   ```
+   Should show `bp_wb` in the list of running apps.
+
+## Manual Deployment
+
+If you prefer to deploy manually:
+
+1. **Build frontend:**
+   ```powershell
+   npm run build:frontend
+   ```
+
+2. **Copy files to BOSA apps directory:**
+   ```powershell
+   xcopy /E /I /Y "D:\dev\projects\BOSA Plugins\wb\*" "D:\dev\projects\BOSA\apps\bp_wb\"
+   ```
+
+3. **Exclude development files:**
+   - Don't copy `node_modules/`
+   - Don't copy `.git/`
+   - Don't copy `*.test.ts` or `*.test.tsx`
+   - Don't copy development config files
+
+4. **Install dependencies:**
+   ```powershell
+   cd D:\dev\projects\BOSA\apps\bp_wb
+   npm install --production
+   ```
+
+## Troubleshooting
+
+### App Not Loading
+
+1. Check BOSA logs for errors
+2. Verify `manifest.yaml` is valid YAML
+3. Check that `server.js` exists and is executable
+4. Verify Node.js is installed and in PATH
+
+### Sidebar Link Not Appearing
+
+1. Verify you're logged in as Super Admin
+2. Check that `sidebar.json` exists in app directory
+3. Verify BOSA is reading sidebar configuration from apps
+4. Check browser console for errors
+
+### API Routes Not Working
+
+1. Verify backend server is running (check `bosa ps`)
+2. Check that BOSA SDK is properly initialized
+3. Verify database migrations have run
+4. Check BOSA logs for API errors
+
+## Production Deployment
+
+For production deployment:
+
+1. Update paths in `deploy_wb.bat` to match production paths
+2. Ensure production build is optimized:
+   ```powershell
+   npm run build
+   ```
+3. Copy to production BOSA instance
+4. Restart BOSA server
+5. Verify app is accessible
+
+## Updating the App
+
+To update an existing deployment:
+
+1. Make changes in development directory
+2. Run deployment script again (it will overwrite existing files)
+3. Restart BOSA server to load changes
+
+**Note:** For Node.js apps, you may need to restart the app process or the entire BOSA server for changes to take effect.
+
diff --git a/docs/UI_TESTING_GUIDE.md b/docs/UI_TESTING_GUIDE.md
new file mode 100644
index 0000000..261d41c
--- /dev/null
+++ b/docs/UI_TESTING_GUIDE.md
@@ -0,0 +1,176 @@
+# UI Testing Guide for BP_WB
+
+This guide explains how to test the BP_WB Website Builder UI during development.
+
+## Prerequisites
+
+- Node.js installed
+- Dependencies installed: `npm install`
+
+## Development Setup
+
+### Option 1: Run Both Servers Separately (Recommended for Development)
+
+**Terminal 1 - Backend Server:**
+```powershell
+npm run dev
+```
+This starts the Express backend server on `http://localhost:3001`
+
+**Terminal 2 - Frontend Dev Server:**
+```powershell
+npm run dev:frontend
+```
+This starts the Vite dev server on `http://localhost:5173` with hot module replacement (HMR)
+
+**Access the UI:**
+- Open your browser to: `http://localhost:5173`
+- The Vite dev server automatically proxies `/api/*` requests to the backend on port 3001
+
+### Option 2: Run Both Servers Together (Requires `concurrently`)
+
+**Install concurrently (if not already installed):**
+```powershell
+npm install --save-dev concurrently
+```
+
+**Run both servers:**
+```powershell
+npm run dev:all
+```
+
+This runs both the backend and frontend servers simultaneously.
+
+## Testing the UI
+
+### 1. Editor Interface
+
+Navigate to: `http://localhost:5173/` or `http://localhost:5173/editor`
+
+You should see:
+- **Toolbar** - Top bar with save, preview, undo/redo buttons
+- **Sidebar** - Component palette on the left
+- **Canvas** - Main editing area in the center
+- **Property Panel** - Right sidebar for editing component properties
+
+### 2. Component Palette
+
+- Click components in the left sidebar to add them to the canvas
+- Components are organized by category (Base, Layout, Forms, etc.)
+
+### 3. Drag and Drop
+
+- Drag components from the palette onto the canvas
+- Drag components within the canvas to reorder them
+- Drop zones will highlight when dragging
+
+### 4. Property Panel
+
+- Click on any component in the canvas
+- The right sidebar shows editable properties
+- Changes update in real-time on the canvas
+
+### 5. API Testing
+
+The frontend automatically proxies API requests:
+- `GET /api/pages` - List all pages
+- `POST /api/pages` - Create a new page
+- `GET /api/pages/:id` - Get a specific page
+- `PUT /api/pages/:id` - Update a page
+- `DELETE /api/pages/:id` - Delete a page
+
+### 6. Preview Mode
+
+Navigate to: `http://localhost:5173/preview/:id` (where `:id` is a page ID)
+
+This shows the rendered page as it would appear to end users.
+
+## Hot Module Replacement (HMR)
+
+The Vite dev server supports hot module replacement:
+- Changes to React components update instantly without page refresh
+- State is preserved during updates
+- Fast refresh for React components
+
+## Troubleshooting
+
+### Port Already in Use
+
+If port 3001 or 5173 is already in use:
+
+**Backend (port 3001):**
+```powershell
+$env:PLUGIN_PORT=3002; npm run dev
+```
+
+**Frontend (port 5173):**
+Edit `vite.config.js` and change the `server.port` value.
+
+### API Requests Failing
+
+1. Ensure the backend server is running on port 3001
+2. Check the proxy configuration in `vite.config.js`
+3. Check browser console for CORS errors
+4. Verify the backend API routes are working: `curl http://localhost:3001/api/pages`
+
+### Components Not Rendering
+
+1. Check browser console for errors
+2. Verify all dependencies are installed: `npm install`
+3. Check that TypeScript compilation is successful: `npm run build`
+4. Clear browser cache and hard refresh (Ctrl+Shift+R)
+
+### Build Errors
+
+If you see TypeScript or build errors:
+```powershell
+# Check for TypeScript errors
+npx tsc --noEmit
+
+# Check for linting errors
+npm run lint
+```
+
+## Production Build
+
+To build for production:
+```powershell
+npm run build
+```
+
+This creates a `dist/` folder with optimized production files. The backend server (`server.js`) automatically serves these files when running in production mode.
+
+## Testing with BOSA Kernel
+
+When testing as a BOSA plugin:
+
+1. **Install the plugin in BOSA:**
+   ```bash
+   bosa plugin install ./path/to/bp_wb
+   ```
+
+2. **Access via BOSA routes:**
+   - Editor: `http://localhost:3000/bp_wb/` or `http://localhost:3000/bp_wb/editor`
+   - API: `http://localhost:3000/api/bp_wb/pages`
+
+3. **Environment Variables:**
+   BOSA automatically sets:
+   - `BOSA_KERNEL_URL` - BOSA kernel URL
+   - `PLUGIN_NAME` - Plugin name (bp_wb)
+   - `BOSA_KERNEL_TOKEN` - Plugin authentication token
+   - `PLUGIN_PORT` - Port assigned to the plugin
+
+## Browser DevTools
+
+Use browser DevTools for debugging:
+- **Console** - View logs and errors
+- **Network** - Monitor API requests
+- **React DevTools** - Inspect React component tree
+- **Elements** - Inspect DOM structure
+
+## Next Steps
+
+- See `docs/BP_WB_DEVELOPMENT_ROADMAP.md` for feature roadmap
+- See `docs/BP_WB_LINEAR_ISSUES.md` for detailed issue list
+- See `docs/DEVELOPER_GUIDE.md` for BOSA plugin development guide
+
diff --git a/manifest.yaml b/manifest.yaml
index b04bb32..1ab50a7 100644
--- a/manifest.yaml
+++ b/manifest.yaml
@@ -3,6 +3,15 @@ version: 0.1.0
 description: BOSA Plugin Website Builder - Visual drag-and-drop page builder for BOSA apps
 author: BOSA Team
 
+# Sidebar configuration for Super Admin
+sidebar:
+  label: Website Builder
+  url: /bp_wb/
+  icon: pencil-square
+  role: super_admin
+  position: after
+  after: themes
+
 runtime:
   type: nodejs
   entry: server.js
diff --git a/package.json b/package.json
index 3cf29c5..15f9798 100644
--- a/package.json
+++ b/package.json
@@ -6,6 +6,8 @@
   "type": "module",
   "scripts": {
     "dev": "node --watch server.js",
+    "dev:frontend": "vite",
+    "dev:all": "concurrently \"npm run dev\" \"npm run dev:frontend\"",
     "start": "node server.js",
     "build": "tsc && vite build",
     "build:frontend": "vite build",
diff --git a/sidebar.json b/sidebar.json
new file mode 100644
index 0000000..340dba5
--- /dev/null
+++ b/sidebar.json
@@ -0,0 +1,15 @@
+{
+  "sidebar": {
+    "links": [
+      {
+        "label": "Website Builder",
+        "url": "/bp_wb/",
+        "icon": "pencil-square",
+        "role": "super_admin",
+        "position": "after",
+        "after": "themes"
+      }
+    ]
+  }
+}
+
diff --git a/version.txt b/version.txt
index fafb6f4..2f92291 100644
--- a/version.txt
+++ b/version.txt
@@ -1,7 +1,15 @@
-BP_WB Version 0.0.0.002
+BP_WB Version 0.0.0.003
 Date: December 21, 2025
 
 === Latest Changes ===
+- [FEATURE] Added deployment script and sidebar integration
+  - Created deploy_wb.bat script in D:\dev\projects\BOSA\apps\ for easy deployment
+  - Added sidebar configuration to manifest.yaml for Super Admin link
+  - Created sidebar.json configuration file for BOSA sidebar integration
+  - Added sidebar link positioned after "Themes" for Super Admin role only
+  - Created deployment documentation (docs/DEPLOYMENT.md)
+  - Created BOSA sidebar integration guide (docs/BOSA_SIDEBAR_INTEGRATION.md)
+  - Deployment script builds frontend, copies files, and installs dependencies
 - [FIX] Removed direct database operations - now using BOSA SDK only
   - Removed better-sqlite3 dependency from package.json
   - Updated backend/api/pages.ts to use BOSA SDK (bosa.db.query) instead of direct SQL