@gravito/zenith 0.1.0-beta.1 → 1.0.0

package/docs/ALERTING_GUIDE.md

@@ -0,0 +1,71 @@
+# 🔔 Zenith Alerting Guide
+
+This guide explains how to configure and manage the alerting system in Zenith to ensure your infrastructure and queues remain healthy.
+
+---
+
+## 🚀 Overview
+
+Zenith's alerting engine is **Redis-Native** and **Stateless**.
+*   **Persistence**: Rules are stored in Redis (`gravito:zenith:alerts:rules`).
+*   **Evaluation**: The server evaluates all rules every 2 seconds against real-time metrics.
+*   **Delivery**: Alerts are dispatched via Slack Webhooks.
+
+---
+
+## 🛠️ Configuration Fields
+
+When adding a new rule in **Settings > Alerting**, you will encounter these fields:
+
+### 1. Rule Name
+A descriptive label for the alert (e.g., `Critical Backlog`, `Agent Offline`). This name will appear in the Slack notification.
+
+### 2. Type (Metric Category)
+*   **Queue Backlog**: Monitors the number of jobs in the `waiting` state.
+*   **High Failure Count**: Monitors the number of jobs in the `failed` state.
+*   **Worker Loss**: Monitors the total number of active worker nodes.
+*   **Node CPU (%)**: Monitors process-level CPU usage reported by Quasar Agents.
+*   **Node RAM (%)**: Monitors process-level RAM usage (RSS) relative to system total.
+
+### 3. Threshold
+The numeric value that triggers the alert.
+*   For **Backlog/Failure**: The number of jobs (e.g., `1000`).
+*   For **CPU/RAM**: The percentage (e.g., `90`).
+*   For **Worker Loss**: The *minimum* number of workers expected (e.g., alert triggers if count is `< 2`).
+
+### 4. Cooldown (Minutes)
+**Crucial Concept**: The period the system "stays silent" after an alert is fired.
+*   **Logic**: Once a rule triggers and sends a notification, it enters a "lock" state for the duration of the cooldown.
+*   **Purpose**: Prevents "Alert Fatigue" and notification storms.
+*   **Example**: If set to `30`, and a backlog spike occurs, you get **one** notification. You won't get another one for the same rule for 30 minutes, even if the backlog remains high.
+
+### 5. Queue (Optional)
+Specify a specific queue name (e.g., `orders`, `emails`) to monitor. If left empty, the rule applies to the **total sum** of all queues.
+
+---
+
+## 🌊 Best Practices
+
+### The "Instant Fire" Design
+Zenith alerts are designed for **instant awareness**.
+*   If a threshold is met during a 2-second check, the alert fires **immediately**.
+*   It does **not** wait for the condition to persist for multiple minutes (Debouncing).
+*   **Pro Tip**: If you have frequent "tiny spikes" that resolve themselves in seconds, set your **Threshold** slightly higher than the spikes to avoid noise.
+
+### Recommended Settings
+
+| Scenario | Type | Threshold | Cooldown |
+| :--- | :--- | :--- | :--- |
+| **Critical Failure** | High Failure Count | 50 | 15m |
+| **System Overload** | Node CPU | 90 | 30m |
+| **Quiet Hours** | Queue Backlog | 5000 | 120m |
+| **Fatal Shutdown** | Worker Loss | 1 | 10m |
+
+---
+
+## 🔗 Slack Integration
+To receive notifications, ensure the `SLACK_WEBHOOK_URL` environment variable is set before starting the Zenith server.
+
+```bash
+export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/Txxx/Bxxx/Xxxx
+```

package/docs/LARAVEL_ZENITH_ROADMAP.md

