Files
webb/docs/superpowers/plans/2026-11-04-webb-editor-admin-suite.md
T

191 lines
13 KiB
Markdown

# WEBB Editor — Dedicated Admin Control Suite Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Build a completely independent, modern visual Admin Control Suite in `/home/creserver/Desktop/WEBB_EDITOR` running on port 3001, allowing visual live editing of the main website (`/home/creserver/Desktop/WEBB` on port 3000) — including text, media uploads, section toggles, horizontal scroll animation controls, and full tool creation (frontend UI + backend multipart API configuration) directly backed by JSON and the `management/` folder.
**Architecture:** A standalone Next.js 14 web application in `/home/creserver/Desktop/WEBB_EDITOR` with Tailwind CSS, Lucide icons, and server-side API endpoints that read and write directly to `../WEBB/management/` and `../WEBB/content/`. The main website on port 3000 has zero links, buttons, or access to the editor, ensuring complete isolation. Changes saved in the editor immediately persist to JSON on disk and reflect instantly on the main site.
**Tech Stack:** Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS, Lucide React, Node.js `fs/promises` file manipulation, Native Form-Data upload handling.
**Spec:** User request dated 2026-11-04 specifying a dedicated admin control suite in a new folder, independent on another port, with no access from the main site, supporting text editing, photo upload/removal, feature toggles, horizontal scroll animation removal/toggling, full tool creation with frontend and backend multipart/form-data configuration, and instant dynamic JSON persistence.
## Global Constraints
- **Location:** The editor project MUST live at `/home/creserver/Desktop/WEBB_EDITOR`.
- **Port:** The editor MUST run on port 3001 (or separate from main site port 3000).
- **Isolation:** The main site (`WEBB`) MUST NOT contain any admin buttons, admin links, or administrative leakage.
- **Data Source of Truth:** Edits must write directly to `management/pages/.../page.config.json`, `management/pages/.../media/`, `content/collections/tools/*.json`, `content/api.catalog.json`, and `content/site.config.json`.
- **Python Venv Rule:** If python scripts are run, always use `/home/creserver/extras/local_venv/bin/python`.
## Review Focus
1. **Path Resolution:** Relative paths to `../WEBB` must reliably resolve regardless of process working directory.
2. **File Permissions & Upload Safety:** Uploaded images must be written atomically to `../WEBB/management/.../media/` and sanitized to prevent directory traversal.
3. **JSON Schema Integrity:** Written JSON files must preserve valid JSON formatting with proper whitespace and typed schema fields.
4. **Instant Dynamic Reflection:** Main site `WEBB` on port 3000 must load updated JSON content immediately without requiring a full manual rebuild.
5. **Form-Data Backend Config:** Tool creation must support full backend specifications: API endpoint URL, HTTP method, multipart/form-data field names (e.g. `image`), parameters, and header options.
---
### Task 1: Initialize Standalone WEBB_EDITOR Project & Scaffolding
**Files:**
- Create: `/home/creserver/Desktop/WEBB_EDITOR/package.json`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/tsconfig.json`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/tailwind.config.js`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/postcss.config.js`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/next.config.js`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/globals.css`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/layout.tsx`
- [ ] Step 1.1: Create directory `/home/creserver/Desktop/WEBB_EDITOR` with Next.js 14, Tailwind CSS, Lucide React dependencies.
- [ ] Step 1.2: Configure `next.config.js` with port 3001 defaults and image domains.
- [ ] Step 1.3: Configure `tailwind.config.js` with admin studio color palette (slate/indigo/amber luxury dark/light theme).
- [ ] Step 1.4: Install dependencies using `npm install` inside `/home/creserver/Desktop/WEBB_EDITOR`.
- [ ] Step 1.5: Verify project builds with `npm run build`.
---
### Task 2: Core File System Bridge & Backend Service Library
**Files:**
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/lib/bridge.ts`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/lib/types.ts`
- Test: `/home/creserver/Desktop/WEBB_EDITOR/src/lib/bridge.test.ts`
- [ ] Step 2.1: Define TypeScript schemas for `HomePageConfig`, `ToolItem`, `ApiEndpoint`, `ShowcaseItem`, and `SectionToggle`.
- [ ] Step 2.2: Implement `getWebbPath(subpath: string)` with absolute resolution targeting `/home/creserver/Desktop/WEBB`.
- [ ] Step 2.3: Implement safe JSON reader and writer functions with backup snapshot creation.
- [ ] Step 2.4: Implement media file scanner that lists all images in `../WEBB/management/pages/home/media/` and `../WEBB/management/pages/tools/*/media/`.
- [ ] Step 2.5: Write unit tests verifying read/write integrity against test JSON structures.
---
### Task 3: API Endpoints for Pages, Sections, Media, and Tools
**Files:**
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/api/pages/home/route.ts`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/api/tools/route.ts`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/api/tools/[slug]/route.ts`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/api/media/upload/route.ts`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/api/media/delete/route.ts`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/api/sections/toggle/route.ts`
- [ ] Step 3.1: Build `GET` and `POST` for `/api/pages/home` to fetch and update `management/pages/home/page.config.json`.
- [ ] Step 3.2: Build `/api/sections/toggle` to toggle section visibility or change layout settings (e.g. toggle horizontal scroll animation vs vertical stack).
- [ ] Step 3.3: Build `POST` for `/api/media/upload` accepting `multipart/form-data` and writing files directly into `../WEBB/management/pages/.../media/`.
- [ ] Step 3.4: Build `POST` for `/api/media/delete` to safely remove unused images.
- [ ] Step 3.5: Build `GET`, `POST`, `PUT`, `DELETE` for `/api/tools` to manage `content/collections/tools/*.json` and `content/api.catalog.json`.
---
### Task 4: Admin Studio Navigation, Layout & Dashboard Overview
**Files:**
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/components/layout/AdminSidebar.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/components/layout/AdminHeader.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/page.tsx` (Dashboard Overview)
- [ ] Step 4.1: Build `AdminSidebar` with navigation links: Overview, Homepage Editor, Showcase Models, Tool Studio (Frontend + Backend), Media Asset Manager, and Settings.
- [ ] Step 4.2: Build `AdminHeader` showing live server status badge (Main Site: `http://localhost:3000` status indicator, Editor: port 3001, quick Save & Sync button).
- [ ] Step 4.3: Build Dashboard Overview page displaying active tools counter, active categories, total images managed, and quick actions.
---
### Task 5: Visual Homepage & Sections Manager (With Animation Toggles)
**Files:**
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/pages/home/page.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/components/editor/SectionCard.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/components/editor/HeroEditorModal.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/components/editor/AnimationControlsModal.tsx`
- [ ] Step 5.1: Build Section Manager list displaying all 10 homepage sections with drag/reorder and toggle switches (`enabled` / `disabled`).
- [ ] Step 5.2: Implement **Horizontal Scrolling Animation Toggle**:
- Option A: Pinned Sticky Cinematic Runway (horizontal scroll translation).
- Option B: Clean Fluid Vertical Stack (horizontal animation completely disabled).
- Option C: Completely Remove Flagship Showcase Section.
- [ ] Step 5.3: Build in-place text editor for Hero title, subtitle, badges, and trust indicators.
- [ ] Step 5.4: Implement instant save handler that writes to `../WEBB/management/pages/home/page.config.json`.
---
### Task 6: Interactive Model Showcase Manager
**Files:**
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/showcase/page.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/components/showcase/ShowcaseCardEditor.tsx`
- [ ] Step 6.1: Build visual card list for all flagship showcase models.
- [ ] Step 6.2: Add card creation and deletion controls.
- [ ] Step 6.3: Implement variant selector (`comparison` slider vs `banner`).
- [ ] Step 6.4: Add direct image uploader for Before / After / Banner images with instant thumbnail preview.
- [ ] Step 6.5: Add inputs for model name, latency chip, category, specs checklist, and tool link.
---
### Task 7: Full Tool Studio Creator (Frontend UI + Backend Multipart API)
**Files:**
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/tools/page.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/tools/new/page.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/tools/[slug]/page.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/components/tools/ToolFrontendForm.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/components/tools/ToolBackendApiForm.tsx`
- [ ] Step 7.1: Build Tool listing page showing all tools with search, category filtering, and status badges.
- [ ] Step 7.2: Build `ToolFrontendForm` for frontend presentation:
- Tool Name, Slug, Summary, Category, Associated App (`homeApp`), Badges, Limits (MB), and Sample Presets.
- Before/After demonstration image uploader that saves directly into `../WEBB/management/pages/tools/[slug]/media/`.
- [ ] Step 7.3: Build `ToolBackendApiForm` for backend execution:
- API Endpoint URL (e.g. `http://127.0.0.1:8000/api/v1/process`), HTTP Method (`POST` / `GET`).
- Multipart/form-data configuration: Upload file field name (e.g. `image` or `file`), optional fields, parameter bindings.
- Custom headers (e.g. Bearer token, API keys), timeout settings.
- [ ] Step 7.4: Build atomic save routine that writes:
- Tool JSON -> `/home/creserver/Desktop/WEBB/content/collections/tools/[slug].json`
- API Endpoint -> `/home/creserver/Desktop/WEBB/content/api.catalog.json` & `/content/api.overlay.json`
- [ ] Step 7.5: Build tool deletion routine that removes tool definitions safely.
---
### Task 8: Media Asset Manager (Visual Upload & Delete Gallery)
**Files:**
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/app/media/page.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/components/media/MediaUploadZone.tsx`
- Create: `/home/creserver/Desktop/WEBB_EDITOR/src/components/media/MediaCard.tsx`
- [ ] Step 8.1: Build visual gallery showing all media files in `../WEBB/management/`.
- [ ] Step 8.2: Implement drag-and-drop file uploader supporting JPG, PNG, WEBP, and MP4.
- [ ] Step 8.3: Add copy image path button (`/management/...`) for easy insertion into configs.
- [ ] Step 8.4: Add delete asset modal with confirmation.
---
### Task 9: Enable Dynamic Revalidation in Main Site (WEBB)
**Files:**
- Modify: `/home/creserver/Desktop/WEBB/src/app/page.tsx`
- Modify: `/home/creserver/Desktop/WEBB/src/app/tools/[slug]/page.tsx`
- [ ] Step 9.1: Add `export const dynamic = 'force-dynamic'` and `export const revalidate = 0` to `src/app/page.tsx` in `WEBB`.
- [ ] Step 9.2: Add `export const dynamic = 'force-dynamic'` and `export const revalidate = 0` to `src/app/tools/[slug]/page.tsx` in `WEBB`.
- [ ] Step 9.3: Verify that modifying `management/pages/home/page.config.json` immediately updates the live page on `http://localhost:3000` without rebuilding.
---
### Task 10: End-to-End Verification, Server Startup & Health Audit
**Files:**
- Verify: Port 3000 (`WEBB`) running without any admin links.
- Verify: Port 3001 (`WEBB_EDITOR`) running cleanly as standalone admin suite.
- Test script: `/home/creserver/Desktop/WEBB_EDITOR/tests/e2e-sync.test.ts`
- [ ] Step 10.1: Run `npm run build` inside `/home/creserver/Desktop/WEBB_EDITOR` with zero errors.
- [ ] Step 10.2: Start `WEBB_EDITOR` on port 3001 (`npm run start -- -p 3001` or daemon).
- [ ] Step 10.3: Execute test: Edit homepage badge via `WEBB_EDITOR` API / UI -> Verify updated text on `http://localhost:3000`.
- [ ] Step 10.4: Execute test: Add new tool with frontend and backend multipart config -> Verify new tool appears in `/tools` and `/tools/[slug]`.
- [ ] Step 10.5: Execute test: Upload image via Media Asset Manager -> Verify image exists in `management/` and renders on `http://localhost:3000`.
- [ ] Step 10.6: Puppeteer in-browser verification of admin suite UI and live sync confirmation.