alchemy-chimera 1.3.0-alpha.4 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 1.3.0 (2026-01-21)
+
+* Add `addRowAction()` to ChimeraConfig for model-defined row actions
+* Fix WebSocket compatibility in ChimeraController (skip theme/beforeAction for WS connections)
+* Add live task monitoring UI with WebSocket support
+* Add "Monitor" button to TaskHistory index and edit pages
+* Add widgets to dashboard
+* Move `setToolbarManagerVariable()` call to end of actions (after document context setup) to ensure proper serialization of document watcher state
+* Fix `setToolbarManagerVariable()` to clear document watcher synchronously for non-document actions, preventing avatar from persisting on list pages
+
 ## 1.3.0-alpha.4 (2025-07-10)
 
 * Always set a new toolbar_manager received from the server

package/CLAUDE.md

@@ -0,0 +1,297 @@
+# Alchemy Chimera Development Guide
+
+## Overview
+
+Chimera is the admin/CMS interface plugin for AlchemyMVC. It provides a complete backend administration interface for managing application data models with CRUD operations, live task monitoring, and system settings management.
+
+## Commands
+- Run tests: `npm test`
+
+## Dependencies
+- alchemymvc (>=1.4.0-alpha)
+- alchemy-acl (~0.9.0-alpha) - Access control
+- alchemy-form (~0.3.0-alpha) - Form handling
+- alchemy-widget (~0.3.0-alpha) - Widget system
+- alchemy-styleboost (>=0.5.0-alpha) - SCSS framework
+
+## Directory Structure
+
+```
+controller/
+├── 00-chimera_controller.js         # Base controller
+├── chimera_editor_controller.js     # CRUD interface
+├── chimera_settings_controller.js   # Settings management
+├── chimera_static_controller.js     # Dashboard/sidebar
+└── system_task_controller.js        # Task execution/monitoring
+
+lib/
+└── chimera_config.js                # Model configuration class
+
+model/
+└── model.js                         # Adds chimera property to models
+
+element/
+├── chimera_run_task_button.js       # Task execution button
+└── chimera_task_monitor.js          # Live task progress UI
+
+view/
+├── chimera/
+│   ├── dashboard.hwk
+│   ├── sidebar.hwk
+│   ├── editor/                      # CRUD views
+│   └── settings/
+└── layouts/
+    └── chimera_*.hwk
+```
+
+## Routes
+
+All routes require `'chimera'` permission and are prefixed with `/chimera`.
+
+| Route | Method | Handler | Description |
+|-------|--------|---------|-------------|
+| `/` | GET | `Chimera.Static#dashboard` | Dashboard |
+| `/settings` | GET/POST | `Chimera.Settings#editor` | System settings |
+| `/editor/{model}/index` | GET | `Chimera.Editor#index` | List records |
+| `/editor/{model}/add` | GET/POST | `Chimera.Editor#add` | Create record |
+| `/editor/{model}/edit/{pk}` | GET/POST | `Chimera.Editor#edit` | Edit record |
+| `/editor/{model}/trash/{pk}` | GET/POST | `Chimera.Editor#trash` | Delete record |
+| `/editor/{model}/preview/{pk}` | GET | `Chimera.Editor#preview` | Preview record |
+| `/task-monitor/{task_history_id}` | GET | `Chimera.Editor#taskMonitor` | Task monitor page |
+
+### API Routes
+| Route | Method | Handler |
+|-------|--------|---------|
+| `/api/editor/{model}/records` | POST | Fetch paginated records |
+| `/api/content/sidebar` | GET | Dynamic sidebar content |
+| `/api/system/task/{id}/run` | POST | Execute system task |
+
+### WebSocket Linkups
+- `chimera@taskmonitor` - Live task monitoring
+
+## Model Configuration
+
+Every model has a static `chimera` property (ChimeraConfig instance):
+
+### Field Sets
+
+Define which fields appear in different contexts:
+
+```javascript
+// In model constitute() or after model definition
+const MyModel = Model.getClass('MyModel');
+
+// Edit form fields
+MyModel.chimera.getFieldSet('edit')
+    .add('title', {group: 'main'})
+    .add('body', {group: 'content'})
+    .add('status', {group: 'settings'});
+
+// List/table fields
+MyModel.chimera.getFieldSet('list')
+    .add('title')
+    .add('status')
+    .add('created');
+```
+
+### Field Options
+```javascript
+{
+    title: 'Field Title',      // Display name
+    purpose: 'default',        // Field purpose for form
+    mode: 'default',           // Edit mode
+    readonly: false,           // Read-only field
+    view: 'default',           // View template
+    wrapper: 'default',        // Wrapper template
+    group: 'main',             // Tab group (multiple = tabs)
+    widget_settings: {}        // Widget-specific config
+}
+```
+
+### Row Actions
+
+Add custom actions to record rows:
+
+```javascript
+MyModel.chimera.addRowAction({
+    name: 'publish',
+    icon: 'share',
+    title: 'Publish',
+    placement: ['row', 'context'],  // Where to show
+    route: 'PublishController#publish',
+    route_params: {
+        pk: '$pk',      // Auto-substituted with record primary key
+        type: 'article'
+    }
+});
+```
+
+Built-in actions: `edit`, `trash`
+
+### Record Preview
+
+```javascript
+MyModel.chimera.setRecordPreview('MyController#preview');
+```
+
+## Widget Generation
+
+Chimera auto-generates UI based on field sets:
+
+### Edit Action
+- Single group → Flat form
+- Multiple groups → Tab navigation
+- Includes save button with states (default, busy, done, error)
+
+### List Action
+- `<alchemy-table>` with pagination
+- Filter row for searching
+- Sortable columns
+- Configurable page size
+
+## Task Monitoring
+
+### Run Task Button
+```html
+<chimera-run-task-button task-id="{{task.$pk}}">
+    Run Task
+</chimera-run-task-button>
+```
+
+### Task Monitor Element
+```html
+<chimera-task-monitor task-history-id="{{history.$pk}}">
+</chimera-task-monitor>
+```
+
+Features:
+- Real-time progress via WebSocket
+- Log output with timestamps
+- Controls: Stop, Pause, Resume
+- Status display with elapsed time
+- Error handling with fallback to database state
+
+### Linkup Events
+| From Server | Description |
+|-------------|-------------|
+| `state` | Initial state |
+| `progress` | Percentage updates |
+| `report` | Log entries |
+| `complete` | Task finished |
+| `paused`, `resumed`, `stopped` | Control confirmations |
+| `error` | Error occurred |
+
+| To Server | Description |
+|-----------|-------------|
+| `stop` | Stop running task |
+| `pause` | Pause task |
+| `resume` | Resume paused task |
+
+## Records API
+
+**POST `/chimera/api/editor/{model}/records`**
+
+Request:
+```javascript
+{
+    page_size: 20,
+    page: 1,
+    fields: ['title', 'status'],
+    sort: {field: 'created', dir: 'desc'},
+    filters: {status: 'published'}
+}
+```
+
+Response:
+```javascript
+{
+    records: [{
+        // Record data
+        $hold: {
+            actions: [{name: 'edit', icon, url, placement}]
+        }
+    }]
+}
+```
+
+## Sidebar Configuration
+
+Auto-generated from models with Chimera configuration, or customize:
+
+```javascript
+alchemy.plugins.chimera.sidebar_menu = [
+    {model: 'Article'},           // Auto-generate link
+    {model: 'User'},
+    {href: '/custom', title: 'Custom Page'}
+];
+```
+
+## Plugin Configuration
+
+```javascript
+alchemy.plugins.chimera = {
+    theme: 'custom-theme',        // Custom theme name
+    title: 'My Admin',            // Window title prefix
+    sidebar_menu: [...]           // Custom sidebar (optional)
+};
+```
+
+## Controllers
+
+### ChimeraController (Base)
+- Sets theme on HTTP requests
+- Manages toolbar for document editing
+- Provides `setTitle(title)` method
+
+### ChimeraEditor
+- `index` - Record list with table
+- `add` - Create form
+- `edit` - Edit form with document watching
+- `trash` - Delete confirmation
+- `preview` - Delegates to model's preview action
+- `records` - API for fetching records
+
+### ChimeraSettings
+- `editor` - System settings form
+
+### SystemTask
+- `run` - Execute task manually
+- `monitor` - WebSocket handler for live updates
+
+## View Templates
+
+Templates use Hawkejs (`.hwk` files):
+
+- `chimera/dashboard.hwk` - Main dashboard
+- `chimera/sidebar.hwk` - Navigation
+- `chimera/editor/index.hwk` - Record list
+- `chimera/editor/add.hwk` - Create form
+- `chimera/editor/edit.hwk` - Edit form
+- `chimera/editor/trash.hwk` - Delete confirmation
+- `chimera/editor/task_monitor.hwk` - Task progress
+- `chimera/settings/editor.hwk` - Settings form
+
+## Utility
+
+```javascript
+// Convert model name to URL segment
+Plugin.modelNameToUrl('MyModel');  // 'my_model'
+```
+
+## Gotchas
+
+1. **Permission required:** All Chimera routes require `'chimera'` permission
+
+2. **Field sets:** Models need `getFieldSet('edit')` configured to appear in admin
+
+3. **has_configuration:** Models only show in sidebar if `chimera.has_configuration` is true
+
+4. **Group tabs:** Multiple groups in edit fieldset automatically creates tabbed interface
+
+5. **WebSocket skip:** Theme/beforeAction skipped for WebSocket connections
+
+6. **Document watching:** Edit page uses toolbar manager for tracking document changes
+
+7. **Private fields:** Call `record.keepPrivateFields()` to preserve sensitive data in responses
+
+8. **Row action $pk:** Use `$pk` in route_params to substitute record's primary key

