ci: add notify-failure, deploy tagging, and jest coverage

- lint.yml: add notify-failure Matrix alert job; add Tag deployed commit
  step to deploy job with deploy-YYYY.MM.DD-N tagging via Gitea API
- package.json: add --coverage flag to jest test script

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.eslintrc.json

@@ -0,0 +1,13 @@
+{
+    "env": { "node": true, "es2021": true },
+    "extends": "eslint:recommended",
+    "parserOptions": { "ecmaVersion": 2021, "sourceType": "commonjs" },
+    "rules": {
+        "no-unused-vars": "warn",
+        "no-empty": "warn",
+        "no-constant-condition": "warn",
+        "no-useless-escape": "warn",
+        "semi": ["error", "always"],
+        "eqeqeq": "warn"
+    }
+}

.gitea/workflows/lint.yml

@@ -0,0 +1,71 @@
+name: Lint
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  js-lint:
+    name: JS (eslint)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install ESLint
+        run: npm install --save-dev eslint@8
+
+      - name: Run ESLint
+        run: npx eslint --ext .js .
+
+  notify-failure:
+    name: Notify on failure
+    runs-on: ubuntu-latest
+    needs: [js-lint]
+    if: failure() && github.event_name == 'push'
+    steps:
+      - name: Send Matrix alert
+        env:
+          MATRIX_WEBHOOK_URL: ${{ secrets.MATRIX_WEBHOOK_URL }}
+          REPO: ${{ github.repository }}
+          BRANCH: ${{ github.ref_name }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          if [ -z "$MATRIX_WEBHOOK_URL" ] || [ "$MATRIX_WEBHOOK_URL" = "CONFIGURE_ME" ]; then exit 0; fi
+          curl -sf -X POST "$MATRIX_WEBHOOK_URL" \
+            -H "Content-Type: application/json" \
+            -d "{\"text\":\"CI FAILED: ${REPO} @ ${BRANCH} — ${RUN_URL}\"}"
+
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    needs: [js-lint]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+    steps:
+      - name: Trigger webhook
+        env:
+          WEBHOOK_SECRET: ${{ secrets.WEBHOOK_SECRET }}
+          GIT_REF: ${{ github.ref }}
+        run: |
+          PAYLOAD="{\"ref\":\"${GIT_REF}\"}"
+          SIG=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
+          curl -sf --connect-timeout 10 \
+            -X POST \
+            -H "Content-Type: application/json" \
+            -H "X-Gitea-Signature: ${SIG}" \
+            -d "$PAYLOAD" \
+            "http://10.10.10.65:9000/hooks/pulse-deploy"
+
+      - name: Tag deployed commit
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="deploy-$(date -u +%Y.%m.%d)-${{ github.run_number }}"
+          curl -sf -X POST \
+            -H "Authorization: token $GITHUB_TOKEN" \
+            -H "Content-Type: application/json" \
+            -d "{\"tag_name\":\"${TAG}\",\"target\":\"${{ github.sha }}\",\"message\":\"Deployed to production\"}" \
+            "https://code.lotusguild.org/api/v1/repos/${{ github.repository }}/tags"

.gitea/workflows/security.yml

@@ -0,0 +1,22 @@
+name: Security
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+  schedule:
+    - cron: '0 6 * * 1'
+
+jobs:
+  npm-audit:
+    name: JS Security (npm audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run npm audit
+        run: npm audit --audit-level=high

.gitea/workflows/test.yml

@@ -0,0 +1,20 @@
+name: Test
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  jest:
+    name: JS Tests (jest)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run jest
+        run: npm test

.gitignore

@@ -30,3 +30,6 @@ Thumbs.db
 *.swp
 *.swo
 *~
+
+# Claude
+Claude.md

README.md

@@ -1,240 +1,435 @@
 # PULSE - Pipelined Unified Logic & Server Engine
 
-A distributed workflow orchestration platform for managing and executing complex multi-step operations across server clusters through an intuitive web interface.
+[![Lint](https://code.lotusguild.org/LotusGuild/pulse/actions/workflows/lint.yml/badge.svg)](https://code.lotusguild.org/LotusGuild/pulse/actions?workflow=lint.yml)
+[![Test](https://code.lotusguild.org/LotusGuild/pulse/actions/workflows/test.yml/badge.svg)](https://code.lotusguild.org/LotusGuild/pulse/actions?workflow=test.yml)
+[![Security](https://code.lotusguild.org/LotusGuild/pulse/actions/workflows/security.yml/badge.svg)](https://code.lotusguild.org/LotusGuild/pulse/actions?workflow=security.yml)
+
+A distributed workflow orchestration platform for managing and executing complex multi-step operations across server clusters through a retro terminal-themed web interface.
+
+> **Security Notice:** This repository is hosted on Gitea and is version-controlled. **Never commit secrets, credentials, passwords, API keys, or any sensitive information to this repo.** All sensitive configuration belongs exclusively in `.env` files which are listed in `.gitignore` and must never be committed. This includes database passwords, worker API keys, webhook secrets, and internal IP details.
+
+**Design System**: [web_template](https://code.lotusguild.org/LotusGuild/web_template) — shared CSS, JS, and layout patterns for all LotusGuild apps
+
+## Styling & Layout
+
+PULSE uses the **LotusGuild Terminal Design System**. For all styling, component, and layout documentation see:
+
+- [`web_template/README.md`](https://code.lotusguild.org/LotusGuild/web_template/src/branch/main/README.md) — full component reference, CSS variables, JS API
+- [`web_template/base.css`](https://code.lotusguild.org/LotusGuild/web_template/src/branch/main/base.css) — unified CSS (`.lt-*` classes)
+- [`web_template/base.js`](https://code.lotusguild.org/LotusGuild/web_template/src/branch/main/base.js) — `window.lt` utilities (toast, modal, WebSocket helpers, fetch)
+- [`web_template/aesthetic_diff.md`](https://code.lotusguild.org/LotusGuild/web_template/src/branch/main/aesthetic_diff.md) — cross-app divergence analysis and convergence guide
+- [`web_template/node/middleware.js`](https://code.lotusguild.org/LotusGuild/web_template/src/branch/main/node/middleware.js) — Express auth, CSRF, CSP nonce middleware
+
+**Pending convergence items (see aesthetic_diff.md):**
+- Extract inline `<style>` from `public/index.html` into `public/style.css` and extend `base.css`
+- Use `lt.autoRefresh.start(refreshData, 30000)` instead of raw `setInterval`
 
 ## Overview
 
-PULSE is a centralized workflow execution system designed to orchestrate operations across distributed infrastructure. It provides a powerful web-based interface for defining, managing, and executing workflows that can span multiple servers, require human interaction, and perform complex automation tasks at scale.
+PULSE is a centralized workflow execution system designed to orchestrate operations across distributed infrastructure. It provides a powerful web-based interface with a vintage CRT terminal aesthetic for defining, managing, and executing workflows that can span multiple servers, require human interaction, and perform complex automation tasks at scale.
 
 ### Key Features
 
-- **Interactive Workflow Management**: Define and execute multi-step workflows with conditional logic, user prompts, and decision points
+- **🎨 Retro Terminal Interface**: Phosphor green CRT-style interface with scanlines, glow effects, and ASCII art
-- **Distributed Execution**: Run commands and scripts across multiple worker nodes simultaneously
+- **⚡ Quick Command Execution**: Instantly execute commands on any worker with built-in templates and command history
-- **High Availability Architecture**: Deploy redundant worker nodes in LXC containers with Ceph storage for fault tolerance
+- **📊 Real-Time Worker Monitoring**: Live system metrics including CPU, memory, load average, and active tasks
-- **Web-Based Control Center**: Intuitive interface for workflow selection, monitoring, and interactive input
+- **🔄 Interactive Workflow Management**: Define and execute multi-step workflows with conditional logic and user prompts
-- **Flexible Worker Pool**: Scale horizontally by adding worker nodes as needed
+- **🌐 Distributed Execution**: Run commands across multiple worker nodes simultaneously via WebSocket
-- **Real-Time Monitoring**: Track workflow progress, view logs, and receive notifications
+- **📈 Execution Tracking**: Comprehensive logging with formatted output, re-run capabilities, and JSON export
+- **🔐 SSO Authentication**: Seamless integration with Authelia for enterprise authentication
+- **🧹 Auto-Cleanup**: Automatic removal of old executions with configurable retention policies
+- **🔔 Terminal Notifications**: Audio beeps and visual toasts for command completion events
 
 ## Architecture
 
 PULSE consists of two core components:
 
 ### PULSE Server
+**Location:** `10.10.10.65` (LXC Container ID: 122)
+**Directory:** `/opt/pulse-server`
+
 The central orchestration hub that:
-- Hosts the web interface for workflow management
+- Hosts the retro terminal web interface
 - Manages workflow definitions and execution state
-- Coordinates task distribution to worker nodes
+- Coordinates task distribution to worker nodes via WebSocket
-- Handles user interactions and input collection
+- Handles user interactions through Authelia SSO
 - Provides real-time status updates and logging
+- Stores all data in MariaDB database
+
+**Technology Stack:**
+- Node.js 20.x
+- Express.js (web framework)
+- WebSocket (ws package) for real-time bidirectional communication
+- MySQL2 (MariaDB driver)
+- Authelia SSO integration
 
 ### PULSE Worker
+**Example:** `10.10.10.151` (LXC Container ID: 153, hostname: pulse-worker-01)
+**Directory:** `/opt/pulse-worker`
+
 Lightweight execution agents that:
-- Connect to the PULSE server and await task assignments
+- Connect to PULSE server via WebSocket with heartbeat monitoring
-- Execute commands, scripts, and code on target infrastructure
+- Execute shell commands and report results in real-time
-- Report execution status and results back to the server
+- Provide system metrics (CPU, memory, load, uptime)
-- Support multiple concurrent workflow executions
+- Support concurrent task execution with configurable limits
-- Automatically reconnect and resume on failure
+- Automatically reconnect on connection loss
+
+**Technology Stack:**
+- Node.js 20.x
+- WebSocket client
+- Child process execution
+- System metrics collection
+
 ```
-┌─────────────────────┐
+┌─────────────────────────────────┐
-│   PULSE Server      │
+│   PULSE Server (10.10.10.65)   │
-│   (Web Interface)   │
+│   Terminal Web Interface + API  │
-└──────────┬──────────┘
+│   ┌───────────┐ ┌──────────┐   │
-           │
+│   │ MariaDB   │ │ Authelia │   │
-    ┌──────┴───────┬──────────────┬──────────────┐
+│   │ Database  │ │   SSO    │   │
-    │              │              │              │
+│   └───────────┘ └──────────┘   │
-┌───▼────┐    ┌───▼────┐    ┌───▼────┐    ┌───▼────┐
+└────────────┬────────────────────┘
-│ Worker │    │ Worker │    │ Worker │    │ Worker │
+             │ WebSocket
-│ Node 1 │    │ Node 2 │    │ Node 3 │    │ Node N │
+    ┌────────┴────────┬───────────┐
-└────────┘    └────────┘    └────────┘    └────────┘
+    │                 │           │
-     LXC Containers in Proxmox with Ceph
+┌───▼────────┐   ┌───▼────┐  ┌──▼─────┐
+│ Worker 1   │   │Worker 2│  │Worker N│
+│10.10.10.151│   │  ...   │  │  ...   │
+└────────────┘   └────────┘  └────────┘
+ LXC Containers in Proxmox with Ceph
 ```
 
-## Deployment
+## Installation
 
 ### Prerequisites
 
-- **Proxmox VE Cluster**: Hypervisor environment for container deployment
+- **Node.js 20.x** or higher
-- **Ceph Storage**: Distributed storage backend for high availability
+- **MariaDB 10.x** or higher
-- **LXC Support**: Container runtime for worker node deployment
+- **Authelia** configured for SSO (optional but recommended)
-- **Network Connectivity**: Communication between server and workers
+- **Network Connectivity** between server and workers
 
-### Installation
+### PULSE Server Setup
 
-#### PULSE Server
 ```bash
-# Clone the repository
+# Clone repository
-git clone https://github.com/yourusername/pulse.git
+cd /opt
-cd pulse
+git clone <your-repo-url> pulse-server
+cd pulse-server
 
 # Install dependencies
-npm install  # or pip install -r requirements.txt
+npm install
 
-# Configure server settings
+# Create .env file with configuration
-cp config.example.yml config.yml
+cat > .env << EOF
-nano config.yml
+# Server Configuration
+PORT=8080
+SECRET_KEY=your-secret-key-here
 
-# Start the PULSE server
+# MariaDB Configuration
-npm start  # or python server.py
+DB_HOST=10.10.10.50
+DB_PORT=3306
+DB_NAME=pulse
+DB_USER=pulse_user
+DB_PASSWORD=your-db-password
+
+# Worker API Key (for worker authentication)
+WORKER_API_KEY=your-worker-api-key
+
+# Auto-cleanup configuration (optional)
+EXECUTION_RETENTION_DAYS=30
+EOF
+
+# Create systemd service
+cat > /etc/systemd/system/pulse.service << EOF
+[Unit]
+Description=PULSE Workflow Orchestration Server
+After=network.target
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/opt/pulse-server
+ExecStart=/usr/bin/node server.js
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Start service
+systemctl daemon-reload
+systemctl enable pulse.service
+systemctl start pulse.service
 ```
 
-#### PULSE Worker
+### PULSE Worker Setup
+
 ```bash
-# On each worker node (LXC container)
+# On each worker node
+cd /opt
+git clone <your-repo-url> pulse-worker
 cd pulse-worker
 
 # Install dependencies
-npm install  # or pip install -r requirements.txt
+npm install
 
-# Configure worker connection
+# Create .env file
-cp worker-config.example.yml worker-config.yml
+cat > .env << EOF
-nano worker-config.yml
+# Worker Configuration
+WORKER_NAME=pulse-worker-01
+PULSE_SERVER=http://10.10.10.65:8080
+PULSE_WS=ws://10.10.10.65:8080
+WORKER_API_KEY=your-worker-api-key
 
-# Start the worker daemon
+# Performance Settings
-npm start  # or python worker.py
+HEARTBEAT_INTERVAL=30
-```
+MAX_CONCURRENT_TASKS=5
+EOF
 
-### High Availability Setup
+# Create systemd service
+cat > /etc/systemd/system/pulse-worker.service << EOF
+[Unit]
+Description=PULSE Worker Node
+After=network.target
 
-Deploy multiple worker nodes across Proxmox hosts:
+[Service]
-```bash
+Type=simple
-# Create LXC template
+User=root
-pct create 1000 local:vztmpl/ubuntu-22.04-standard_amd64.tar.zst \
+WorkingDirectory=/opt/pulse-worker
-  --rootfs ceph-pool:8 \
+ExecStart=/usr/bin/node worker.js
-  --memory 2048 \
+Restart=always
-  --cores 2 \
+RestartSec=10
-  --net0 name=eth0,bridge=vmbr0,ip=dhcp
 
-# Clone for additional workers
+[Install]
-pct clone 1000 1001 --full --storage ceph-pool
+WantedBy=multi-user.target
-pct clone 1000 1002 --full --storage ceph-pool
+EOF
-pct clone 1000 1003 --full --storage ceph-pool
 
-# Start all workers
+# Start service
-for i in {1000..1003}; do pct start $i; done
+systemctl daemon-reload
+systemctl enable pulse-worker.service
+systemctl start pulse-worker.service
 ```
 
 ## Usage
 
-### Creating a Workflow
+### Quick Command Execution
 
-1. Access the PULSE web interface at `http://your-server:8080`
+1. Access PULSE at `http://your-server:8080`
-2. Navigate to **Workflows** → **Create New**
+2. Navigate to **⚡ Quick Command** tab
-3. Define workflow steps using the visual editor or YAML syntax
+3. Select a worker from the dropdown
-4. Specify execution targets (specific nodes, groups, or all workers)
+4. Use **Templates** for pre-built commands or **History** for recent commands
-5. Add interactive prompts where user input is required
+5. Enter your command and click **Execute**
-6. Save and activate the workflow
+6. View results in the **Executions** tab
 
-### Example Workflow
+**Built-in Command Templates:**
-```yaml
+- System Info: `uname -a`
-name: "System Update and Reboot"
+- Disk Usage: `df -h`
-description: "Update all servers in the cluster with user confirmation"
+- Memory Usage: `free -h`
-steps:
+- CPU Info: `lscpu`
-  - name: "Check Current Versions"
+- Running Processes: `ps aux --sort=-%mem | head -20`
-    type: "execute"
+- Network Interfaces: `ip addr show`
-    targets: ["all"]
+- Docker Containers: `docker ps -a`
-    command: "apt list --upgradable"
+- System Logs: `tail -n 50 /var/log/syslog`
-    
-  - name: "User Approval"
-    type: "prompt"
-    message: "Review available updates. Proceed with installation?"
-    options: ["Yes", "No", "Cancel"]
-    
-  - name: "Install Updates"
-    type: "execute"
-    targets: ["all"]
-    command: "apt-get update && apt-get upgrade -y"
-    condition: "prompt_response == 'Yes'"
-    
-  - name: "Reboot Confirmation"
-    type: "prompt"
-    message: "Updates complete. Reboot all servers?"
-    options: ["Yes", "No"]
-    
-  - name: "Rolling Reboot"
-    type: "execute"
-    targets: ["all"]
-    command: "reboot"
-    strategy: "rolling"
-    condition: "prompt_response == 'Yes'"
-```
 
-### Running a Workflow
+### Worker Monitoring
 
-1. Select a workflow from the dashboard
+The **Workers** tab displays real-time metrics for each worker:
-2. Click **Execute**
+- System information (OS, architecture, CPU cores)
-3. Monitor progress in real-time
+- Memory usage (used/total with percentage)
-4. Respond to interactive prompts as they appear
+- Load averages (1m, 5m, 15m)
-5. View detailed logs for each execution step
+- System uptime
+- Active tasks vs. maximum concurrent capacity
 
-## Configuration
+### Execution Management
 
-### Server Configuration (`config.yml`)
+- **View Details**: Click any execution to see formatted logs with timestamps, status, and output
-```yaml
+- **Re-run Command**: Click "Re-run" button in execution details to repeat a command
-server:
+- **Download Logs**: Export execution data as JSON for auditing
-  host: "0.0.0.0"
+- **Clear Completed**: Bulk delete finished executions
-  port: 8080
+- **Auto-Cleanup**: Executions older than 30 days are automatically removed
-  secret_key: "your-secret-key"
 
-database:
+### Workflow Creation (Future Feature)
-  type: "postgresql"
-  host: "localhost"
-  port: 5432
-  name: "pulse"
 
-workers:
+1. Navigate to **Workflows** → **Create New**
-  heartbeat_interval: 30
+2. Define workflow steps using JSON syntax
-  timeout: 300
+3. Specify target workers
-  max_concurrent_tasks: 10
+4. Add interactive prompts where needed
-
+5. Save and execute
-security:
-  enable_authentication: true
-  require_approval: true
-```
-
-### Worker Configuration (`worker-config.yml`)
-```yaml
-worker:
-  name: "worker-01"
-  server_url: "http://pulse-server:8080"
-  api_key: "worker-api-key"
-  
-resources:
-  max_cpu_percent: 80
-  max_memory_mb: 1024
-  
-executor:
-  shell: "/bin/bash"
-  working_directory: "/tmp/pulse"
-  timeout: 3600
-```
 
 ## Features in Detail
 
-### Interactive Workflows
+### Terminal Aesthetic
-- Pause execution to collect user input via web forms
+- Phosphor green (#00ff41) on black (#0a0a0a) color scheme
-- Display intermediate results for review
+- CRT scanline animation effect
-- Conditional branching based on user decisions
+- Text glow and shadow effects
-- Multi-choice prompts with validation
+- ASCII box-drawing characters for borders
+- Boot sequence animation on first load
+- Hover effects with smooth transitions
 
-### Mass Execution
+### Real-Time Communication
-- Run commands across all workers simultaneously
+- WebSocket-based bidirectional communication
-- Target specific node groups or individual servers
+- Instant command result notifications
-- Rolling execution for zero-downtime updates
+- Live worker status updates
-- Parallel and sequential execution strategies
+- Terminal beep sounds for events
+- Toast notifications with visual feedback
 
-### Monitoring & Logging
+### Execution Tracking
-- Real-time workflow execution dashboard
+- Formatted log display (not raw JSON)
-- Detailed per-step logging and output capture
+- Color-coded success/failure indicators
-- Historical execution records and analytics
+- Timestamp and duration for each step
-- Alert notifications for failures or completion
+- Scrollable output with syntax highlighting
+- Persistent history with pagination
+- Load More button for large execution lists
 
 ### Security
-- Role-based access control (RBAC)
+- Authelia SSO integration for user authentication
 - API key authentication for workers
-- Workflow approval requirements
+- User session management
-- Audit logging for all actions
+- Admin-only operations (worker deletion, workflow management)
+- Audit logging for all executions
 
+### Performance
+- Automatic cleanup of old executions (configurable retention)
+- Pagination for large execution lists (50 at a time)
+- Efficient WebSocket connection pooling
+- Worker heartbeat monitoring
+- Database connection pooling
+
+## Configuration
+
+### Environment Variables
+
+**Server (.env):**
+```bash
+PORT=8080                           # Server port
+SECRET_KEY=<random-string>          # Session secret
+DB_HOST=10.10.10.50                # MariaDB host
+DB_PORT=3306                        # MariaDB port
+DB_NAME=pulse                       # Database name
+DB_USER=pulse_user                  # Database user
+DB_PASSWORD=<password>              # Database password
+WORKER_API_KEY=<api-key>           # Worker authentication key
+EXECUTION_RETENTION_DAYS=30         # Auto-cleanup retention (default: 30)
+```
+
+**Worker (.env):**
+```bash
+WORKER_NAME=pulse-worker-01         # Unique worker name
+PULSE_SERVER=http://10.10.10.65:8080   # Server HTTP URL
+PULSE_WS=ws://10.10.10.65:8080          # Server WebSocket URL
+WORKER_API_KEY=<api-key>            # Must match server key
+HEARTBEAT_INTERVAL=30               # Heartbeat seconds (default: 30)
+MAX_CONCURRENT_TASKS=5              # Max parallel tasks (default: 5)
+```
+
+## Database Schema
+
+PULSE uses MariaDB with the following tables:
+
+| Table | Purpose |
+|-------|---------|
+| `users` | User accounts synced from Authelia SSO |
+| `workers` | Worker node registry with connection metadata |
+| `workflows` | Workflow definitions stored as JSON |
+| `executions` | Execution history with logs, status, and timestamps |
+
+### `executions` Table Key Columns
+
+| Column | Description |
+|--------|-------------|
+| `id` | Auto-increment primary key |
+| `worker_id` | Foreign key to workers |
+| `command` | The command that was executed |
+| `status` | `running`, `completed`, `failed` |
+| `output` | Command output / log (JSON or text) |
+| `created_at` | Execution start timestamp |
+| `completed_at` | Execution end timestamp |
+
+### `workers` Table Key Columns
+
+| Column | Description |
+|--------|-------------|
+| `id` | Auto-increment primary key |
+| `name` | Worker name (from `WORKER_NAME` env) |
+| `last_seen` | Last heartbeat timestamp |
+| `status` | `online`, `offline` |
+| `metadata` | JSON blob of system info |
+
+## Troubleshooting
+
+### Worker Not Connecting
+```bash
+# Check worker service status
+systemctl status pulse-worker
+
+# Check worker logs
+journalctl -u pulse-worker -n 50 -f
+
+# Verify API key matches server
+grep WORKER_API_KEY /opt/pulse-worker/.env
+```
+
+### Commands Stuck in "Running"
+- This was fixed in recent updates - restart the server:
+```bash
+systemctl restart pulse.service
+```
+
+### Clear All Executions
+Use the database directly if needed:
+```bash
+mysql -h 10.10.10.50 -u pulse_user -p pulse
+> DELETE FROM executions WHERE status IN ('completed', 'failed');
+```
+
+## Development
+
+### Recent Updates
+
+**Phase 1-6 Improvements:**
+- Formatted log display with color-coding
+- Worker system metrics monitoring
+- Command templates and history
+- Re-run and download execution features
+- Auto-cleanup and pagination
+- Terminal aesthetic refinements
+- Audio notifications and visual toasts
+
+See git history for detailed changelog.
+
+### Future Enhancements
+- Full workflow system implementation
+- Multi-worker command execution
+- Scheduled/cron job support
+- Execution search and filtering
+- Dark/light theme toggle
+- Mobile-responsive design
+- REST API documentation
+- Webhook integrations
+
+## License
+
+MIT License - See LICENSE file for details
 
 ---
 
-**PULSE** - Orchestrating your infrastructure, one heartbeat at a time.
+## CI / CD
+
+| Workflow | Purpose | Triggers |
+|---|---|---|
+| `lint.yml` | ESLint on all `.js` files | Every push and PR |
+| `test.yml` | Jest unit tests (`lib/utils.js`) | Every push and PR |
+| `security.yml` | `npm audit --audit-level=high` | Every push, PR, and weekly Monday 6am |
+| `deploy` job in `lint.yml` | Calls the `pulse-deploy` webhook on CT122 (10.10.10.65) to pull + restart | Push to `main` only, after lint passes |
+
+Branch protection is enabled on `main` — the `lint.yml` check must pass before any PR can merge.
+
+Tests live in `tests/utils.test.js` and cover the pure utility functions in `lib/utils.js`:
+`validateWebhookUrl`, `applyParams`, `evalCondition`, `calculateNextRun`.
+
+---
+
+**PULSE** - Orchestrating your infrastructure, one heartbeat at a time. ⚡
+
+Built with retro terminal aesthetics 🖥️ | Powered by WebSockets 🔌 | Secured by Authelia 🔐

lib/utils.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Validate a webhook URL.
+ * Returns { ok: true, url } or { ok: false, reason }.
+ */
+function validateWebhookUrl(raw) {
+  if (!raw) return { ok: true, url: null };
+  let url;
+  try { url = new URL(raw); } catch { return { ok: false, reason: 'Invalid URL format' }; }
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    return { ok: false, reason: 'Webhook URL must use http or https' };
+  }
+  const host = url.hostname.toLowerCase();
+  if (
+    host === 'localhost' ||
+    host === '::1' ||
+    /^127\./.test(host) ||
+    /^10\./.test(host) ||
+    /^192\.168\./.test(host) ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+    /^169\.254\./.test(host) ||
+    /^fe80:/i.test(host)
+  ) {
+    return { ok: false, reason: 'Webhook URL must not point to a private/internal address' };
+  }
+  return { ok: true, url };
+}
+
+/**
+ * Replace {{param}} placeholders in a command string.
+ * Throws if a substituted value contains unsafe characters.
+ */
+function applyParams(command, params) {
+  return command.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    if (!(key in params)) return match;
+    const val = String(params[key]).trim();
+    if (!/^[a-zA-Z0-9._:@/-]+$/.test(val)) {
+      throw new Error(`Unsafe value for workflow parameter "${key}"`);
+    }
+    return val;
+  });
+}
+
+/**
+ * Evaluate a condition expression safely using vm.runInNewContext.
+ * Returns boolean (false on error).
+ */
+function evalCondition(condition, state, params) {
+  const vm = require('vm');
+  try {
+    const context = vm.createContext({ state, params, promptResponse: state.promptResponse });
+    return !!vm.runInNewContext(condition, context, { timeout: 100 });
+  } catch (e) {
+    console.warn(`[Workflow] evalCondition error (treated as false): ${e.message} — condition: ${condition}`);
+    return false;
+  }
+}
+
+/**
+ * Calculate the next run date for a scheduled command.
+ */
+function calculateNextRun(scheduleType, scheduleValue) {
+  const cronParser = require('cron-parser');
+  const now = new Date();
+
+  if (scheduleType === 'interval') {
+    const minutes = parseInt(scheduleValue);
+    if (isNaN(minutes) || minutes <= 0) throw new Error(`Invalid interval value: ${scheduleValue}`);
+    return new Date(now.getTime() + minutes * 60000);
+  } else if (scheduleType === 'daily') {
+    const [hours, minutes] = scheduleValue.split(':').map(Number);
+    if (isNaN(hours) || isNaN(minutes)) throw new Error(`Invalid daily time format: ${scheduleValue}`);
+    const next = new Date(now);
+    next.setHours(hours, minutes, 0, 0);
+    if (next <= now) next.setDate(next.getDate() + 1);
+    return next;
+  } else if (scheduleType === 'hourly') {
+    const hours = parseInt(scheduleValue);
+    if (isNaN(hours) || hours <= 0) throw new Error(`Invalid hourly value: ${scheduleValue}`);
+    return new Date(now.getTime() + hours * 3600000);
+  } else if (scheduleType === 'cron') {
+    const interval = cronParser.CronExpressionParser.parse(scheduleValue, { currentDate: now });
+    return interval.next().toDate();
+  }
+
+  throw new Error(`Unknown schedule type: ${scheduleType}`);
+}
+
+module.exports = { validateWebhookUrl, applyParams, evalCondition, calculateNextRun };

package.json

@@ -3,21 +3,22 @@
   "version": "1.0.0",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "jest --coverage"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "description": "",
   "dependencies": {
-    "bcryptjs": "^3.0.3",
+    "cron-parser": "^5.5.0",
-    "body-parser": "^2.2.1",
-    "cors": "^2.8.5",
     "dotenv": "^17.2.3",
     "express": "^5.1.0",
-    "js-yaml": "^4.1.1",
+    "express-rate-limit": "^8.3.1",
-    "jsonwebtoken": "^9.0.2",
     "mysql2": "^3.15.3",
     "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.1",
+    "jest": "^29.7.0"
   }
 }

public/.eslintrc.json

@@ -0,0 +1,11 @@
+{
+    "env": { "browser": true, "es2021": true },
+    "parserOptions": { "ecmaVersion": 2021, "sourceType": "script" },
+    "rules": {
+        "no-unused-vars": "warn",
+        "no-empty": "warn",
+        "no-inner-declarations": "warn",
+        "semi": ["error", "always"],
+        "eqeqeq": "warn"
+    }
+}

public/base.js

@@ -0,0 +1 @@
+/root/code/web_template/base.js

tests/.eslintrc.json

@@ -0,0 +1,7 @@
+{
+    "env": {
+        "node": true,
+        "jest": true,
+        "es2021": true
+    }
+}

tests/utils.test.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const { validateWebhookUrl, applyParams, evalCondition, calculateNextRun } = require('../lib/utils');
+
+// ── validateWebhookUrl ──────────────────────────────────────────────────────
+
+describe('validateWebhookUrl', () => {
+  test('null/empty returns ok with null url', () => {
+    expect(validateWebhookUrl(null)).toEqual({ ok: true, url: null });
+    expect(validateWebhookUrl('')).toEqual({ ok: true, url: null });
+  });
+
+  test('valid public https URL is accepted', () => {
+    const result = validateWebhookUrl('https://hooks.example.com/notify');
+    expect(result.ok).toBe(true);
+    expect(result.url).toBeInstanceOf(URL);
+  });
+
+  test('valid public http URL is accepted', () => {
+    const result = validateWebhookUrl('http://webhook.example.com/event');
+    expect(result.ok).toBe(true);
+  });
+
+  test('invalid URL format is rejected', () => {
+    expect(validateWebhookUrl('not a url')).toMatchObject({ ok: false, reason: expect.stringContaining('Invalid URL') });
+  });
+
+  test('non-http protocol is rejected', () => {
+    expect(validateWebhookUrl('ftp://example.com/hook')).toMatchObject({ ok: false, reason: expect.stringContaining('http') });
+  });
+
+  test('localhost is rejected', () => {
+    expect(validateWebhookUrl('http://localhost/hook')).toMatchObject({ ok: false });
+  });
+
+  test('10.x.x.x private range is rejected', () => {
+    expect(validateWebhookUrl('http://10.0.0.1/hook')).toMatchObject({ ok: false });
+    expect(validateWebhookUrl('http://10.10.10.45/hook')).toMatchObject({ ok: false });
+  });
+
+  test('192.168.x.x private range is rejected', () => {
+    expect(validateWebhookUrl('http://192.168.1.1/hook')).toMatchObject({ ok: false });
+  });
+
+  test('127.0.0.1 loopback is rejected', () => {
+    expect(validateWebhookUrl('http://127.0.0.1/hook')).toMatchObject({ ok: false });
+  });
+
+  test('172.16.x.x – 172.31.x.x private range is rejected', () => {
+    expect(validateWebhookUrl('http://172.16.0.1/hook')).toMatchObject({ ok: false });
+    expect(validateWebhookUrl('http://172.31.255.255/hook')).toMatchObject({ ok: false });
+  });
+
+  test('172.32.x.x (outside private range) is accepted', () => {
+    const result = validateWebhookUrl('http://172.32.0.1/hook');
+    expect(result.ok).toBe(true);
+  });
+});
+
+// ── applyParams ─────────────────────────────────────────────────────────────
+
+describe('applyParams', () => {
+  test('replaces a single placeholder', () => {
+    expect(applyParams('echo {{msg}}', { msg: 'hello' })).toBe('echo hello');
+  });
+
+  test('replaces multiple placeholders', () => {
+    expect(applyParams('cp {{src}} {{dst}}', { src: 'a.txt', dst: 'b.txt' })).toBe('cp a.txt b.txt');
+  });
+
+  test('leaves unknown placeholders unchanged', () => {
+    expect(applyParams('echo {{unknown}}', {})).toBe('echo {{unknown}}');
+  });
+
+  test('throws on unsafe param value with spaces', () => {
+    expect(() => applyParams('echo {{x}}', { x: 'rm -rf /' })).toThrow('Unsafe value');
+  });
+
+  test('throws on unsafe param value with semicolons', () => {
+    expect(() => applyParams('echo {{x}}', { x: 'a;b' })).toThrow('Unsafe value');
+  });
+
+  test('allows safe characters: dots, dashes, slashes, colons, @', () => {
+    expect(applyParams('ssh {{host}}', { host: 'user@10.0.0.1:22' })).toBe('ssh user@10.0.0.1:22');
+    expect(applyParams('cat {{path}}', { path: '/etc/hosts' })).toBe('cat /etc/hosts');
+  });
+
+  test('trims whitespace from param values', () => {
+    expect(applyParams('echo {{x}}', { x: '  hello  ' })).toBe('echo hello');
+  });
+});
+
+// ── evalCondition ───────────────────────────────────────────────────────────
+
+describe('evalCondition', () => {
+  test('evaluates truthy expression', () => {
+    expect(evalCondition('1 === 1', {}, {})).toBe(true);
+  });
+
+  test('evaluates falsy expression', () => {
+    expect(evalCondition('1 === 2', {}, {})).toBe(false);
+  });
+
+  test('accesses state variables', () => {
+    expect(evalCondition('state.count > 5', { count: 10 }, {})).toBe(true);
+    expect(evalCondition('state.count > 5', { count: 3 }, {})).toBe(false);
+  });
+
+  test('accesses params', () => {
+    expect(evalCondition('params.env === "prod"', {}, { env: 'prod' })).toBe(true);
+  });
+
+  test('returns false on syntax error (does not throw)', () => {
+    expect(evalCondition('this is not valid js !!!', {}, {})).toBe(false);
+  });
+
+  test('returns false on timeout / infinite loop', () => {
+    expect(evalCondition('while(true){}', {}, {})).toBe(false);
+  });
+});
+
+// ── calculateNextRun ────────────────────────────────────────────────────────
+
+describe('calculateNextRun', () => {
+  test('interval: returns a date ~N minutes in the future', () => {
+    const before = Date.now();
+    const result = calculateNextRun('interval', '30');
+    expect(result.getTime()).toBeGreaterThanOrEqual(before + 30 * 60000 - 100);
+    expect(result.getTime()).toBeLessThanOrEqual(before + 30 * 60000 + 1000);
+  });
+
+  test('interval: throws on non-positive value', () => {
+    expect(() => calculateNextRun('interval', '0')).toThrow();
+    expect(() => calculateNextRun('interval', '-5')).toThrow();
+    expect(() => calculateNextRun('interval', 'abc')).toThrow();
+  });
+
+  test('hourly: returns a date ~N hours in the future', () => {
+    const before = Date.now();
+    const result = calculateNextRun('hourly', '2');
+    expect(result.getTime()).toBeGreaterThanOrEqual(before + 2 * 3600000 - 100);
+  });
+
+  test('daily: returns a Date object', () => {
+    const result = calculateNextRun('daily', '06:00');
+    expect(result).toBeInstanceOf(Date);
+    expect(result.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  test('daily: throws on invalid time format', () => {
+    expect(() => calculateNextRun('daily', 'noon')).toThrow();
+  });
+
+  test('cron: returns next occurrence after now', () => {
+    const result = calculateNextRun('cron', '0 6 * * 1');
+    expect(result).toBeInstanceOf(Date);
+    expect(result.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  test('unknown type throws', () => {
+    expect(() => calculateNextRun('weekly', '1')).toThrow('Unknown schedule type');
+  });
+});

worker/worker.js

@@ -0,0 +1,257 @@
+const axios = require('axios');
+const WebSocket = require('ws');
+const { exec } = require('child_process');
+const { promisify } = require('util');
+const os = require('os');
+const crypto = require('crypto');
+require('dotenv').config();
+
+const execAsync = promisify(exec);
+
+class PulseWorker {
+  constructor() {
+    this.workerId = crypto.randomUUID();
+    this.workerName = process.env.WORKER_NAME || os.hostname();
+    this.serverUrl = process.env.PULSE_SERVER || 'http://localhost:8080';
+    this.wsUrl = process.env.PULSE_WS || 'ws://localhost:8080';
+    this.apiKey = process.env.WORKER_API_KEY;
+    this.heartbeatInterval = parseInt(process.env.HEARTBEAT_INTERVAL || '30') * 1000;
+    this.maxConcurrentTasks = parseInt(process.env.MAX_CONCURRENT_TASKS || '5');
+    this.activeTasks = 0;
+    this.ws = null;
+    this.heartbeatTimer = null;
+  }
+
+  async start() {
+    console.log(`[PULSE Worker] Starting worker: ${this.workerName}`);
+    console.log(`[PULSE Worker] Worker ID: ${this.workerId}`);
+    console.log(`[PULSE Worker] Server: ${this.serverUrl}`);
+
+    // Send initial heartbeat
+    await this.sendHeartbeat();
+
+    // Start heartbeat timer
+    this.startHeartbeat();
+
+    // Connect to WebSocket for real-time commands
+    this.connectWebSocket();
+
+    console.log(`[PULSE Worker] Worker started successfully`);
+  }
+
+  startHeartbeat() {
+    this.heartbeatTimer = setInterval(async () => {
+      try {
+        await this.sendHeartbeat();
+      } catch (error) {
+        console.error('[PULSE Worker] Heartbeat failed:', error.message);
+      }
+    }, this.heartbeatInterval);
+  }
+
+  async sendHeartbeat() {
+    const metadata = {
+      hostname: os.hostname(),
+      platform: os.platform(),
+      arch: os.arch(),
+      cpus: os.cpus().length,
+      totalMem: os.totalmem(),
+      freeMem: os.freemem(),
+      uptime: os.uptime(),
+      loadavg: os.loadavg(),
+      activeTasks: this.activeTasks,
+      maxConcurrentTasks: this.maxConcurrentTasks
+    };
+
+    try {
+      const response = await axios.post(
+        `${this.serverUrl}/api/workers/heartbeat`,
+        {
+          worker_id: this.workerId,
+          name: this.workerName,
+          metadata: metadata
+        },
+        {
+          headers: {
+            'X-API-Key': this.apiKey,
+            'Content-Type': 'application/json'
+          }
+        }
+      );
+
+      console.log(`[PULSE Worker] Heartbeat sent - Status: online`);
+      return response.data;
+    } catch (error) {
+      console.error('[PULSE Worker] Heartbeat error:', error.message);
+      throw error;
+    }
+  }
+
+  connectWebSocket() {
+    console.log(`[PULSE Worker] Connecting to WebSocket...`);
+    
+    this.ws = new WebSocket(this.wsUrl);
+
+    this.ws.on('open', () => {
+      console.log('[PULSE Worker] WebSocket connected');
+      // Identify this worker
+      this.ws.send(JSON.stringify({
+        type: 'worker_connect',
+        worker_id: this.workerId,
+        worker_name: this.workerName
+      }));
+    });
+
+    this.ws.on('message', async (data) => {
+      try {
+        const message = JSON.parse(data.toString());
+        await this.handleMessage(message);
+      } catch (error) {
+        console.error('[PULSE Worker] Message handling error:', error);
+      }
+    });
+
+    this.ws.on('close', () => {
+      console.log('[PULSE Worker] WebSocket disconnected, reconnecting...');
+      setTimeout(() => this.connectWebSocket(), 5000);
+    });
+
+    this.ws.on('error', (error) => {
+      console.error('[PULSE Worker] WebSocket error:', error.message);
+    });
+  }
+
+  async handleMessage(message) {
+    console.log(`[PULSE Worker] Received message:`, message.type);
+
+    switch (message.type) {
+      case 'execute_command':
+        await this.executeCommand(message);
+        break;
+      case 'execute_workflow':
+        await this.executeWorkflow(message);
+        break;
+      case 'ping':
+        this.sendPong();
+        break;
+      default:
+        console.log(`[PULSE Worker] Unknown message type: ${message.type}`);
+    }
+  }
+
+  async executeCommand(message) {
+    const { command, execution_id, command_id, timeout = 300000 } = message;
+
+    if (this.activeTasks >= this.maxConcurrentTasks) {
+      console.log(`[PULSE Worker] Max concurrent tasks reached, rejecting command`);
+      return;
+    }
+
+    this.activeTasks++;
+    console.log(`[PULSE Worker] Executing command (active tasks: ${this.activeTasks})`);
+
+    try {
+      const startTime = Date.now();
+      const { stdout, stderr } = await execAsync(command, {
+        timeout: timeout,
+        maxBuffer: 10 * 1024 * 1024 // 10MB buffer
+      });
+      const duration = Date.now() - startTime;
+
+      const result = {
+        type: 'command_result',
+        execution_id,
+        worker_id: this.workerId,
+        command_id,
+        success: true,
+        stdout: stdout,
+        stderr: stderr,
+        duration: duration,
+        timestamp: new Date().toISOString()
+      };
+
+      this.sendResult(result);
+      console.log(`[PULSE Worker] Command completed in ${duration}ms`);
+    } catch (error) {
+      const result = {
+        type: 'command_result',
+        execution_id,
+        worker_id: this.workerId,
+        command_id,
+        success: false,
+        error: error.message,
+        stdout: error.stdout || '',
+        stderr: error.stderr || '',
+        timestamp: new Date().toISOString()
+      };
+
+      this.sendResult(result);
+      console.error(`[PULSE Worker] Command failed:`, error.message);
+    } finally {
+      this.activeTasks--;
+    }
+  }
+
+  async executeWorkflow(message) {
+    const { workflow, execution_id } = message;
+    
+    console.log(`[PULSE Worker] Executing workflow: ${workflow.name}`);
+    
+    // Workflow execution will be implemented in phase 2
+    // For now, just acknowledge receipt
+    this.sendResult({
+      type: 'workflow_result',
+      execution_id,
+      worker_id: this.workerId,
+      success: true,
+      message: 'Workflow execution not yet implemented',
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  sendResult(result) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(result));
+    }
+  }
+
+  sendPong() {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ type: 'pong', worker_id: this.workerId }));
+    }
+  }
+
+  async stop() {
+    console.log('[PULSE Worker] Shutting down...');
+    
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+    }
+
+    if (this.ws) {
+      this.ws.close();
+    }
+
+    console.log('[PULSE Worker] Shutdown complete');
+  }
+}
+
+// Start worker
+const worker = new PulseWorker();
+
+// Handle graceful shutdown
+process.on('SIGTERM', async () => {
+  await worker.stop();
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  await worker.stop();
+  process.exit(0);
+});
+
+// Start the worker
+worker.start().catch((error) => {
+  console.error('[PULSE Worker] Fatal error:', error);
+  process.exit(1);
+});