@@ -0,0 +1,109 @@
+# 🚀 Project Zenith: Laravel Integration Roadmap
+
+**Repository**: `gravito-framework/laravel-zenith`
+**Target Audience**: Laravel 10/11 Applications
+**Goal**: Provide deep, native introspection into Laravel applications for Gravito Zenith.
+
+---
+
+## 1. Vision & Architecture
+
+Unlike the **Quasar Agent** (which is a sidecar daemon for OS/Infrastructure monitoring), **Laravel Zenith** is a native Composer package that lives *inside* the application.
+
+*   **Role**: " The Reporter". It sees what the OS cannot see.
+*   **Transport**: Direct Redis connection (utilizing `swarrot` or standard `predis`/`phpredis`).
+*   **Philosophy**: Zero-blocking. All reporting should be "fire-and-forget" or queued to avoid slowing down the user request lifecycle.
+
+---
+
+## 2. Core Features (The "Why")
+
+### A. Live Operational Logs (`logs`)
+*   **Feature**: A custom `Log Channel` driver.
+*   **Goal**: Stream logs (Info/Error/Debug) directly to Zenith's Live Log view.
+*   **Implementation**:
+    *   `config/logging.php`: Add a `zenith` channel.
+    *   Push JSON payloads to `flux_console:logs` Redis channel.
+
+### B. Queue Lifecycle Events (`queues`)
+*   **Feature**: Listen to Laravel Queue Events (`JobProcessing`, `JobProcessed`, `JobFailed`).
+*   **Goal**: Provide granular job insight that `quasar-go` cannot (e.g., "Job X failed with Exception Y", "Job Z took 45s").
+*   **Implementation**:
+    *   Event Subscriber for `Illuminate\Queue\Events\*`.
+    *   Capture `job->getRawBody()`, `exception->getMessage()`.
+
+### C. Request Performance (`http`)
+*   **Feature**: Global Middleware (`ZenithMonitorMiddleware`).
+*   **Goal**: Track "Slow Requests", 500 Errors, and Throughput.
+*   **Metrics**:
+    *   Status Codes (2xx, 4xx, 5xx).
+    *   Duration (ms).
+    *   Route Name / Controller Action.
+
+### D. System Health Checks
+*   **Feature**: `php artisan zenith:check`
+*   **Goal**: Verify Redis connection and permissions.
+
+---
+
+## 3. Implementation Roadmap
+
+### Phase 1: The Foundation (Logs & Config)
+**Goal**: Get the package installed and streaming basic logs.
+- [ ] Initialize Repository `gravito-framework/laravel-zenith`.
+- [ ] Create `ZenithServiceProvider`.
+- [ ] Implement `ZenithLogger` (Monolog Handler).
+- [ ] Publishing `config/zenith.php` (Redis connection settings).
+- [ ] **Deliverable**: `Log::info('Hello Zenith')` appears in Zenith UI.
+
+### Phase 2: The Worker's Eye (Queues)
+**Goal**: Deep visibility into Queue Jobs.
+- [ ] Create `ZenithQueueSubscriber`.
+- [ ] Handle `JobFailed`: Serialize exception and push to Zenith Alerting.
+- [ ] Handle `JobProcessed`: Record metrics for "Jobs per minute".
+- [ ] **Deliverable**: Seeing real-time "Job Completed" toasts and Error details in Zenith.
+
+### Phase 3: The Watchtower (HTTP & Exceptions)
+**Goal**: Monitoring web requests.
+- [ ] Create `RecordRequestMetrics` Middleware.
+- [ ] Exception Handler integration (optional, for global error catching).
+- [ ] Filter logic (ignore `/nova`, `/telescope`, etc.).
+- [ ] **Deliverable**: HTTP Throughput graphs in Zenith.
+
+### Phase 4: The Bridge (Remote Control Hooks)
+**Goal**: Allow Zenith to trigger Laravel actions safely.
+- [ ] Expose internal hooks for `quasar-go` to call?
+    *   *Note*: `quasar-go` already calls `artisan`. Phase 4 might be about ensuring `artisan zenith:run-job {id}` exists if we need advanced job re-running that `queue:retry` can't handle.
+
+---
+
+## 4. Technical Specifications
+
+### Redis Protocol
+We will reuse the **Gravito Pulse Protocol (GPP)** used by `quasar-go`:
+*   **Logs**: `PUBLISH flux_console:logs`
+*   **Metrics**: `INCR flux_console:metrics:...`
+
+### Configuration (`zenith.php`)
+```php
+return [
+    'enabled' => env('ZENITH_ENABLED', true),
+    
+    'connection' => env('ZENITH_REDIS_CONNECTION', 'default'),
+    
+    'logging' => [
+        'enabled' => true,
+        'level' => 'debug',
+    ],
+    
+    'queues' => [
+        'monitor_all' => true,
+        'ignore_jobs' => [],
+    ],
+];
+```
+
+### Dependency Strategy
+*   **Support**: Laravel 10.x, 11.x
+*   **Php**: 8.1+
+*   **Driver**: `phpredis` (preferred) or `predis`.

package/docs/QUASAR_MASTER_PLAN.md

@@ -0,0 +1,140 @@
+# 🌌 Project Quasar: Master Implementation Plan
+
+**Version**: 1.0.0 (Unified)
+**Target**: Zenith v1.0
+**Context**: This document supersedes all previous "Pulse" plans. It is the single source of truth for the Quasar monitoring ecosystem.
+
+---
+
+## 1. Vision & Identity
+
+**Quasar** is the comprehensive observability layer for the Gravito ecosystem. It unifies infrastructure monitoring (CPU/RAM), application insights (Queues/Slow Logs), and availability checks into a single stream.
+
+> **Slogan**: *"The brightest signal in your infrastructure."*
+
+---
+
+## 2. Architecture & Deployment Matrix
+
+We employ a "Right Tool for the Job" strategy for deployment:
+
+| Ecosystem | Tool | Package | Strategy |
+| :--- | :--- | :--- | :--- |
+| **Node.js / Bun** | **SDK** | `@gravito/quasar` | **In-App Integration**. Directly imports into the app. Captures Event Loop, Heap, and Queues. |
+| **Legacy / Polyglot** | **Agent** | `gravito/quasar-agent` | **Sidecar / Daemon**. Standalone Go binary. Captures OS-level metrics and external Queue states via Redis/API. |
+| **PHP / Laravel** | **Package** | `gravito/laravel-zenith` | **Native Integration**. Laravel Service Provider. Captures Jobs, Logs, and Exceptions. |
+
+### 🚀 Deployment Methods (Zero Friction)
+1.  **NPM**: `npm install @gravito/quasar` (For Node developers)
+2.  **Docker**: `image: gravito/quasar-agent:latest` (For Container/K8s/Laravel Sail)
+3.  **Shell**: `curl -sL get.gravito.dev/quasar | bash` (For Bare Metal/VM)
+
+---
+
+## 3. Data Protocol (The Quasar Schema)
+
+All agents/SDKs report to Redis using this unified schema.
+
+**Namespace**: `gravito:quasar:`
+
+### A. Heartbeat (Infrastructure)
+*   **Key**: `gravito:quasar:node:{service_name}:{node_id}`
+*   **TTL**: 30 seconds
+*   **Metrics Philosophy**: Report **BOTH** Process and System metrics to isolate resource usage.
+    *   `process`: metrics for the specific service (RAM usage, CPU time).
+    *   `system`: metrics for the host OS (Load avg, Total RAM).
+
+### B. Queues (Workload)
+*   **Key**: `gravito:quasar:queues:{service_name}`
+*   **TTL**: 30 seconds
+*   **Purpose**: Snapshots of queue depths from various drivers.
+    *   Gravito Stream (Native)
+    *   Laravel Horizon (Redis)
+    *   BullMQ (Redis)
+    *   AWS SQS (API)
+
+### C. Insights (Performance)
+*   **Key**: `gravito:quasar:slow:{service_name}` (Stream)
+*   **Purpose**: Log requests or jobs that exceed performance thresholds.
+
+---
+
+## 4. Execution Roadmap
+
+### Phase 1: Foundation & Application Monitoring (Pulse Node)
+**Goal**: Establish the basic dashboard and Node.js SDK for monitoring application health (CPU/RAM).
+
+- [x] **Define Schema**: Update `PULSE_SPEC.md` with new Redis key patterns (`gravito:quasar:node:*`) and payload structure.
+- [x] **SDK Update**: Refactor `@gravito/quasar` (formerly pulse-node) to support:
+    - [x] Automatic runtime detection (Node, Bun, Deno).
+    - [x] System/Process split metrics.
+    - [x] Correct Redis namespacing.
+- [x] **Server Update**: Update Zenith's `PulseService` to scan new key patterns.
+- [x] **UI Overhaul**: Redesign `PulsePage` in Zenith:
+    - [x] Implement "Card" layout for nodes.
+    - [x] Rich metrics visualization (CPU/RAM split bars).
+    - [x] Add brand icons for runtimes (Node, Bun, Deno, PHP, Go, Python).
+    - [x] **Layout Optimization**: Compact Grid for Service Groups.
+
+---
+
+### Phase 2: Architecture Evolution - "The Brain-Hand Model" 🧠 🖐️ - **Completed** ✅
+To support advanced features like **Queue Insights** (Phase 2) and **Remote Control** (Phase 3), we are adopting a bidirectional architecture.
+
+*   **Metric Transport (The Mouth)**: Agent sends metrics to Zenith (via shared Redis).
+*   **Local Insight (The Eyes)**: Agent inspects *its own* environment (Local Redis, Local Queue) to gather data. Zenith doesn't need to connect to the App DB directly.
+*   **Command execution (The Hand)**: Zenith publishes commands (Retry/Delete), and Agent listens and executes them locally.
+
+#### Revised Phase 2: Application Insights (Queues) - **Completed** ✅
+**Goal**: Enable Quasar Agent to "see" local queues and report their status.
+
+- [x] **SDK Architecture**: Update `QuasarAgent` to handle **Dual Connections**:
+    - `transport`: Connection to Zenith (for sending heartbeat).
+    - `app`: Connection to Local App (for inspecting queues/bull/laravel).
+- [x] **Probe Implementation**: Create `QueueProbe` interface and implementations:
+    - `RedisListProbe`: Simple `LLEN` checks.
+    - [x] `BullProbe` (Future): Check `bull:*:waiting`, etc.
+    - [x] `LaravelProbe`: Check `queues:default`, `queues:reserved`, `queues:delayed`.
+- [x] **SDK API**: Expose `.monitorQueue(name, type)` method.
+- [x] **UI Update**: Update `NodeCard` to render a "Queues" section if queue data is present in payload.
+
+### Phase 3: Remote Control (Command & Control) - **Completed** ✅
+**Goal**: Allow Zenith to instruct Quasar to perform actions (Retry Job, Delete Job).
+
+- [x] **Protocol**: Define Command Protocol (Redis Pub/Sub: `gravito:quasar:cmd:{service}:{node_id}`).
+- [x] **Agent**: Implement `CommandListener` in SDK.
+- [x] **Command Executors**: Implement `RetryJobExecutor` and `DeleteJobExecutor`.
+- [x] **Security (Allowlist Strategy)**:
+    - [x] Implement **Command Allowlist** inside Agent code (only `RETRY_JOB`, `DELETE_JOB` allowed).
+    - [ ] (Future) Use **Redis ACL** (v6+) to restrict Agent's `transport` connection.
+- [x] **Server**: Add `CommandService` and `/api/pulse/command` endpoint.
+- [x] **UI**: Add "Retry/Delete" buttons in Zenith `PulsePage` for failed queue jobs.
+- [x] **Documentation**: Created `ALERTING_GUIDE.md` for configuration best practices.
+
+### Phase 4: Polyglot Agent - **Completed** ✅
+*   [x] Create `gravito-framework/quasar` repo (`quasar-go`).
+*   [x] Develop Go Agent core (utilizing `gopsutil`).
+    *   [x] System Probe (CPU/RAM)
+    *   [x] Agent heartbeat loop
+    *   [x] Config management (env vars)
+*   [x] Implement Queue Monitoring in Go Agent:
+    *   [x] Redis List Probe
+    *   [x] Laravel Queue Probe
+*   [x] Implement Remote Control in Go Agent:
+    *   [x] Command Listener (Pub/Sub)
+    *   [x] RETRY_JOB / DELETE_JOB Executors
+    *   [x] **Laravel Deep Integration**:
+        *   [x] `LARAVEL_ACTION` Executor (runs `artisan` safely).
+        *   [x] Auto-discovery of Laravel project root via process inspection.
+        *   [x] **Advanced Process Introspection**: Captures real-time CPU/RAM usage per Laravel Worker process.
+        *   [x] **Virtual Node Mapping**: Visualizes individual Laravel Workers as distinct nodes in Zenith UI.
+        *   [x] Support for `retry-all`, `retry {id}`, and `restart` (graceful worker reload).
+*   [x] Docker & Makefile setup.
+*   [x] Binary Release pipeline (GitHub Actions).
+*   [x] Publish to Docker Hub (`carllee/quasar-go-agent`).
+
+---
+
+## 5. Security & Access
+*   **Auth**: Agents authenticate via a shared secret (`QUASAR_TOKEN`) if writing to a remote Redis.
+*   **Isolation**: Process metrics only report what they have access to. System metrics require readable `/proc` (in Docker).