package/assets/stylesheets/chimera/chimera.scss

@@ -614,6 +614,56 @@ al-field[mode="inline"] {
 			display: flex;
 			gap: 1rem;
 		}
+
+		[data-he-slot="right"] {
+			display: flex;
+			gap: 1rem;
+			align-items: center;
+		}
+
+		// Button visibility based on toolbar state
+		&[state="editing"] {
+			.start-edit {
+				display: none;
+			}
+		}
+
+		&[state="default"],
+		&[state="ready"] {
+			.stop-and-save,
+			.stop-edit,
+			.save-all,
+			chimera-dashboard-button[action="reset"] {
+				display: none;
+			}
+		}
+
+		&[state="saving"],
+		&[state="saving-before-stop"] {
+			.start-edit,
+			.stop-edit {
+				display: none;
+			}
+		}
+
+		&[state="saving"] {
+			.stop-and-save {
+				display: none;
+			}
+		}
+
+		&[state="saving-before-stop"] {
+			.save-all {
+				display: none;
+			}
+		}
+
+		// Save button styling
+		.stop-and-save,
+		.save-all {
+			--al-button-bg-color: green;
+			--al-button-bg-color-hover: rgb(55, 155, 55);
+		}
 	}
 }
 
@@ -670,4 +720,231 @@ al-table {
 			background-color: #edeff5;
 		}
 	}
+}
+
+// Task Monitor Styles
+chimera-task-monitor {
+	display: block;
+
+	.task-monitor-container {
+		background-color: white;
+		border: 1px solid var(--color-box-border, #dadee0);
+		border-radius: 4px;
+		padding: 1.5rem;
+		margin: 1rem;
+	}
+
+	.task-monitor-header {
+		display: flex;
+		justify-content: space-between;
+		align-items: flex-start;
+		margin-bottom: 1.5rem;
+		padding-bottom: 1rem;
+		border-bottom: 1px solid var(--color-box-border, #dadee0);
+	}
+
+	.task-info {
+		.task-title {
+			margin: 0 0 0.5rem 0;
+			font-size: 1.5rem;
+			color: var(--color-title, #475466);
+		}
+
+		.task-type {
+			font-size: 0.9rem;
+			color: #888;
+			font-family: monospace;
+		}
+	}
+
+	.task-meta {
+		display: flex;
+		gap: 2rem;
+		align-items: flex-start;
+
+		.meta-item {
+			display: flex;
+			flex-direction: column;
+			align-items: flex-end;
+
+			.meta-label {
+				font-size: 0.75rem;
+				color: #888;
+				text-transform: uppercase;
+				margin-bottom: 0.25rem;
+			}
+
+			.task-status {
+				font-weight: 600;
+				padding: 0.25rem 0.75rem;
+				border-radius: 4px;
+				font-size: 0.9rem;
+
+				&.status-running {
+					background-color: #cff4fc;
+					color: #055160;
+				}
+
+				&.status-paused {
+					background-color: #fff3cd;
+					color: #664d03;
+				}
+
+				&.status-completed {
+					background-color: #d1e7dd;
+					color: #0f5132;
+				}
+
+				&.status-error {
+					background-color: #f8d7da;
+					color: #842029;
+				}
+
+				&.status-pending {
+					background-color: #e2e3e5;
+					color: #41464b;
+				}
+			}
+
+			.elapsed-time,
+			.progress-text {
+				font-size: 1.1rem;
+				font-weight: 600;
+				font-family: monospace;
+			}
+		}
+	}
+
+	.task-error {
+		background-color: #f8d7da;
+		color: #842029;
+		border: 1px solid #f5c2c7;
+		padding: 1rem;
+		border-radius: 4px;
+		margin-bottom: 1rem;
+	}
+
+	.progress-container {
+		margin-bottom: 1.5rem;
+
+		.progress-track {
+			height: 8px;
+			background-color: #e9ecef;
+			border-radius: 4px;
+			overflow: hidden;
+
+			.progress-bar {
+				height: 100%;
+				background-color: var(--color-active, #3699FF);
+				border-radius: 4px;
+				transition: width 0.3s ease;
+
+				&.complete {
+					background-color: #198754;
+				}
+
+				&.error {
+					background-color: #dc3545;
+				}
+			}
+		}
+	}
+
+	.task-controls {
+		display: flex;
+		gap: 1rem;
+		margin-bottom: 1.5rem;
+
+		.btn-danger {
+			--context-color: #842029;
+			--context-background-color: #f8d7da;
+			--context-border-color: #f5c2c7;
+			@extend .danger;
+		}
+	}
+
+	.task-logs {
+		margin-bottom: 1.5rem;
+
+		.logs-title {
+			margin: 0 0 0.75rem 0;
+			font-size: 1rem;
+			color: var(--color-title, #475466);
+		}
+
+		.log-output {
+			background-color: #1e1e1e;
+			color: #d4d4d4;
+			border-radius: 4px;
+			padding: 1rem;
+			font-family: 'Consolas', 'Monaco', monospace;
+			font-size: 0.85rem;
+			line-height: 1.5;
+			min-height: 200px;
+			max-height: 400px;
+			overflow-y: auto;
+
+			.log-entry {
+				margin-bottom: 0.25rem;
+				display: flex;
+				gap: 1rem;
+
+				.log-timestamp {
+					color: #888;
+					flex-shrink: 0;
+				}
+
+				.log-content {
+					white-space: pre-wrap;
+					word-break: break-word;
+				}
+
+				&.log-success .log-content {
+					color: #4ec9b0;
+				}
+
+				&.log-error .log-content {
+					color: #f14c4c;
+				}
+
+				&.log-warning .log-content {
+					color: #cca700;
+				}
+
+				&.log-info .log-content {
+					color: #3dc9b0;
+				}
+
+				&.log-detail .log-content {
+					color: #9cdcfe;
+				}
+
+				&.log-stack .log-content {
+					font-size: 0.8rem;
+					color: #808080;
+				}
+			}
+		}
+	}
+
+	.task-timestamps {
+		display: flex;
+		gap: 2rem;
+		padding-top: 1rem;
+		border-top: 1px solid var(--color-box-border, #dadee0);
+		font-size: 0.9rem;
+
+		.timestamp-item {
+			display: flex;
+			gap: 0.5rem;
+
+			.timestamp-label {
+				color: #888;
+			}
+
+			.timestamp-value {
+				font-family: monospace;
+			}
+		}
+	}
 }

package/config/routes.js

@@ -13,6 +13,22 @@ chimera_section.add({
 	handler    : 'Chimera.Static#dashboard',
 });
 
+// Customize dashboard - create a user-specific copy
+chimera_section.add({
+	name            : 'Chimera.Static#customizeDashboard',
+	methods         : 'post',
+	paths           : '/api/dashboard/customize',
+	is_system_route : true,
+});
+
+// Reset dashboard - remove user-specific copy, revert to default
+chimera_section.add({
+	name            : 'Chimera.Static#resetDashboard',
+	methods         : 'post',
+	paths           : '/api/dashboard/reset',
+	is_system_route : true,
+});
+
 // Settings editor
 chimera_section.add({
 	name            : 'Chimera.Settings#editor',
@@ -52,6 +68,14 @@ chimera_section.add({
 	breadcrumb : 'chimera.editor.{model}.trash.{pk}'
 });
 
+// Task monitor page - shows live progress of a running task
+chimera_section.add({
+	name       : 'Chimera.Editor#taskMonitor',
+	methods    : ['get'],
+	paths      : '/task-monitor/{task_history_id}',
+	breadcrumb : 'chimera.task-monitor'
+});
+
 // Editor data action
 chimera_section.add({
 	name            : 'Chimera.Editor#records',
@@ -68,6 +92,20 @@ chimera_section.add({
 	is_system_route : true,
 });
 
+// System Task run action - starts a task manually
+chimera_section.add({
+	name            : 'Chimera.SystemTask#run',
+	paths           : '/api/system/task/{[System.Task]_id}/run',
+	methods         : ['post'],
+	is_system_route : true,
+});
+
+// Linkup route for live task monitoring via WebSocket
+// Permission is inherited from chimera_section.requirePermission('chimera')
+// Note: eventname is 'taskmonitor' (not 'chimera@taskmonitor') because the section prefix
+// is handled by the router lookup, not stored in the key
+chimera_section.linkup('Chimera.SystemTask#monitor', 'taskmonitor', 'Chimera.SystemTask#monitor');
+
 alchemy.sputnik.after('base_app', () => {
 
 	let prefixes = Prefix.all();