jsgui3-server 0.0.148 → 0.0.150

package/admin-ui/v1/utils/formatters.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * Format a byte count into a human-readable string.
+ * @param {number} bytes
+ * @returns {string}
+ */
+function format_bytes(bytes) {
+    if (bytes === 0 || bytes === null || bytes === undefined) return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(Math.abs(bytes)) / Math.log(1024));
+    const index = Math.min(i, units.length - 1);
+    const value = bytes / Math.pow(1024, index);
+    return (index > 0 ? value.toFixed(1) : Math.round(value)) + ' ' + units[index];
+}
+
+/**
+ * Format seconds into a human-readable uptime string.
+ * @param {number} seconds
+ * @returns {string}
+ */
+function format_uptime(seconds) {
+    if (seconds === null || seconds === undefined || seconds < 0) return '—';
+    seconds = Math.floor(seconds);
+    if (seconds < 60) return seconds + 's';
+
+    const days = Math.floor(seconds / 86400);
+    const hours = Math.floor((seconds % 86400) / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const secs = seconds % 60;
+
+    if (days > 0) return days + 'd ' + hours + 'h';
+    if (hours > 0) return hours + 'h ' + minutes + 'm';
+    return minutes + 'm ' + secs + 's';
+}
+
+/**
+ * Format a timestamp into HH:MM:SS.
+ * @param {number} timestamp - Unix milliseconds
+ * @returns {string}
+ */
+function format_time(timestamp) {
+    if (!timestamp) return '--:--:--';
+    const d = new Date(timestamp);
+    const pad = (n) => String(n).padStart(2, '0');
+    return pad(d.getHours()) + ':' + pad(d.getMinutes()) + ':' + pad(d.getSeconds());
+}
+
+/**
+ * Format a timestamp into a relative human-readable string.
+ * @param {number} timestamp - Unix milliseconds
+ * @returns {string}
+ */
+function format_relative_time(timestamp) {
+    if (!timestamp) return '—';
+    const diff = Date.now() - timestamp;
+    if (diff < 60000) return 'just now';
+    if (diff < 3600000) return Math.floor(diff / 60000) + ' minutes ago';
+    if (diff < 86400000) return Math.floor(diff / 3600000) + ' hours ago';
+    return new Date(timestamp).toLocaleString();
+}
+
+module.exports = {
+    format_bytes,
+    format_uptime,
+    format_time,
+    format_relative_time
+};

package/dev-status.svg

@@ -0,0 +1,139 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 850" style="background:#1e1e2e; font-family: 'Segoe UI', sans-serif; color: #cdd6f4;">
+  <!-- Definitions for gradients and shadows -->
+  <defs>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="3" dy="3" stdDeviation="4" flood-color="#000000" flood-opacity="0.5"/>
+    </filter>
+    <linearGradient id="grad-server" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#313244;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#45475a;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient id="grad-client" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#181825;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#1e1e2e;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient id="grad-success" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#a6e3a1;stop-opacity:0.2" />
+      <stop offset="100%" style="stop-color:#a6e3a1;stop-opacity:0.1" />
+    </linearGradient>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto" markerUnits="strokeWidth">
+      <path d="M0,0 L0,6 L9,3 z" fill="#89b4fa" />
+    </marker>
+  </defs>
+
+  <!-- Title -->
+  <text x="50" y="50" fill="#cdd6f4" font-size="32" font-weight="bold">jsgui3-server: Dev Status & Architecture</text>
+  <text x="50" y="80" fill="#a6adc8" font-size="16">Admin UI • Auto-Observables • Defensive Programming • Server Lifecycle</text>
+
+  <!-- Areas -->
+  <rect x="50" y="110" width="500" height="700" rx="15" fill="url(#grad-server)" stroke="#585b70" stroke-width="2" />
+  <text x="70" y="140" fill="#fab387" font-size="24" font-weight="bold">Server Side (Node.js)</text>
+
+  <rect x="650" y="110" width="500" height="700" rx="15" fill="url(#grad-client)" stroke="#585b70" stroke-width="2" />
+  <text x="670" y="140" fill="#89b4fa" font-size="24" font-weight="bold">Client Side (Browser)</text>
+
+  <!-- Server Components -->
+  
+  <!-- Server Lifecycle Box -->
+  <g transform="translate(80, 180)">
+    <rect width="440" height="140" rx="8" fill="#313244" stroke="#f38ba8" stroke-width="2" stroke-dasharray="5,5" filter="url(#shadow)" />
+    <text x="15" y="30" fill="#f38ba8" font-size="18" font-weight="bold">Lifecycle Fixes</text>
+    
+    <g transform="translate(20, 50)">
+      <circle cx="10" cy="10" r="5" fill="#f38ba8" />
+      <text x="25" y="15" fill="#cdd6f4" font-size="14">1. _started Guard (Prevents double start)</text>
+    </g>
+    <g transform="translate(20, 80)">
+      <circle cx="10" cy="10" r="5" fill="#f38ba8" />
+      <text x="25" y="15" fill="#cdd6f4" font-size="14">2. Split Events: 'ready' vs 'listening'</text>
+    </g>
+     <g transform="translate(20, 110)">
+      <text x="25" y="15" fill="#a6adc8" font-size="12" font-style="italic">Fixed EADDRINUSE crash root cause</text>
+    </g>
+  </g>
+
+  <!-- Admin Module -->
+  <g transform="translate(80, 350)">
+    <rect width="200" height="120" rx="8" fill="#45475a" stroke="#89b4fa" stroke-width="2" filter="url(#shadow)" />
+    <text x="50" y="30" fill="#89b4fa" font-size="18" font-weight="bold">Admin_Module</text>
+    <line x1="10" y1="40" x2="190" y2="40" stroke="#585b70" />
+    <text x="15" y="65" fill="#cdd6f4" font-size="14">GET /api/admin/resources</text>
+    <text x="15" y="90" fill="#cdd6f4" font-size="14">GET /api/admin/observables</text>
+  </g>
+
+  <!-- Publishers -->
+  <g transform="translate(320, 350)">
+    <rect width="200" height="120" rx="8" fill="#45475a" stroke="#a6e3a1" stroke-width="2" filter="url(#shadow)" />
+    <text x="30" y="30" fill="#a6e3a1" font-size="18" font-weight="bold">Publishers</text>
+    <line x1="10" y1="40" x2="190" y2="40" stroke="#585b70" />
+    <text x="15" y="65" fill="#cdd6f4" font-size="14">HTTP_Webpage_Publisher</text>
+    <text x="15" y="90" fill="#cdd6f4" font-size="14">HTTP_Observable_Publisher</text>
+  </g>
+
+  <!-- Defensive Layers -->
+  <g transform="translate(80, 500)">
+    <rect width="440" height="100" rx="8" fill="url(#grad-success)" stroke="#a6e3a1" stroke-width="1" />
+    <text x="15" y="30" fill="#a6e3a1" font-size="18" font-weight="bold">Defensive Coding Layers</text>
+    <text x="20" y="60" fill="#cdd6f4" font-size="14">• Resource_Pool.add(undefined) → Warn & Return</text>
+    <text x="20" y="80" fill="#cdd6f4" font-size="14">• Bundler Failures → Fallback Empty Bundle</text>
+  </g>
+  
+  <!-- Bundler -->
+  <g transform="translate(80, 630)">
+    <rect width="440" height="60" rx="8" fill="#313244" stroke="#fab387" stroke-width="2" />
+    <text x="15" y="35" fill="#fab387" font-size="18" font-weight="bold">Bundler (esbuild)</text>
+    <text x="180" y="35" fill="#cdd6f4" font-size="14">Fixed: npm link jsgui3-html</text>
+  </g>
+
+
+  <!-- Client Components -->
+
+  <!-- Admin Page -->
+  <g transform="translate(680, 250)">
+    <rect width="440" height="180" rx="8" fill="#313244" stroke="#89b4fa" stroke-width="2" filter="url(#shadow)" />
+    <text x="15" y="30" fill="#89b4fa" font-size="18" font-weight="bold">Admin_Page (Client)</text>
+    <line x1="10" y1="40" x2="430" y2="40" stroke="#585b70" />
+    
+    <!-- Child Controls -->
+    <g transform="translate(20, 60)">
+      <rect width="180" height="40" rx="4" fill="#45475a" stroke="#cba6f7" stroke-width="1" />
+      <text x="35" y="25" fill="#cba6f7" font-size="14">Resource_List</text>
+    </g>
+    
+    <g transform="translate(220, 60)">
+      <rect width="180" height="40" rx="4" fill="#45475a" stroke="#cba6f7" stroke-width="1" />
+      <text x="25" y="25" fill="#cba6f7" font-size="14">Observables_List</text>
+    </g>
+    
+    <g transform="translate(120, 120)">
+      <rect width="200" height="40" rx="4" fill="#45475a" stroke="#f9e2af" stroke-width="1" />
+      <text x="30" y="25" fill="#f9e2af" font-size="14">Auto_Observable_UI</text>
+    </g>
+  </g>
+
+  <!-- Data Flow Arrows -->
+  
+  <!-- Route Info -->
+  <path d="M 280 410 L 680 300" stroke="#89b4fa" stroke-width="2" stroke-dasharray="5,5" fill="none" marker-end="url(#arrow)" />
+  <rect x="420" y="330" width="120" height="25" rx="4" fill="#1e1e2e" stroke="#89b4fa" />
+  <text x="430" y="347" fill="#89b4fa" font-size="12">JSON Data</text>
+
+  <!-- Observable Stream -->
+  <path d="M 430 470 L 800 390" stroke="#a6e3a1" stroke-width="2" fill="none" marker-end="url(#arrow)" />
+  <rect x="560" y="440" width="100" height="25" rx="4" fill="#1e1e2e" stroke="#a6e3a1" />
+  <text x="575" y="457" fill="#a6e3a1" font-size="12">SSE Steam</text>
+
+  <!-- Legend -->
+  <g transform="translate(900, 750)">
+    <text x="0" y="0" fill="#a6adc8" font-size="14" font-weight="bold">Legend</text>
+    <rect x="0" y="10" width="15" height="15" fill="#313244" stroke="#f38ba8" />
+    <text x="25" y="23" fill="#cdd6f4" font-size="12">Lifecycle Code</text>
+    
+    <rect x="0" y="35" width="15" height="15" fill="#313244" stroke="#89b4fa" />
+    <text x="25" y="48" fill="#cdd6f4" font-size="12">UI / Route Component</text>
+    
+    <rect x="0" y="60" width="15" height="15" fill="#313244" stroke="#a6e3a1" />
+    <text x="25" y="73" fill="#cdd6f4" font-size="12">Observable / Defensive</text>
+  </g>
+
+</svg>

package/docs/admin-extension-guide.md

@@ -0,0 +1,345 @@
+# Admin UI Extension Guide
+
+## Overview
+
+The jsgui3-server admin dashboard (`/admin/v1`) is fully extensible. You can:
+
+1. **Disable** the admin UI entirely
+2. **Add custom sidebar sections** with automatic data rendering
+3. **Add custom protected API endpoints** with role-based auth
+4. **Use plugins** to bundle related admin extensions
+5. **Access admin internals** (auth service, user store, SSE channel) for advanced use
+
+All extension APIs follow snake_case naming and return `this` for chaining.
+
+---
+
+## Quick Start
+
+```javascript
+const Server = require('jsgui3-server');
+
+const server = await Server.serve(MyControl, { port: 8080 });
+
+// Add a custom section — shows up in the sidebar
+server.admin_v1.add_section({
+    id: 'my_data',
+    label: 'My Data',
+    api_path: '/api/admin/v1/my-data',
+    handler: (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify([
+            { name: 'Item A', value: 42 },
+            { name: 'Item B', value: 99 }
+        ]));
+    }
+});
+```
+
+That's it. The sidebar section appears automatically, and clicking it shows a table.
+
+---
+
+## API Reference
+
+### `admin_v1.add_section(options)`
+
+Register a custom sidebar section.
+
+| Parameter       | Type       | Required | Default        | Description |
+|----------------|-----------|----------|----------------|-------------|
+| `id`           | `string`  | Yes      | —              | Unique section identifier (snake_case) |
+| `label`        | `string`  | Yes      | —              | Human-readable sidebar label |
+| `icon`         | `string`  | No       | `null`         | Emoji or text icon prefix |
+| `api_path`     | `string`  | Yes      | —              | Data endpoint path |
+| `role`         | `string`  | No       | `'admin_read'` | Required role to view |
+| `handler`      | `Function`| No       | —              | `(req, res)` handler for the endpoint |
+
+**Returns:** `Admin_Module_V1` (chainable)
+
+If `handler` is provided, it is automatically registered as a protected endpoint at `api_path`. If omitted, you must register the endpoint separately with `add_endpoint()` or via `server.publish()`.
+
+#### Auto-Rendering Behaviour
+
+The admin shell fetches `api_path` and renders the response based on its shape:
+
+| Response Shape          | Rendered As           |
+|------------------------|-----------------------|
+| Array of objects       | Table (columns = keys)|
+| Object                 | Key-value panel       |
+| Scalar (string/number) | Plain text block      |
+| Empty array            | "No data" message     |
+
+The v1 shell builds these panels with jsgui controls (table rows, key-value rows, buttons) rather than string-based `innerHTML` rendering.
+
+#### Example: Array → Table
+
+```javascript
+// Handler returns:
+[
+    { name: 'Worker 1', status: 'running', cpu: '12%' },
+    { name: 'Worker 2', status: 'idle',    cpu: '0%' }
+]
+// Renders as a 3-column table: Name | Status | CPU
+```
+
+#### Example: Object → Key-Value
+
+```javascript
+// Handler returns:
+{ version: '2.1.0', uptime: '4h 12m', mode: 'production' }
+// Renders as Key-Value pairs
+```
+
+---
+
+### `admin_v1.add_endpoint(options)`
+
+Register a custom protected API endpoint.
+
+| Parameter  | Type       | Required | Default        | Description |
+|-----------|-----------|----------|----------------|-------------|
+| `path`    | `string`  | Yes      | —              | Route path |
+| `role`    | `string`  | No       | `'admin_read'` | Required role |
+| `handler` | `Function`| Yes      | —              | `(req, res)` handler |
+
+**Returns:** `Admin_Module_V1` (chainable)
+
+The endpoint is automatically wrapped with role-based authentication. Unauthenticated requests get 401, insufficient-role requests get 403.
+
+```javascript
+server.admin_v1.add_endpoint({
+    path: '/api/admin/v1/workers/restart',
+    role: 'admin_write',
+    handler: (req, res) => {
+        // restart logic ...
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+    }
+});
+```
+
+---
+
+### `admin_v1.use(plugin_fn)`
+
+Plugin-style extension point. The function receives the admin module instance.
+
+**Returns:** `Admin_Module_V1` (chainable)
+
+```javascript
+// my_admin_plugin.js
+function my_admin_plugin(admin) {
+    admin.add_section({
+        id: 'metrics',
+        label: 'Metrics',
+        icon: '📊',
+        api_path: '/api/admin/v1/metrics',
+        handler: (req, res) => {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ requests: 12345, errors: 2 }));
+        }
+    });
+
+    admin.add_endpoint({
+        path: '/api/admin/v1/metrics/reset',
+        role: 'admin_write',
+        handler: (req, res) => {
+            // reset metrics...
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true }));
+        }
+    });
+}
+
+module.exports = my_admin_plugin;
+
+// In your server.js:
+server.admin_v1.use(require('./my_admin_plugin'));
+```
+
+---
+
+### `admin_v1.get_custom_sections()`
+
+Returns the current list of registered custom section metadata.
+
+```javascript
+const sections = server.admin_v1.get_custom_sections();
+// [{ id: 'metrics', label: 'Metrics', icon: '📊', api_path: '/api/admin/v1/metrics' }]
+```
+
+---
+
+## Declarative Configuration
+
+Custom sections and endpoints can be declared in the `Server.serve()` options:
+
+```javascript
+Server.serve({
+    Ctrl: MyControl,
+    port: 8080,
+    admin: {
+        sections: [
+            {
+                id: 'jobs',
+                label: 'Background Jobs',
+                icon: '⚙️',
+                api_path: '/api/admin/v1/jobs',
+                handler: (req, res) => {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(get_job_status()));
+                }
+            }
+        ],
+        endpoints: [
+            {
+                path: '/api/admin/v1/jobs/trigger',
+                role: 'admin_write',
+                handler: (req, res) => {
+                    trigger_job();
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true }));
+                }
+            }
+        ]
+    }
+});
+```
+
+---
+
+## Disabling the Admin UI
+
+```javascript
+// Boolean shorthand
+Server.serve({ Ctrl: MyControl, admin: false });
+
+// Object form
+Server.serve({ Ctrl: MyControl, admin: { enabled: false } });
+
+// Constructor form
+const server = new Server({ Ctrl: MyControl, admin: false });
+```
+
+When disabled, no admin routes, SSE channel, or request instrumentation are set up. `server.admin_v1` is `null`.
+
+---
+
+## Exported Classes
+
+For advanced use cases (custom auth, subclassing, testing), the admin classes are exported:
+
+```javascript
+const Server = require('jsgui3-server');
+
+// On the Server constructor:
+const { Admin_Module_V1, Admin_Auth_Service, Admin_User_Store } = Server;
+
+// From the npm module entry:
+const jsgui = require('jsgui3-server');
+const { Admin_Module_V1, Admin_Auth_Service, Admin_User_Store } = jsgui;
+```
+
+### Admin_Module_V1
+
+The core admin adapter. Instruments the server, manages telemetry, provides APIs and SSE.
+
+**Key properties:**
+- `auth` — `Admin_Auth_Service` instance
+- `user_store` — `Admin_User_Store` instance
+
+**Key methods:**
+- `init(server)` — Attach to a server instance
+- `add_section(opts)` — Register custom sidebar section
+- `add_endpoint(opts)` — Register custom API endpoint
+- `use(plugin_fn)` — Apply a plugin function
+- `get_custom_sections()` — Get section metadata array
+- `get_status()` — Get server status snapshot
+- `get_resources_tree()` — Get resource pool tree
+- `get_routes_list()` — Get route registrations
+- `destroy()` — Cleanup heartbeat and SSE
+
+### Admin_Auth_Service
+
+Session-based authentication service.
+
+**Key methods:**
+- `is_authenticated(req)` — Check if request has a valid session
+- `has_role(req, role)` — Check if session has a specific role
+- `has_any_role(req, roles)` — Check if session has any of the given roles
+- `create_session(username, roles)` — Create a new session
+- `destroy_session(session_id)` — Remove a session
+- `handle_login(req, res)` — HTTP login handler
+- `handle_logout(req, res)` — HTTP logout handler
+- `handle_session(req, res)` — HTTP session check handler
+
+### Admin_User_Store
+
+In-memory user credential store using scrypt hashing.
+
+**Key methods:**
+- `add_user({ username, password, roles })` — Add a user (password is hashed)
+- `verify_credentials(username, password)` — Verify credentials (returns `{ valid, user }`)
+- `has_user(username)` — Check if user exists
+- `get_user(username)` — Get user record (without password hash)
+
+---
+
+## Architecture Notes
+
+### How Custom Sections Work
+
+1. **Server-side:** `add_section()` stores metadata and optionally registers an API endpoint
+2. **Client-side:** On activation, the admin shell fetches `GET /api/admin/v1/custom-sections`
+3. **Dynamic nav:** Custom sections are added to the sidebar below a separator line
+4. **Data fetch:** When clicked, the shell fetches the section's `api_path`
+5. **Auto-render:** The response is rendered as a table, key-value panel, or text
+
+On repeated metadata fetches, previously mounted custom section nav controls are removed before new ones are added. This keeps the sidebar free of duplicate custom entries.
+
+### Security Model
+
+- All custom endpoints are wrapped with role-based guards automatically
+- Unauthenticated → 401 JSON response
+- Authenticated but missing role → 403 JSON response
+- Session cookies are `httpOnly` with `SameSite=Lax`
+
+### Roles
+
+| Role           | Purpose                        |
+|---------------|-------------------------------|
+| `admin_read`  | View dashboard data and sections |
+| `admin_write` | Mutating operations (start/stop/restart) |
+
+Default users get both roles. Custom user creation:
+
+```javascript
+server.admin_v1.user_store.add_user({
+    username: 'viewer',
+    password: 'readonly123',
+    roles: ['admin_read']
+});
+```
+
+---
+
+## Chaining Example
+
+```javascript
+server.admin_v1
+    .add_section({ id: 'workers',  label: 'Workers',  api_path: '/api/admin/v1/workers', handler: workers_handler })
+    .add_section({ id: 'queues',   label: 'Queues',    api_path: '/api/admin/v1/queues',  handler: queues_handler })
+    .add_endpoint({ path: '/api/admin/v1/workers/scale', role: 'admin_write', handler: scale_handler })
+    .use(require('./my-monitoring-plugin'));
+```
+
+---
+
+## Verification
+
+Use the Admin UI interaction regression suite after extension changes that affect shell behavior:
+
+```bash
+node tests/test-runner.js --test=admin-ui-jsgui-controls.test.js
+```