package/package.json

@@ -1,50 +1,54 @@
 {
-    "name": "@gravito/zenith",
-    "version": "0.1.0-beta.1",
-    "description": "Gravito Zenith: Zero-config control plane for Gravito Flux & Stream",
-    "type": "module",
-    "bin": {
-        "zenith": "./dist/bin.js",
-        "flux-console": "./dist/bin.js"
-    },
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "scripts": {
-        "dev:server": "bun run --watch src/server/index.ts",
-        "dev:client": "vite",
-        "build": "vite build && bun build ./src/server/index.ts ./src/bin.ts --outdir ./dist --target bun",
-        "start": "bun ./dist/bin.js",
-        "test": "bun test",
-        "seed": "bun scripts/seed.ts",
-        "worker": "bun scripts/worker.ts"
-    },
-    "dependencies": {
-        "@gravito/atlas": "workspace:*",
-        "@gravito/photon": "workspace:*",
-        "@gravito/stream": "workspace:*",
-        "@tanstack/react-query": "^5.0.0",
-        "clsx": "^2.1.1",
-        "date-fns": "^4.1.0",
-        "framer-motion": "^12.23.26",
-        "ioredis": "^5.0.0",
-        "lucide-react": "^0.562.0",
-        "react": "^19.0.0",
-        "react-dom": "^19.0.0",
-        "react-router-dom": "^7.11.0",
-        "recharts": "^3.6.0",
-        "tailwind-merge": "^3.4.0"
-    },
-    "devDependencies": {
-        "@types/react": "^19.0.0",
-        "@types/react-dom": "^19.0.0",
-        "@vitejs/plugin-react": "^5.1.2",
-        "autoprefixer": "^10.4.0",
-        "postcss": "^8.4.0",
-        "tailwindcss": "^3.4.0",
-        "typescript": "^5.0.0",
-        "vite": "^6.0.0"
-    },
-    "publishConfig": {
-        "access": "public"
-    }
+  "name": "@gravito/zenith",
+  "version": "1.0.0",
+  "description": "Gravito Zenith: Zero-config control plane for Gravito Flux & Stream",
+  "type": "module",
+  "bin": {
+    "zenith": "dist/bin.js",
+    "flux-console": "dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "dev:server": "bun run --watch src/server/index.ts",
+    "dev:client": "vite",
+    "build": "vite build && bun build ./src/server/index.ts ./src/bin.ts --outdir ./dist --target bun",
+    "start": "bun ./dist/bin.js",
+    "test": "bun test",
+    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
+    "seed": "bun scripts/seed.ts",
+    "worker": "bun scripts/worker.ts"
+  },
+  "dependencies": {
+    "@gravito/atlas": "workspace:*",
+    "@gravito/photon": "workspace:*",
+    "@gravito/quasar": "workspace:*",
+    "@gravito/stream": "workspace:*",
+    "@tanstack/react-query": "^5.0.0",
+    "clsx": "^2.1.1",
+    "date-fns": "^4.1.0",
+    "framer-motion": "^12.23.26",
+    "ioredis": "^5.0.0",
+    "lucide-react": "^0.562.0",
+    "nodemailer": "^7.0.12",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.11.0",
+    "recharts": "^3.6.0",
+    "tailwind-merge": "^3.4.0"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^7.0.4",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^5.1.2",
+    "autoprefixer": "^10.4.0",
+    "postcss": "^8.4.0",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/scripts/debug_redis_keys.ts

@@ -0,0 +1,24 @@
+import { Redis } from 'ioredis'
+
+const redis = new Redis('redis://localhost:6379')
+
+async function check() {
+  console.log('Connecting to Redis...')
+  try {
+    const keys = await redis.keys('gravito:quasar:node:*')
+    console.log('Keys found count:', keys.length)
+    console.log('Keys:', keys)
+
+    if (keys.length > 0) {
+      const val = await redis.get(keys[0])
+      console.log('--- Value of first key ---')
+      console.log(val)
+      console.log('--- End Value ---')
+    }
+  } catch (err) {
+    console.error('Redis Error:', err)
+  }
+  process.exit(0)
+}
+
+check()

package/specs/PULSE_SPEC.md

@@ -0,0 +1,86 @@
+# Gravito Pulse Implementation Spec
+
+## Overview
+Gravito Pulse is a lightweight APM (Application Performance Monitoring) system integrated into Zenith. It follows the philosophy: *"If you can connect to Redis, you are monitored."*
+
+## 1. Gravito Pulse Protocol (GPP)
+
+### Data Structure
+Pulse uses Redis keys with specific TTLs to represent live services.
+
+- **Key Pattern**: `gravito:quasar:node:{service}:{node_id}`
+- **TTL**: 30 seconds (Agents should heartbeat every 10-15s).
+- **Data Type**: String (JSON)
+
+### Payload Schema
+```json
+{
+  "id": "string",          // Unique Instance ID (e.g., UUID or Hostname-PID)
+  "service": "string",     // Group name (e.g., "worker-billing", "api-gateway")
+  "language": "string",    // "node" | "bun" | "deno" | "php" | "go" | "python" | "other"
+  "version": "string",     // Language/Runtime Version
+  "pid": "number",         // Process ID
+  "hostname": "string",    // Machine Hostname or Custom Name
+  "platform": "string",    // OS Platform (linux, darwin, win32)
+  "cpu": {
+     "system": "number",   // System Load % (0-100)
+     "process": "number",  // Process Usage % (0-100)
+     "cores": "number"     // Core count
+  },
+  "memory": {
+    "system": {
+        "total": "number", // System Total Memory (bytes)
+        "free": "number",  // System Free Memory (bytes)
+        "used": "number"   // System Used Memory (bytes)
+    },
+    "process": {
+        "rss": "number",      // Resident Set Size (bytes)
+        "heapTotal": "number",// Heap Total (bytes)
+        "heapUsed": "number"  // Heap Used (bytes)
+    }
+  },
+  "runtime": {
+    "uptime": "number",    // Process uptime in seconds
+    "framework": "string"  // Optional framework info
+  },
+  "timestamp": "number"    // Unix Ms Timestamp
+}
+```
+
+## 2. Implementation Modules
+
+### A. Client SDK (`@gravito/pulse-node`)
+A lightweight agent to collect metrics and publish to Redis.
+- **Dependencies**: `ioredis`, `pidusage` (optional, or use native `os`/`process`).
+- **Functionality**:
+    - `startPulse({ service: string })`: Starts the heartbeat loop.
+    - Collects CPU/RAM usage.
+    - Publishes to Redis.
+
+### B. Server Collector (Zenith Console)
+- **Service**: `PulseService`
+- **Method**: `getNodes()`
+    - Performs `SCAN 0 MATCH pulse:* COUNT 100`.
+    - Returns grouped nodes by `service`.
+- **API**: `GET /api/pulse/nodes`
+
+### C. Frontend Dashboard (Zenith UI)
+- **Route**: `/pulse`
+- **Components**:
+    - `ServiceGroup`: A container for nodes of a specific service.
+    - `NodeCard`: Displays CPU/RAM sparklines (optional) and current health.
+    - `HealthBadge`: Green (Fresh), Yellow (>15s ago), Red (Dead/Gone - though Redis TTL handles removal, frontend can handle stale UI).
+
+## 3. Alerts (Phase 2)
+- Server-side checker that monitors values from `PulseService`.
+- Triggers `AlertService` if:
+    - CPU > 90% for 2 mins.
+    - Memory > 90% for 5 mins.
+    - Disk < 10% free.
+
+## 4. Work Plan
+1. **Define Types**: Add `PulseNode` interface to `@gravito/custom-types` or `flux-console` shared types.
+2. **Implement Server Collector**: Create `PulseService` in `packages/flux-console/server/services`.
+3. **Implement API**: Add route in `packages/flux-console/server/routes.ts`.
+4. **Implement UI**: Create `PulsePage` and components.
+5. **Implement Node Client**: Add `startPulse` to `packages/stream` (or separate package) to verify "dogfooding" by having the server monitor itself.

package/src/client/App.tsx

@@ -8,6 +8,7 @@ import {
   LoginPage,
   MetricsPage,
   OverviewPage,
+  PulsePage,
   QueuesPage,
   SchedulesPage,
   SettingsPage,
@@ -48,6 +49,7 @@ function AuthenticatedRoutes() {
           <Route path="/schedules" element={<SchedulesPage />} />
           <Route path="/workers" element={<WorkersPage />} />
           <Route path="/metrics" element={<MetricsPage />} />
+          <Route path="/pulse" element={<PulsePage />} />
           <Route path="/settings" element={<SettingsPage />} />
         </Routes>
       </Layout>

package/src/client/Layout.tsx

@@ -90,6 +90,15 @@ export function Layout({ children }: LayoutProps) {
       }
     })
 
+    ev.addEventListener('pulse', (e) => {
+      try {
+        const data = JSON.parse(e.data)
+        window.dispatchEvent(new CustomEvent('flux-pulse-update', { detail: data }))
+      } catch (err) {
+        console.error('SSE Pulse Error', err)
+      }
+    })
+
     ev.onerror = (err) => {
       console.error('[Zenith] SSE Connection Error', err)
       ev.close()
@@ -339,6 +348,14 @@ export function Layout({ children }: LayoutProps) {
     return () => window.removeEventListener('keydown', handleKeyDown)
   }, [])
 
+  // Auto-scroll to selected item
+  useEffect(() => {
+    const el = document.getElementById(`command-item-${selectedIndex}`)
+    if (el) {
+      el.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+    }
+  }, [selectedIndex])
+
   const handleSelect = (cmd: CommandItem) => {
     cmd.action()
     setIsCommandPaletteOpen(false)
@@ -559,6 +576,7 @@ export function Layout({ children }: LayoutProps) {
                     {filteredCommands.map((cmd, i) => (
                       <button
                         type="button"
+                        id={`command-item-${i}`}
                         key={cmd.id}
                         className={cn(
                           'w-full flex items-center justify-between p-4 rounded-2xl transition-all cursor-pointer group/cmd outline-none',

package/src/client/Sidebar.tsx

@@ -23,10 +23,11 @@ export function Sidebar({ className, collapsed, toggleCollapse }: SidebarProps)
 
   const navItems = [
     { icon: LayoutDashboard, label: 'Overview', path: '/' },
+    { icon: Activity, label: 'Pulse', path: '/pulse' },
     { icon: ListTree, label: 'Queues', path: '/queues' },
     { icon: Clock, label: 'Schedules', path: '/schedules' },
     { icon: HardDrive, label: 'Workers', path: '/workers' },
-    { icon: Activity, label: 'Metrics', path: '/metrics' },
+    // { icon: Activity, label: 'Metrics', path: '/metrics' },
     { icon: Settings, label: 'Settings', path: '/settings' },
   ]