@gravito/zenith 1.0.1 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/zenith",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Gravito Zenith: Zero-config control plane for Gravito Flux & Stream",
   "type": "module",
   "bin": {

package/scripts/verify-throttle.ts

@@ -1,6 +1,8 @@
 console.log('🎧 Connecting to log stream...')
 const req = await fetch('http://localhost:3000/api/logs/stream')
-if (!req.body) throw new Error('No body')
+if (!req.body) {
+  throw new Error('No body')
+}
 
 const reader = req.body.getReader()
 const decoder = new TextDecoder()
@@ -16,7 +18,9 @@ console.log(`⏳ Measuring received logs for ${DURATION}ms...`)
 async function readStream() {
   while (true) {
     const { done, value } = await reader.read()
-    if (done) break
+    if (done) {
+      break
+    }
 
     const chunk = decoder.decode(value)
     // SSE format: event: log\ndata: ...\n\n

package/scripts/worker.ts

@@ -53,7 +53,8 @@ if (queuesRaw === 'all') {
 
 const failRate = parseFloat(process.argv.find((a) => a.startsWith('--fail='))?.split('=')[1] || '0')
 const processDelay = parseInt(
-  process.argv.find((a) => a.startsWith('--delay='))?.split('=')[1] || '100'
+  process.argv.find((a) => a.startsWith('--delay='))?.split('=')[1] || '100',
+  10
 )
 
 // Simple Job class for testing

package/src/client/Layout.tsx

@@ -42,6 +42,16 @@ interface CommandItem {
   category: 'Navigation' | 'System' | 'Action'
 }
 
+/**
+ * The main layout wrapper for the Zenith dashboard.
+ *
+ * It manages global state for the dashboard, including theme switching,
+ * the command palette (Ctrl+K), real-time event streaming (SSE),
+ * and the overall responsive structure.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function Layout({ children }: LayoutProps) {
   const navigate = useNavigate()
   const queryClient = useQueryClient()

package/src/client/Sidebar.tsx

@@ -18,6 +18,15 @@ interface SidebarProps {
   toggleCollapse: () => void
 }
 
+/**
+ * Sidebar navigation component for the Zenith dashboard.
+ *
+ * Provides links to various sections of the dashboard and supports
+ * a collapsible state to maximize screen space.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function Sidebar({ className, collapsed, toggleCollapse }: SidebarProps) {
   const location = useLocation()
 

package/src/client/ThroughputChart.tsx

@@ -15,6 +15,15 @@ interface ThroughputPoint {
   count: number
 }
 
+/**
+ * Real-time throughput visualization component.
+ *
+ * Displays a live-updating area chart of the number of jobs processed
+ * per minute across the system.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function ThroughputChart() {
   // Initial fetch via React Query
   const { data: initialData } = useQuery({

package/src/client/WorkerStatus.tsx

@@ -7,18 +7,20 @@ function cn(...inputs: ClassValue[]) {
 }
 
 function formatBytes(bytes: number) {
-  if (bytes === 0) return '0 B'
+  if (bytes === 0) {
+    return '0 B'
+  }
   const k = 1024
   const sizes = ['B', 'KB', 'MB', 'GB', 'TB']
   const i = Math.floor(Math.log(bytes) / Math.log(k))
-  return parseFloat((bytes / k ** i).toFixed(1)) + ' ' + sizes[i]
+  return `${parseFloat((bytes / k ** i).toFixed(1))} ${sizes[i]}`
 }
 
 function getWorkerName(id: string, pid: number) {
   // If ID contains Hostname+PID, try to simplify it
   // Example: CarldeMacBook-Air.local-99401
   const complexIdMatch = id.match(/^(.*)-(\d+)$/)
-  if (complexIdMatch && parseInt(complexIdMatch[2]) === pid) {
+  if (complexIdMatch && parseInt(complexIdMatch[2], 10) === pid) {
     // Return just the hostname part, and maybe truncate if too long
     let hostname = complexIdMatch[1]
     if (hostname.endsWith('.local')) {
@@ -51,6 +53,15 @@ interface WorkerInfo {
   }
 }
 
+/**
+ * Real-time worker node status visualization component.
+ *
+ * Displays a list of active worker nodes with their CPU, RAM, uptime metrics,
+ * and highlights a specific worker if provided.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function WorkerStatus({
   highlightedWorkerId,
   workers = [],

package/src/client/components/BrandIcons.tsx

@@ -1,5 +1,10 @@
 import type { SVGProps } from 'react'
 
+/**
+ * SVG icon for Node.js runtime.
+ * @public
+ * @since 3.0.0
+ */
 export function NodeIcon(props: SVGProps<SVGSVGElement>) {
   return (
     <svg
@@ -19,6 +24,11 @@ export function NodeIcon(props: SVGProps<SVGSVGElement>) {
   )
 }
 
+/**
+ * SVG icon for Bun runtime.
+ * @public
+ * @since 3.0.0
+ */
 export function BunIcon(props: SVGProps<SVGSVGElement>) {
   return (
     <svg
@@ -49,6 +59,11 @@ export function BunIcon(props: SVGProps<SVGSVGElement>) {
   )
 }
 
+/**
+ * SVG icon for Deno runtime.
+ * @public
+ * @since 3.0.0
+ */
 export function DenoIcon(props: SVGProps<SVGSVGElement>) {
   return (
     <svg
@@ -69,6 +84,11 @@ export function DenoIcon(props: SVGProps<SVGSVGElement>) {
   )
 }
 
+/**
+ * SVG icon for PHP runtime.
+ * @public
+ * @since 3.0.0
+ */
 export function PhpIcon(props: SVGProps<SVGSVGElement>) {
   return (
     <svg
@@ -95,6 +115,11 @@ export function PhpIcon(props: SVGProps<SVGSVGElement>) {
   )
 }
 
+/**
+ * SVG icon for Go runtime.
+ * @public
+ * @since 3.0.0
+ */
 export function GoIcon(props: SVGProps<SVGSVGElement>) {
   return (
     <svg
@@ -115,6 +140,11 @@ export function GoIcon(props: SVGProps<SVGSVGElement>) {
   )
 }
 
+/**
+ * SVG icon for Python runtime.
+ * @public
+ * @since 3.0.0
+ */
 export function PythonIcon(props: SVGProps<SVGSVGElement>) {
   return (
     <svg

package/src/client/components/ConfirmDialog.tsx

@@ -2,18 +2,42 @@ import { AnimatePresence, motion } from 'framer-motion'
 import { createPortal } from 'react-dom'
 import { cn } from '../utils'
 
+/**
+ * Props for the ConfirmDialog component.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface ConfirmDialogProps {
+  /** Whether the dialog is visible. */
   open: boolean
+  /** Dialog title text. */
   title: string
+  /** Detailed confirmation message. */
   message: string
+  /** Text for the confirmation button. @default 'Confirm' */
   confirmText?: string
+  /** Text for the cancel button. @default 'Cancel' */
   cancelText?: string
+  /** Callback triggered when user confirms the action. */
   onConfirm: () => void
+  /** Callback triggered when user cancels the action. */
   onCancel: () => void
+  /** Visual style of the confirmation button. @default 'danger' */
   variant?: 'danger' | 'warning' | 'info'
+  /** Whether an action is currently in progress (shows a spinner). @default false */
   isProcessing?: boolean
 }
 
+/**
+ * A modal dialog used for user confirmation before performing sensitive actions.
+ *
+ * It provides a consistent UI for confirmations across the Zenith dashboard
+ * and supports different visual variants.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function ConfirmDialog({
   open,
   title,

package/src/client/components/JobInspector.tsx

@@ -21,11 +21,29 @@ interface Job {
   _archivedAt?: string
 }
 
+/**
+ * Props for the JobInspector component.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface JobInspectorProps {
+  /** The name of the queue to inspect. */
   queueName: string
+  /** Callback triggered when the inspector is closed. */
   onClose: () => void
 }
 
+/**
+ * A detailed view for inspecting jobs within a specific queue.
+ *
+ * It provides tabs for viewing waiting, delayed, and failed jobs,
+ * as well as an archive search. Users can perform bulk actions like
+ * deleting or retrying jobs.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function JobInspector({ queueName, onClose }: JobInspectorProps) {
   const [view, setView] = React.useState<'waiting' | 'delayed' | 'failed' | 'archive'>('waiting')
   const [page, setPage] = React.useState(1)

package/src/client/components/LogArchiveModal.tsx

@@ -17,6 +17,15 @@ interface LogArchiveModalProps {
   onClose: () => void
 }
 
+/**
+ * A modal for exploring and searching historical application logs and job events.
+ *
+ * It provides advanced filtering by search query, time range, and severity level.
+ * Users can trace specific events across time and export the audit trail.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function LogArchiveModal({ isOpen, onClose }: LogArchiveModalProps) {
   const [page, setPage] = React.useState(1)
   const [search, setSearch] = React.useState('')
@@ -329,9 +338,49 @@ export function LogArchiveModal({ isOpen, onClose }: LogArchiveModalProps) {
 
             {/* Footer / Pagination */}
             <div className="p-4 border-t bg-muted/5 flex flex-col sm:flex-row justify-between items-center gap-4 text-[10px] uppercase font-bold text-muted-foreground">
-              <div>
-                Scanning {total.toLocaleString()} events • Page {page} of {totalPages || 1}
+              <div className="flex items-center gap-4">
+                <span>
+                  Scanning {total.toLocaleString()} events • Page {page} of {totalPages || 1}
+                </span>
+
+                <div className="h-4 w-px bg-border/50 hidden sm:block"></div>
+
+                {/* Export Controls */}
+                <div className="flex items-center gap-2">
+                  <select
+                    className="bg-background border border-border/50 rounded-lg px-2 py-1 outline-none focus:ring-1 focus:ring-primary/30"
+                    onChange={(e) => {
+                      // Trigger export
+                      const format = e.target.value
+                      const url = new URL('/api/logs/export', window.location.href)
+                      if (search) {
+                        url.searchParams.set('search', search)
+                      }
+                      if (status !== 'all') {
+                        url.searchParams.set('status', status)
+                      }
+                      if (dateRange.start) {
+                        url.searchParams.set('startTime', dateRange.start)
+                      }
+                      if (dateRange.end) {
+                        url.searchParams.set('endTime', dateRange.end)
+                      }
+                      url.searchParams.set('format', format)
+
+                      // For now, just open in new tab to trigger download
+                      window.open(url.toString(), '_blank')
+                    }}
+                    defaultValue=""
+                  >
+                    <option value="" disabled>
+                      Export As...
+                    </option>
+                    <option value="json">JSON</option>
+                    <option value="csv">CSV</option>
+                  </select>
+                </div>
               </div>
+
               <div className="flex items-center gap-2">
                 <button
                   type="button"

package/src/client/components/NotificationBell.tsx

@@ -13,6 +13,15 @@ import { useEffect, useRef, useState } from 'react'
 import { type Notification, useNotifications } from '../contexts/NotificationContext'
 import { cn } from '../utils'
 
+/**
+ * A notification bell icon component with a dropdown panel.
+ *
+ * Displays the unread notification count and provides a list view of recent
+ * system notifications with mark-as-read and clear-all functionality.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function NotificationBell() {
   const [isOpen, setIsOpen] = useState(false)
   const { notifications, unreadCount, markAsRead, markAllAsRead, clearAll, removeNotification } =

package/src/client/components/PageHeader.tsx

@@ -10,6 +10,15 @@ interface PageHeaderProps {
   className?: string
 }
 
+/**
+ * Reusable header component for Zenith dashboard pages.
+ *
+ * Provides a consistent layout for the page title, icon, description,
+ * and optional action buttons.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function PageHeader({
   icon: Icon,
   title,

package/src/client/components/Toaster.tsx

@@ -4,6 +4,16 @@ import { useEffect, useState } from 'react'
 import { useNotifications } from '../contexts/NotificationContext'
 import { cn } from '../utils'
 
+/**
+ * Global toast notification container for Zenith.
+ *
+ * Renders an animated stack of floating notifications in the corner of the
+ * screen. It integrates with the `NotificationContext` to display real-time
+ * alerts and messages.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function Toaster() {
   const { notifications, removeNotification } = useNotifications()
   const [activeIds, setActiveIds] = useState<Set<string>>(new Set())

package/src/client/components/UserProfileDropdown.tsx

@@ -5,6 +5,15 @@ import { useEffect, useRef, useState } from 'react'
 import { useNavigate } from 'react-router-dom'
 import { useAuth } from '../contexts/AuthContext'
 
+/**
+ * A user profile dropdown component for the Zenith dashboard.
+ *
+ * Displays current user information, system uptime, and provides access
+ * to settings and logout functionality.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function UserProfileDropdown() {
   const [isOpen, setIsOpen] = useState(false)
   const { isAuthEnabled, logout } = useAuth()

package/src/client/contexts/AuthContext.tsx

@@ -11,6 +11,12 @@ interface AuthContextType {
 
 const AuthContext = createContext<AuthContextType | null>(null)
 
+/**
+ * React hook to access authentication state and methods.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function useAuth() {
   const context = useContext(AuthContext)
   if (!context) {
@@ -23,6 +29,12 @@ interface AuthProviderProps {
   children: ReactNode
 }
 
+/**
+ * Provider component for managing global authentication state in Zenith.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function AuthProvider({ children }: AuthProviderProps) {
   const [isAuthenticated, setIsAuthenticated] = useState(false)
   const [isAuthEnabled, setIsAuthEnabled] = useState(false)

package/src/client/contexts/NotificationContext.tsx

@@ -1,12 +1,25 @@
 import { createContext, type ReactNode, useCallback, useContext, useEffect, useState } from 'react'
 
+/**
+ * Represents a system notification in the Zenith dashboard.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface Notification {
+  /** Unique notification ID. */
   id: string
+  /** The severity type of the notification. */
   type: 'info' | 'success' | 'warning' | 'error'
+  /** Short title for the notification. */
   title: string
+  /** Detailed notification message. */
   message: string
+  /** Epoch timestamp when the notification was created. */
   timestamp: number
+  /** Whether the notification has been read by the user. */
   read: boolean
+  /** Optional source identifier (e.g., a queue name). */
   source?: string
 }
 
@@ -22,6 +35,12 @@ interface NotificationContextType {
 
 const NotificationContext = createContext<NotificationContextType | null>(null)
 
+/**
+ * React hook to access the notification system.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function useNotifications() {
   const context = useContext(NotificationContext)
   if (!context) {
@@ -34,6 +53,12 @@ interface NotificationProviderProps {
   children: ReactNode
 }
 
+/**
+ * Provider component for managing global notifications in Zenith.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function NotificationProvider({ children }: NotificationProviderProps) {
   const [notifications, setNotifications] = useState<Notification[]>([])
 

package/src/client/pages/LoginPage.tsx

@@ -4,6 +4,15 @@ import { useState } from 'react'
 import { useAuth } from '../contexts/AuthContext'
 import { cn } from '../utils'
 
+/**
+ * The login page for the Zenith dashboard.
+ *
+ * Provides a secure, password-protected entry point to the administration
+ * console with modern UI effects and smooth animations.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function LoginPage() {
   const { login } = useAuth()
   const [password, setPassword] = useState('')

package/src/client/pages/MetricsPage.tsx

@@ -25,6 +25,15 @@ import {
 } from 'recharts'
 import { cn } from '../utils'
 
+/**
+ * System Metrics Page.
+ *
+ * Displays detailed performance analytics, throughput trends, and queue
+ * distribution charts using interactive visualizations.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function MetricsPage() {
   const [timeRange, setTimeRange] = React.useState<'15m' | '1h' | '6h' | '24h'>('15m')
 

package/src/client/pages/OverviewPage.tsx

@@ -347,6 +347,15 @@ function QueueList({
   )
 }
 
+/**
+ * System Overview Dashboard Page.
+ *
+ * Provides a high-level, real-time view of all processing pipelines,
+ * including job counts, worker status, and live operational logs.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function OverviewPage() {
   const [selectedQueue, setSelectedQueue] = React.useState<string | null>(null)
   const [hoveredWorkerId, setHoveredWorkerId] = React.useState<string | null>(null)

package/src/client/pages/PulsePage.tsx

@@ -394,6 +394,16 @@ function ServiceGroup({ service, nodes }: { service: string; nodes: PulseNode[]
   )
 }
 
+/**
+ * System Pulse Dashboard Page.
+ *
+ * Provides real-time resource monitoring (CPU, RAM) and service discovery
+ * for all connected Quasar agents. It also allows remote management of
+ * connected worker nodes.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function PulsePage() {
   const { data: initialData, isLoading } = useQuery<{ nodes: Record<string, PulseNode[]> }>({
     queryKey: ['pulse-nodes'],

package/src/client/pages/QueuesPage.tsx

@@ -26,6 +26,15 @@ interface QueueStats {
   paused?: boolean
 }
 
+/**
+ * Queue Management Page.
+ *
+ * Provides detailed monitoring and management controls for message queues,
+ * including job inspection, pausing/resuming queues, and bulk retry/purge actions.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function QueuesPage() {
   const [selectedQueue, setSelectedQueue] = React.useState<string | null>(null)
   const [searchQuery, setSearchQuery] = React.useState('')

package/src/client/pages/SchedulesPage.tsx

@@ -45,6 +45,15 @@ interface QueueListItem {
   paused: boolean
 }
 
+/**
+ * Task Schedules Page.
+ *
+ * View and manage all recurring jobs and cron tasks. Users can register new
+ * schedules, manually trigger execution, or delete existing schedules.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function SchedulesPage() {
   const queryClient = useQueryClient()
   const [isModalOpen, setIsModalOpen] = useState(false)

package/src/client/pages/SettingsPage.tsx

@@ -17,6 +17,15 @@ import {
 import React from 'react'
 import { cn } from '../utils'
 
+/**
+ * System Settings Page.
+ *
+ * Allows administrators to configure dashboard appearance, monitoring alerts,
+ * and data retention policies. It also provides system-level information.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function SettingsPage() {
   const queryClient = useQueryClient()
   const [showAddRule, setShowAddRule] = React.useState(false)

package/src/client/pages/WorkersPage.tsx

@@ -35,6 +35,16 @@ interface Worker {
   }
 }
 
+/**
+ * Worker Nodes Dashboard Page.
+ *
+ * Provides a detailed view of all active and inactive worker nodes in the
+ * cluster, including their resource usage, monitored queues, and Laravel
+ * worker status.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function WorkersPage() {
   const queryClient = useQueryClient()
   const { isPending, error, data } = useQuery<{ workers: Worker[] }>({

package/src/client/utils.ts

@@ -1,6 +1,15 @@
 import { type ClassValue, clsx } from 'clsx'
 import { twMerge } from 'tailwind-merge'
 
+/**
+ * Conditionally join class names and merge Tailwind CSS classes.
+ *
+ * @param inputs - A list of class values to be merged.
+ * @returns The merged class string.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }