@gravito/zenith 0.1.0-beta.1 → 1.0.0

package/src/shared/types.ts

@@ -0,0 +1,99 @@
+export interface PulseCpu {
+  system: number // Percentage 0-100
+  process: number // Percentage 0-100
+  cores: number
+}
+
+export interface PulseMemory {
+  system: {
+    total: number // bytes
+    free: number // bytes
+    used: number // bytes
+  }
+  process: {
+    rss: number // bytes
+    heapTotal: number // bytes
+    heapUsed: number // bytes
+  }
+}
+
+export interface PulseRuntime {
+  uptime: number // seconds
+  framework: string // e.g. "Node 20.1", "Laravel 10.0"
+  status?: string
+  errors?: string[]
+}
+
+export interface QueueSnapshot {
+  name: string
+  driver: 'redis' | 'sqs' | 'rabbitmq'
+  size: {
+    waiting: number
+    active: number
+    failed: number
+    delayed: number
+  }
+  throughput?: {
+    in: number // jobs/min
+    out: number // jobs/min
+  }
+}
+
+export interface PulseNode {
+  id: string // Unique Instance ID
+  service: string // Group name
+  language: 'node' | 'bun' | 'deno' | 'php' | 'go' | 'python' | 'other'
+  version: string // App Version
+  pid: number
+  hostname: string
+  platform: string
+  cpu: PulseCpu
+  memory: PulseMemory
+  queues?: QueueSnapshot[]
+  runtime: PulseRuntime
+  meta?: any // Extra metadata like Laravel workers
+  timestamp: number // Last heartbeat
+}
+export interface AlertRule {
+  id: string
+  name: string
+  type: 'backlog' | 'failure' | 'worker_lost' | 'node_cpu' | 'node_ram'
+  threshold: number
+  queue?: string // Optional: specific queue or all
+  cooldownMinutes: number
+}
+
+export interface AlertEvent {
+  ruleId: string
+  timestamp: number
+  message: string
+  severity: 'warning' | 'critical'
+}
+
+export interface AlertConfig {
+  channels: {
+    slack?: {
+      enabled: boolean
+      webhookUrl: string
+    }
+    discord?: {
+      enabled: boolean
+      webhookUrl: string
+    }
+    email?: {
+      enabled: boolean
+      smtpHost: string
+      smtpPort: number
+      smtpUser: string
+      smtpPass: string
+      from: string
+      to: string // Comma separated list
+    }
+  }
+}
+
+export interface MaintenanceConfig {
+  autoCleanup: boolean
+  retentionDays: number
+  lastRun?: number // Timestamp
+}

package/tsconfig.json

