mabdalla/bp_wb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add deployment script and sidebar integration for Super Admin

Browse source
This commit is contained in:
mmabdalla 2025-12-29 00:38:38 +02:00
parent 94ece92305
commit a8073c50e5
7 changed files with 540 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

175
docs/BOSA_SIDEBAR_INTEGRATION.md Normal file
View file

@ -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

154
docs/DEPLOYMENT.md Normal file
View file

@ -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.

176
docs/UI_TESTING_GUIDE.md Normal file
View file

@ -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

9
manifest.yaml
View file

@ -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

2
package.json
View file

@ -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",

15
sidebar.json Normal file
View file

@ -0,0 +1,15 @@
{
"sidebar": {
"links": [
{
"label": "Website Builder",
"url": "/bp_wb/",
"icon": "pencil-square",
"role": "super_admin",
"position": "after",
"after": "themes"
}
]
}
}

10
version.txt
View file

@ -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