webui-page-builder

# WebUI Page Builder When the user wants to create **WebUI page plugins** (shown in the WebUI left navigation under **Home**), first explain the feature clearly, then guide them through creation and development. ## Core Principles - **Language**: Detect the user's language from their messages or UI locale. Conduct the **entire conversation in the user's language** (Chinese or English). Do not switch languages mid-session. - **Admin-required notice**: Creating, editing, hiding, deleting, importing, or exporting WebUI pages requires administrator privileges. Before starting any write workflow, remind the user that the operation must be performed by an admin. This skill does **not** verify the user's role; WebUI visibility and backend APIs enforce authorization. - **Explain before acting**: If the user only asks what the feature is, explain fully before creating anything. - **Confirm once**: Before creating, confirm `pageId` (lowercase English + hyphens), `title` (navigation label in the user's language), and optional `icon` (Lucide icon name). - **WebUI plugin space only**: Read and write only under `~/.flocks/plugins/contracts/webui/`. - **Final location check**: After finishing any page development, verify that all WebUI page files are stored under `~/.flocks/plugins/contracts/webui/<pageId>/`. They must **not** remain in the project code directories such as `webui/`, `flocks/`, `tests/`, or `docs/`. - **SDK only**: Page code may import only `react` and `@flocks/webui-contract-sdk` (`Card`, `api`, `useCurrentUser`). - **Never write `dist/`**: Build artifacts are generated automatically. - **Auth-aware**: All `/api/contracts/webui/pages/*` routes require authentication. Prefer **direct file writes** for Rex; use API Token only when calling HTTP from non-browser clients. Never embed tokens in page source. - **Page-scoped backend**: When built-in `/api/*` is insufficient, use the WebUI Page Backend API Runtime design: page APIs live under the page directory and are exposed only at `/api/contracts/webui/pages/<pageId>/api/*`. ## Authentication Flocks protects **all HTTP API paths by default** (including `/api/contracts/webui/pages/*`). Only bootstrap, static assets, and a few public endpoints are exempt. Understand who needs what credential: ### WebUI (browser) - User must be **logged in** (session cookie `flocks_session`). - The WebUI axios client sends cookies automatically (`withCredentials: true`). - Navigation, page host, bundle loading, and in-page `api` calls all reuse this session — **no extra token setup** for end users. - If the user is not logged in or the session expired, WebUI pages and related APIs return **401**. ### Rex / Agent (recommended: file writes, no HTTP auth) When creating or editing pages, first remind the user that the operation requires admin privileges, then **write files directly** under `~/.flocks/plugins/contracts/webui/<pageId>/`: - No HTTP request → no API Token needed. - The file watcher detects changes, rebuilds, and publishes SSE events automatically. - This is the **preferred path** for Rex in chat sessions. - This skill does not perform role verification; WebUI and backend API paths are responsible for enforcing admin-only management. ### Rex / Agent (optional: HTTP API) Use the REST API only when file-editing access is unavailable or you need an explicit build trigger. Page management APIs require admin privileges. `curl`, Python `httpx`/`requests`, and other **non-browser** clients **must** carry an API Token — even on `127.0.0.1`. **Token location**: `~/.flocks/config/.secret.json`, secret id `server_api_token`. **Generate or rotate** (on the Flocks server): ```bash flocks admin generate-api-token ``` **Configure on a remote client** (same token value): ```bash flocks admin set-api-token --token <token> ``` **Read token in Python** (when Rex runs a script inside Flocks): ```python from flocks.security import get_secret_manager from flocks.server.auth import API_TOKEN_SECRET_ID token = get_secret_manager().get(API_TOKEN_SECRET_ID) ``` **Request headers** (either works): ```text Authorization: Bearer <token> X-Flocks-API-Token: <token> ``` All `curl` examples in this skill use `Authorization: Bearer <token>` — substitute the real token from the secret store. Do **not** ask the user to paste the token into chat; read it from the secret file or use file writes instead. API Token authenticates as a synthetic **admin service identity** (`api-token-service`). It is for automation, not for end-user page rendering. ### WebUI contract page code (`@flocks/webui-contract-sdk` `api`) - The SDK `api` helper is the WebUI axios client — it sends the **logged-in user's session cookie**, not an API Token. - Page code may call other `/api/*` endpoints (alerts, sessions, etc.) while the user is logged in. - **Never** hardcode `server_api_token` or any secret inside `src/Page.tsx` or other page source; tokens would be exposed in the bundle. ### Explain to users (first reply / when asked) **Chinese example**: > WebUI 契约页面相关接口都需要登录鉴权。普通用户可以查看和使用已发布页面，但创建、修改、隐藏、删除、导入或导出页面需要管理员权限。我（Rex）在开始这类写操作前会提醒需要管理员操作，通常直接读写 `~/.flocks/plugins/contracts/webui/` 目录，不经过 HTTP。若用脚本调管理 API，需在服务端配置 `server_api_token` 并在请求头携带 Bearer Token。 **English example**: > WebUI page APIs require authentication. Regular users can view and use published pages, but creating, editing, hiding, deleting, importing, or exporting pages requires admin privileges. I (Rex) remind the user before starting these write operations and usually read/write `~/.flocks/plugins/contracts/webui/` directly without HTTP. Non-browser management API clients must send a Bearer API Token from `server_api_token` in `~/.flocks/config/.secret.json`. ## First Reply Must Cover Explain these points in the user's language: 1. **What it is**: Custom React pages under the Home section of the left navigation — for alert dashboards, asset views, duty screens, etc. 2. **Where files live**: `~/.flocks/plugins/contracts/webui/<pageId>/` in the user space, **not** in the project code directory. 3. **How it appears**: After creation, a nav item shows under Home; route is `/contracts/webui/<pageId>`. 4. **How to develop**: Describe requirements in chat; you write `src/Page.tsx`; saving triggers auto-build; **no restart** required. 5. **Live updates**: Source changes rebuild automatically; open pages and navigation refresh via SSE. 6. **How to remove**: Tell the user both options below — hiding from nav (reversible) and permanently deleting the page directory. 7. **Authentication and authorization**: WebUI uses login session automatically. Regular users can use published pages. Creating/modifying pages requires admin privileges; Rex should remind the user before write operations but does not verify roles in this skill; scripts calling management APIs need `server_api_token` (see **Authentication** above). 8. **Data sources**: Built-in `/api/*` endpoints, page-scoped backend APIs (`/api/contracts/webui/pages/<pageId>/api/*`), or workflows (`/api/workflow/{id}/run`) (see **Backend Data & API Extension** below). 9. **Backup + restart/upgrade continuity**: Back up the full page directory and explain that Flocks scans/rebuilds pages from `~/.flocks/plugins/contracts/webui/` after restart or upgrade. Then ask whether the user already has a page idea. If they have an idea, remind them that creation requires admin privileges, then start creation. If they do not have an idea, offer 2–3 example scenarios. ## Page ID Rules - Allowed: `a-z`, `0-9`, `-` - Examples: `alert-dashboard`, `threat-overview`, `duty-screen` - Disallowed: uppercase, spaces, CJK characters, underscores ## Directory Layout ```text ~/.flocks/plugins/contracts/webui/<pageId>/ manifest.json src/index.tsx src/Page.tsx dist/page.js # auto-generated dist/meta.json # auto-generated assets/ # optional ``` ## Creation Options ### Option A — API (when HTTP is needed) Requires a valid `server_api_token` (see **Authentication**). Rex should prefer Option B unless API is explicitly required. ```bash curl -s -X POST http://127.0.0.1:8000/api/contracts/webui/pages \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -d '{"id":"alert-dashboard","title":"Alert Dashboard","icon":"BarChart3","order":100}' ``` Chinese example title: `"title":"告警看板"`. ### Option B — Write files directly (preferred for Rex) Create under `~/.flocks/plugins/contracts/webui/<pageId>/`: **manifest.json** ```json { "id": "alert-dashboard", "title": "Alert Dashboard", "route": "/contracts/webui/alert-dashboard", "icon": "BarChart3", "order": 100, "enabled": true, "placement": "home.after", "entry": "src/index.tsx", "updatedAt": 0 } ``` **src/index.tsx** ```tsx import Page from './Page'; export default Page; ``` **src/Page.tsx** — start from the template below. ## Page Template Use the manifest `title` for the card heading. Keep in-page status text in the user's language. ```tsx import { useEffect, useState } from 'react'; import { Card } from '@flocks/webui-contract-sdk'; export default function Page() { const [ready, setReady] = useState(false); useEffect(() => { setReady(true); }, []); return ( <Card title="Alert Dashboard"> {ready ? 'Ready' : 'Loading...'} </Card> ); } ``` For Chinese pages, use Chinese copy inside the component, e.g. `{ready ? '页面已就绪' : '加载中...'}`. ## Development Flow 1. After scaffold creation, tell the user the nav label, route, and directory path. 2. Identify data sources — built-in `/api/*`, page-scoped backend APIs, workflows, or external systems that need server-side proxying. 3. Edit `src/Page.tsx` based on requirements (add more files under `src/` if needed). 4. On save, the system rebuilds automatically. If build fails, read `dist/meta.json` → `error` and fix. 5. Manual rebuild: `POST /api/contracts/webui/pages/<pageId>/build` 6. Before wrapping up, run a final location check: every page file created for the user must be under `~/.flocks/plugins/contracts/webui/<pageId>/`; do not leave page source, API handlers, assets, or drafts in the repository code directories. ## Backup and Restore Always provide this backup command in the first explanation and in the final wrap-up: ```bash cp -a ~/.flocks/plugins/contracts/webui/<pageId> ~/.flocks/workspace/outputs/<today>/<pageId>-backup ``` Restore by copying the backup directory back to `~/.flocks/plugins/contracts/webui/<pageId>/`. After restart (or immediately if watcher is active), the page will be scanned and available again. ## Backend Data & API Extension When a WebUI contract page needs backend logic or external data that built-in APIs do not provide, use a **page-scoped backend API runtime**. ### Design Principle Do **not** register arbitrary global FastAPI routes such as `/api/my-dashboard/stats`. The page backend should be scoped to the page namespace: ```text /api/contracts/webui/pages/<pageId>/api/{path:path} ``` This keeps page APIs tied to page lifecycle, permissions, logs, hot reload, deletion, and future UI management. ### Architecture ```text WebUI Page (src/Page.tsx) └─ SDK api ──► /api/contracts/webui/pages/<pageId>/api/* (page-scoped backend) ├─► /api/workflow/{id}/run (multi-step workflows) └─► /api/* (built-in Flocks APIs) ``` ### Target Directory Layout When a page needs backend code, add an `api/` directory inside that page: ```text ~/.flocks/plugins/contracts/webui/<pageId>/ manifest.json src/Page.tsx api/ routes.yaml handlers.py dist/ page.js meta.json ``` ### Route Manifest Use `api/routes.yaml` to declare the page API surface: ```yaml routes: - method: GET path: /stats handler: handlers.get_stats timeoutMs: 5000 - method: POST path: /ack handler: handlers.ack_alert timeoutMs: 10000 ``` Rules: - `path` must start with `/` and is always scoped under `/api/contracts/webui/pages/<pageId>/api`. - `handler` points to a callable in `api/handlers.py`. - Keep route count small and page-specific. - Prefer read-only `GET` for dashboards; use `POST` for actions. - Do not expose global admin operations from page APIs. ### Handler Code Use `api/handlers.py` for server-side page logic: ```python async def get_stats(ctx, request): # ctx exposes trusted server-side helpers such as: # ctx.user, ctx.page_id, ctx.secrets, ctx.logger return { "open": 12, "critical": 3, } async def ack_alert(ctx, request): body = await request.json() alert_id = body.get("id") if not alert_id: return {"ok": False, "error": "missing alert id"} return {"ok": True, "id": alert_id} ``` Implementation expectations for the runtime: - Route module loading is controlled by Flocks, not by arbitrary `include_router`. - Handlers run as trusted local plugins, not as a security sandbox. - Runtime enforces auth, page ID validation, route validation, request/response size limits, timeout, and structured error reporting. - Secrets are read server-side through `ctx.secrets` or `get_secret_manager()`; never return secrets to the page. - Watcher should monitor `api/routes.yaml` and `api/*.py`; API changes should hot-reload without restarting Flocks. - API runtime errors should be visible in page diagnostics (for example `dist/meta.json` or a dedicated API meta file). ### Call from Page Code The SDK `api` helper sends the logged-in user's session cookie: ```tsx const res = await api.page.get('/stats'); ``` For data access contracts, use the contract helper instead of hand-writing operation URLs: ```tsx const res = await api .contract('soc/alerts', 'soc.alerts.operations') .operation('list', { params: { limit: 100 } });