@@ -1,10 +1,10 @@
 {
     "extends": "../../tsconfig.json",
     "compilerOptions": {
-        "target": "ES2020",
+        "target": "ESNext",
         "useDefineForClassFields": true,
         "lib": [
-            "ES2020",
+            "ESNext",
             "DOM",
             "DOM.Iterable"
         ],

package/ARCHITECTURE.md

@@ -1,88 +0,0 @@
-
-# 🏗️ Gravito Flux Console Architecture
-
-> The official, standalone visualization and management console for Gravito Flux & Stream.
-
-## 1. Project Manifesto
-
-- **Dogfooding First**: Uses `@gravito/photon` for HTTP serving and `@gravito/stream` for queue interaction.
-- **Zero-Config**: Should work out-of-the-box via `npx` with minimal arguments.
-- **Stateless**: The console itself holds no long-term state; Redis is the source of truth.
-- **Micro-Frontend Ready**: Built with React, matching the Gravito Admin ecosystem, but capable of running standalone.
-
-## 2. System Architecture
-
-```mermaid
-graph TD
-    CLI[CLI Entry (bin)] --> Boot[Bootstrapper]
-    Boot -->|Init| Server[Photon Server (Node/Bun)]
-    
-    subgraph "Backend Layer"
-        Server -->|Serve| API[Management API]
-        Server -->|Serve| Static[Frontend Assets]
-        
-        API -->|Command| QM[QueueManager (@gravito/stream)]
-        QM -->|Protocol| Redis[(Redis)]
-    end
-    
-    subgraph "Frontend Layer (React/Vite)"
-        UI[Dashboard UI] -->|Fetch| API
-    end
-```
-
-## 3. Technical Stack
-
-### Backend
-- **Runtime**: Bun / Node.js (Compat)
-- **Framework**: **`@gravito/photon`** (Hono wrapper)
-- **Data Access**: **`@gravito/stream`** (Directly uses QueueDrivers)
-- **Persistence**: **`MySQLPersistence`** / **`SQLitePersistence`** for long-term auditing.
-
-### Frontend
-- **Framework**: React 19
-- **Build Tool**: Vite
-- **Styling**: TailwindCSS (keeping consistent with `admin-shell`)
-- **State Management**: React Query (TanStack Query) for real-time polling.
-
-## 4. Key Features (Phase 1 MVP)
-
-### A. Dashboard
-- **System Overview**: Connection status, Driver type (Redis/Rabbit/Kafka).
-- **Throughput Metrics**: Jobs processed per second (calculated window).
-
-### B. Queue Management
-- **List Queues**: Show all active queues with counts (Waiting, Active, Failed).
-- **Inspect Queue**: View jobs in a paginated list.
-- **Job Detail**: View JSON payload and stack trace.
-
-### C. Actions
-- **Retry Job**: Move job from `failed` to `waiting`.
-- **Delete Job**: Remove job permanently.
-
-### D. Persistence & Auditing
-- **Job Archive**: Completed and Failed jobs move to SQL storage.
-- **Operational Log Archiving**: Persistent storage for system events and worker activities with history search.
-- **Hybrid Search**: Query both Redis (Live) and SQL (Archive) simultaneously.
-- **Retention Management**: Configurable auto-cleanup for historical data.
-
-### E. Alerting System
-- **Real-time Checks**: Monitoring for failure spikes and worker loss.
-- **Notifications**: Slack integration via Webhooks.
-- **Cool-down Logic**: Prevents duplicated alerts for the same event.
-
-## 5. Deployment Strategy
-
-The package is published as a standard NPM package. It contains a `bin` entry point.
-
-### Usage Scenarios
-1.  **Local Ad-hoc**: `npx @gravito/flux-console start --url redis://...`
-2.  **Project Integration**: Add to `package.json` scripts.
-3.  **Docker**: Official image wrapping the CLI.
-
-## 6. Development Workflow
-
-Since this is a monolithic package (Backend + Frontend):
-- `npm run dev` should start:
-    1.  Vite Dev Server (Frontend)
-    2.  Photon Watch Mode (Backend)
-- Backend should proxy `/` requests to Vite during development.

package/BATCH_OPERATIONS_IMPLEMENTATION.md

@@ -1,159 +0,0 @@
-# Batch Operations Implementation Summary
-
-## ✅ Completed Features
-
-### 1. Backend Enhancements
-
-#### New Service Methods (`QueueService.ts`)
-- **`getJobCount(queueName, type)`**: Get total count of jobs by type (waiting/delayed/failed)
-- **`deleteAllJobs(queueName, type)`**: Delete ALL jobs of a specific type from a queue
-- **`retryAllJobs(queueName, type)`**: Retry ALL jobs of a specific type (delayed or failed)
-
-#### New API Endpoints (`server/index.ts`)
-- **`GET /api/queues/:name/jobs/count`**: Returns total count of jobs by type
-- **`POST /api/queues/:name/jobs/bulk-delete-all`**: Deletes ALL jobs of a specific type
-- **`POST /api/queues/:name/jobs/bulk-retry-all`**: Retries ALL jobs of a specific type
-
-### 2. Frontend Enhancements
-
-#### New Component: `ConfirmDialog.tsx`
-- Reusable confirmation dialog with:
-  - Animated entrance/exit (Framer Motion)
-  - Loading state support
-  - Variant support (danger/warning/info)
-  - Customizable messages and buttons
-
-#### Enhanced `JobInspector` Component
-**State Management:**
-- `totalCount`: Tracks total jobs matching current view
-- `isProcessing`: Loading state for bulk operations
-- `confirmDialog`: Manages confirmation dialog state
-
-**New Features:**
-1. **Total Count Display**
-   - Fetches and displays total job count for non-archive views
-   - Shows "X of Y total" in the selection bar
-
-2. **"Select All Matching Query" UI**
-   - Warning banner when showing partial results
-   - "Delete All X" and "Retry All X" buttons
-   - Only shown when total count exceeds visible jobs
-
-3. **Confirmation Dialogs**
-   - Replaces browser `confirm()` with custom modal
-   - Shows job counts and queue names
-   - Warning emoji for destructive "ALL" operations
-   - Loading spinner during processing
-
-4. **Keyboard Shortcuts**
-   - **Ctrl+A / Cmd+A**: Select all visible jobs on current page
-   - **Escape**: Clear selection → Close dialog → Close inspector (cascading)
-
-5. **Improved UX**
-   - "Select All (Page)" label clarifies scope
-   - Total count shown next to checkbox
-   - Disabled state for processing operations
-   - Error handling with user-friendly messages
-
-### 3. Visual Enhancements
-
-- **Amber warning banner** for "Select All Matching" feature
-- **AlertCircle icon** for visual emphasis
-- **Loading spinners** in confirmation buttons
-- **Disabled states** prevent double-clicks
-- **Color-coded buttons**:
-  - Red for delete operations
-  - Amber for retry operations
-  - Primary color for standard actions
-
-## 🎯 User Workflows
-
-### Workflow 1: Bulk Delete Selected Jobs
-1. User opens JobInspector for a queue
-2. Clicks checkboxes to select specific jobs
-3. Clicks "Delete Selected" button
-4. Confirms in dialog
-5. Jobs are deleted, UI refreshes
-
-### Workflow 2: Delete ALL Jobs of a Type
-1. User opens JobInspector for a queue
-2. Switches to "failed" view (for example)
-3. Sees warning banner: "Showing 50 of 1,234 total failed jobs"
-4. Clicks "Delete All 1,234" button
-5. Sees strong warning dialog with ⚠️ emoji
-6. Confirms action
-7. ALL 1,234 failed jobs are deleted
-
-### Workflow 3: Keyboard Power User
-1. User opens JobInspector
-2. Presses **Ctrl+A** to select all visible jobs
-3. Presses **Delete** button
-4. Presses **Escape** to cancel dialog
-5. Presses **Escape** again to close inspector
-
-## 🔧 Technical Details
-
-### Backend Implementation
-- **Redis Operations**: Uses `LLEN`, `ZCARD` for counts; `DEL` for bulk deletion
-- **Atomic Operations**: Existing `retryDelayedJob()` and `retryAllFailedJobs()` reused
-- **Type Safety**: Full TypeScript support with proper type guards
-
-### Frontend Implementation
-- **React Hooks**: `useState`, `useEffect`, `useQuery` for state management
-- **TanStack Query**: Automatic cache invalidation after bulk operations
-- **Framer Motion**: Smooth animations for dialog entrance/exit
-- **Event Handling**: Keyboard event listeners with proper cleanup
-
-### Error Handling
-- Try-catch blocks around all API calls
-- User-friendly error messages
-- Console logging for debugging
-- Graceful degradation if API fails
-
-## 📊 Performance Considerations
-
-- **Lazy Loading**: Total count fetched only when needed
-- **Debouncing**: Could be added for rapid selection changes (future enhancement)
-- **Pagination**: Archive view supports pagination for large datasets
-- **Redis Efficiency**: Uses pipelined commands where possible
-
-## 🧪 Testing Recommendations
-
-- [ ] Test with 10, 100, 1,000+ jobs
-- [ ] Test keyboard shortcuts across browsers
-- [ ] Test confirmation dialog cancellation
-- [ ] Test error scenarios (network failures, Redis errors)
-- [ ] Test archive view (should not show "Delete All" buttons)
-- [ ] Test concurrent bulk operations
-- [ ] Test UI responsiveness during long operations
-
-## 📝 Documentation Updates
-
-- ✅ Updated `ROADMAP.md` to mark feature as completed
-- ✅ Added detailed task checklist
-- ✅ Included keyboard shortcuts in documentation
-
-## 🚀 Future Enhancements
-
-1. **Progress Indicators**: Show "Deleting 500/1000..." for large batches
-2. **Undo Functionality**: Temporary recovery window for accidental deletions
-3. **Bulk Edit**: Modify job data in bulk
-4. **Export/Import**: Export selected jobs to JSON, import later
-5. **Advanced Filters**: Select jobs by date range, error type, etc.
-6. **Bulk Scheduling**: Reschedule multiple delayed jobs at once
-
-## 🎉 Summary
-
-The Batch Operations feature is now **fully implemented** and **production-ready**. Users can:
-- Select multiple jobs with checkboxes
-- Perform bulk delete/retry on selected jobs
-- Delete/retry ALL jobs of a specific type with a single click
-- Use keyboard shortcuts for faster workflows
-- Get clear confirmation dialogs with loading states
-- See total counts and visual feedback throughout
-
-**Estimated Implementation Time**: ~3 hours
-**Actual Implementation Time**: ~2.5 hours
-**Lines of Code Added**: ~350 lines
-**Files Modified**: 4 files
-**New Files Created**: 2 files

package/EVOLUTION_BLUEPRINT.md

@@ -1,112 +0,0 @@
-# Gravito Zenith Evolution Blueprint
-**Target**: Zenith v2.0 - The Universal Application Control Plane
-**Core Philosophy**: Lightweight, Redis-Native, Language-Agnostic.
-
-## 🧭 Strategic Vision
-
-We aim to evolve Zenith from a **Queue Manager** into a **Lightweight Application Control Plane**. We will absorb the best features from industry leaders (Laravel Pulse, Sidekiq, BullMQ) while strictly avoiding their architectural pitfalls (heavy deps, SQL locks, language coupling).
-
----
-
-## 📅 Roadmap Structure
-
-### Phase 1: Deep Visibility (Queue Insights)
-**Focus**: Enhance the depth of information for the current Queue System.
-**Benchmarks**: Sidekiq, BullMQ.
-
-#### 1.1 Worker "X-Ray" Vision (The "Busy" State)
--   **Concept**: Instead of just showing "Busy", show *what* the worker is doing.
--   **Implementation**: Update Heartbeat Protocol to include `currentJobId` and `jobName`.
--   **UI**: Workers table shows "Processing: Order #1024 (SendEmail)".
--   **Benefit**: Instantly identify which job is hogging a worker.
--   **Difference**: Unlike Sidekiq which uses expensive extensive locking, we use ephemeral keys.
-
-#### 1.2 Enhanced Payload Inspector
--   **Concept**: Developer-friendly data inspection.
--   **Implementation**:
-    -   Syntax-highlighted JSON viewer with folding.
-    -   "Copy as cURL" or "Copy to Clipboard" actions.
-    -   Display stack traces with click-to-open (if local) potential.
--   **UX Rule**: Always lazy-load heavy payloads. Never fetch them in the list view.
-
-#### 1.3 Timeline Visualization (Gantt-lite)
--   **Concept**: Visualize concurrency.
--   **Implementation**: A canvas-based timeline showing job execution durations overlapping in time.
--   **Benefit**: Spot resource contention or gaps in processing.
-
----
-
-## Phase 2: System Pulse (Resource Monitoring)
-**Focus**: Lightweight APM (Application Performance Monitoring).
-**Benchmarks**: Laravel Pulse, PM2.
-
-#### 2.1 Gravito Pulse Protocol (GPP)
--   **Concept**: A standardized JSON structure for services to report health.
--   **Structure**: `pulse:{service}:{id}` (TTL 30s).
--   **Metrics**: CPU%, RAM (RSS/Heap), Disk Usage, Uptime, Event Loop Lag.
--   **Avoidance**: Do NOT store historical time-series data in SQL. Use Redis Lists/Streams with aggressive trimming (e.g., keep last 1 hour).
-
-#### 2.2 Grid Dashboard
--   **Concept**: Customizable "Mission Control" view.
--   **UI**: Drag-and-drop grid system.
--   **Widgets**:
-    -   Host Health (CPU/RAM guages).
-    -   Queue Backlog (Sparklines).
-    -   Exception Rate (Counter).
-    -   Slowest Routes (List).
-
-#### 2.3 Cross-Language Recorders
--   **Goal**: Provide simple SDKs.
-    -   `@gravito/recorder-node`: For Express/Hono/Nest.
-    -   `@gravito/recorder-php`: For Laravel/Symfony.
-    -   `@gravito/recorder-python`: For Django/FastAPI.
-
----
-
-## Phase 3: Intelligent Operations (Proactive Ops)
-**Focus**: Alerting and Anomaly Detection.
-**Benchmarks**: New Relic (Lite), Oban.
-
-#### 3.1 Outlier Detection (The "Slow" & "Error" Trap)
--   **Concept**: Only capture interesting data.
--   **Logic**:
-    -   If `duration > threshold`: Push to `pulse:slow_jobs`.
-    -   If `status >= 500`: Push to `pulse:exceptions`.
--   **Benefit**: Zero overhead for successful, fast requests.
-
-#### 3.2 Smart Alerting Engine
--   **Concept**: "Don't spam me."
--   **Features**:
-    -   **Thresholds**: "CPU > 90% for 5 minutes".
-    -   **Cooldown**: "Alert once per hour per rule".
-    -   **Channels**: Slack, Discord, Email, Webhook.
-
----
-
-## 🎨 UI/UX Unification Strategy
-
-To prevent "Feature Bloat" (UI Clutter), we will enforce strict design rules:
-
-### 1. Navigation Hierarchy
-Refactor Sidebar into logical groups:
--   **Dashboards** (Overview, System Pulse)
--   **Queues** (Active, Waiting, Delayed, Failed)
--   **Infrastructure** (Workers, Databases, Redis)
--   **Settings** (Alerts, API Keys)
-
-### 2. Contextual Density
--   **List View**: Minimal info (ID, Name, Status, Time).
--   **Detail Panel**: Slide-over panel for deep inspection (Payloads, Stack Traces, Logs).
--   **Avoidance**: Don't try to cram everything into the table rows.
-
-### 3. Unified Filters
--   Create a shared "Filter Bar" component (Date Range, Status, Queue Name) that works consistently across Logs, Jobs, and Pulse views.
-
----
-
-## ✅ Implementation Checklist (Next Steps)
-
-1.  **[ ] Protocol Definition**: Document `GPP` (Gravito Pulse Protocol).
-2.  **[ ] Backend Core**: Implement `SystemMonitor` service in Zenith.
-3.  **[ ] Frontend Core**: Create the `GridDashboard` component layout.
-4.  **[ ] Feature**: Implement `Worker X-Ray` (easiest win from Phase 1).

package/JOBINSPECTOR_SCROLL_FIX.md

@@ -1,152 +0,0 @@
-# JobInspector 滾動修復
-
-## 🐛 問題描述
-
-當佇列中有大量工作（例如 100+ 個）時，JobInspector 側邊欄會被撐得很高，導致：
-- 整個側邊欄超出螢幕高度
-- 無法看到底部的 "Dismiss" 按鈕
-- 需要滾動整個頁面才能查看所有內容
-- UX 體驗很差
-
-## ✅ 修復方案
-
-### 修改的 CSS 類別
-
-#### 1. 主容器 (`motion.div`)
-```tsx
-// 修改前
-className="bg-card border-l h-full w-full max-w-2xl shadow-2xl flex flex-col"
-
-// 修改後
-className="bg-card border-l h-screen max-h-screen w-full max-w-2xl shadow-2xl flex flex-col overflow-hidden"
-```
-
-**變更說明：**
-- `h-full` → `h-screen max-h-screen`: 明確限制高度為視窗高度
-- 新增 `overflow-hidden`: 防止內容溢出
-
-#### 2. 頂部標題區域
-```tsx
-// 修改前
-className="p-6 border-b flex justify-between items-center bg-muted/20"
-
-// 修改後
-className="p-6 border-b flex justify-between items-center bg-muted/20 flex-shrink-0"
-```
-
-**變更說明：**
-- 新增 `flex-shrink-0`: 防止標題區域被壓縮
-
-#### 3. 內容滾動區域
-```tsx
-// 修改前
-className="p-0 overflow-y-auto flex-1 bg-muted/5"
-
-// 修改後
-className="flex-1 overflow-y-auto bg-muted/5 min-h-0"
-```
-
-**變更說明：**
-- 移除 `p-0`（padding 由內部元素控制）
-- 新增 `min-h-0`: 允許 flex 子元素縮小到 0，確保滾動正常運作
-
-#### 4. 底部按鈕區域
-```tsx
-// 修改前
-className="p-4 border-t bg-card text-right"
-
-// 修改後
-className="p-4 border-t bg-card text-right flex-shrink-0"
-```
-
-**變更說明：**
-- 新增 `flex-shrink-0`: 防止按鈕區域被壓縮
-
-## 🎯 修復效果
-
-### 修復前
-```
-┌─────────────────────────────┐
-│ Header (標題區)              │ ← 正常
-├─────────────────────────────┤
-│ Job 1                       │
-│ Job 2                       │
-│ Job 3                       │
-│ ...                         │
-│ Job 98                      │
-│ Job 99                      │
-│ Job 100                     │ ← 超出螢幕
-├─────────────────────────────┤
-│ [Dismiss] 按鈕               │ ← 看不到
-└─────────────────────────────┘
-```
-
-### 修復後
-```
-┌─────────────────────────────┐
-│ Header (標題區)              │ ← 固定在頂部
-├─────────────────────────────┤
-│ Job 1                       │ ↕️
-│ Job 2                       │ ↕️
-│ Job 3                       │ ↕️ 可滾動區域
-│ ...                         │ ↕️
-│ Job 50                      │ ↕️
-├─────────────────────────────┤
-│ [Dismiss] 按鈕               │ ← 固定在底部
-└─────────────────────────────┘
-```
-
-## 📊 技術細節
-
-### Flexbox 佈局結構
-```
-motion.div (h-screen, flex flex-col, overflow-hidden)
-├─ Header (flex-shrink-0)          ← 不會被壓縮
-├─ Content (flex-1, overflow-y-auto, min-h-0) ← 可滾動，佔據剩餘空間
-└─ Footer (flex-shrink-0)          ← 不會被壓縮
-```
-
-### 關鍵 CSS 屬性
-
-1. **`h-screen max-h-screen`**: 限制容器高度為視窗高度
-2. **`overflow-hidden`**: 防止容器本身滾動
-3. **`flex-shrink-0`**: 防止 header 和 footer 被壓縮
-4. **`flex-1`**: 讓內容區域佔據所有剩餘空間
-5. **`overflow-y-auto`**: 只在內容區域啟用垂直滾動
-6. **`min-h-0`**: 允許 flex 子元素縮小（CSS flexbox 的特殊行為）
-
-## 🧪 測試驗證
-
-### 測試案例
-1. ✅ 打開有 100+ 工作的佇列
-2. ✅ 側邊欄高度固定為螢幕高度
-3. ✅ 工作列表可以滾動
-4. ✅ 頂部標題始終可見
-5. ✅ 底部 Dismiss 按鈕始終可見
-6. ✅ 滾動流暢，無卡頓
-
-### 測試步驟
-```bash
-# 1. 確保測試資料存在
-bun scripts/test-batch-operations.ts create
-
-# 2. 打開 Flux Console
-# http://localhost:3000
-
-# 3. 點擊 test-batch 佇列的 Inspect
-# 4. 確認可以看到頂部標題和底部按鈕
-# 5. 滾動工作列表，確認滾動流暢
-```
-
-## 📝 相關文件
-
-- `src/client/pages/QueuesPage.tsx` - JobInspector 元件
-- 修改行數: 255, 258, 294, 505
-
-## 🎉 總結
-
-這個修復確保了 JobInspector 在處理大量工作時：
-- ✅ 高度固定為螢幕高度
-- ✅ 內容區域可以獨立滾動
-- ✅ 頂部和底部區域始終可見
-- ✅ UX 體驗大幅改善