@gravito/zenith 1.1.3 → 1.1.6

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "@gravito/zenith",
-  "version": "1.1.3",
+  "sideEffects": false,
+  "version": "1.1.6",
   "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",
+  "main": "./dist/server/index.js",
+  "exports": {
+    ".": "./dist/server/index.js",
+    "./bin": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "dev:server": "bun run --watch src/server/index.ts",
     "dev:client": "vite",
@@ -22,10 +30,10 @@
     "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'"
   },
   "dependencies": {
-    "@gravito/atlas": "^1.6.0",
-    "@gravito/photon": "^1.0.1",
-    "@gravito/quasar": "^1.3.0",
-    "@gravito/stream": "^2.0.2",
+    "@gravito/atlas": "^2.5.2",
+    "@gravito/photon": "^1.1.3",
+    "@gravito/quasar": "^1.3.2",
+    "@gravito/stream": "^2.1.1",
     "@tanstack/react-query": "^5.0.0",
     "clsx": "^2.1.1",
     "date-fns": "^4.1.0",
@@ -43,6 +51,7 @@
     "@types/nodemailer": "^7.0.4",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@types/node": "latest",
     "@vitejs/plugin-react": "^5.1.2",
     "autoprefixer": "^10.4.0",
     "postcss": "^8.4.0",

package/CHANGELOG.md

@@ -1,62 +0,0 @@
-# @gravito/zenith
-
-## 1.1.3
-
-### Patch Changes
-
-- Convert all workspace:\* dependencies to version numbers for npm publishing
-
-  - Fixed 144 workspace:\* dependencies across 58 packages
-  - Ensures all packages work properly when installed from npm
-  - Resolves issues with bunx and npm installation of CLI tools
-  - All internal dependencies now use explicit version constraints
-
-- Updated dependencies
-  - @gravito/photon@1.0.1
-  - @gravito/stream@2.0.2
-
-## 1.1.2
-
-### Patch Changes
-
-- Updated dependencies [905588f]
-  - @gravito/stream@2.0.1
-
-## 1.1.1
-
-### Patch Changes
-
-- Updated dependencies
-  - @gravito/atlas@2.1.0
-  - @gravito/stream@1.0.3
-
-## 1.1.0
-
-### Minor Changes
-
-- Implement several more examples and fix module issues, including:
-  - Support middleware in core route definitions.
-  - Improve Atlas driver loading and dependency injection.
-  - Add PostgreSQL support to Ecommerce MVC example.
-  - Fix internal type resolution issues across packages.
-
-### Patch Changes
-
-- Updated dependencies
-  - @gravito/atlas@1.2.0
-  - @gravito/quasar@1.2.0
-  - @gravito/stream@1.0.2
-
-## 1.0.1
-
-### Patch Changes
-
-- @gravito/stream@1.0.1
-
-## 1.0.0
-
-### Patch Changes
-
-- Updated dependencies
-  - @gravito/atlas@1.0.1
-  - @gravito/stream@1.0.0

package/Dockerfile

@@ -1,46 +0,0 @@
-# Use Bun official image
-FROM oven/bun:1.1.26 AS base
-WORKDIR /usr/src/app
-
-# ---- 1. Install Dependencies ----
-FROM base AS install
-# Copy root files
-COPY package.json bun.lock ./
-# Copy package.json files for workspace resolution
-COPY packages/photon/package.json ./packages/photon/
-COPY packages/stream/package.json ./packages/stream/
-COPY packages/flux-console/package.json ./packages/flux-console/
-
-# Install dependencies
-RUN bun install --frozen-lockfile
-
-# ---- 2. Build Stage ----
-FROM base AS build
-COPY --from=install /usr/src/app/node_modules ./node_modules
-COPY --from=install /usr/src/app/packages ./packages
-COPY . .
-
-# Build the console
-# This bundles the server and builds the client (Vite)
-RUN cd packages/flux-console && bun run build
-
-# ---- 3. Production Runner ----
-FROM base AS release
-WORKDIR /app
-
-# Copy built artifacts
-# Note: server and bin are bundled into dist/
-COPY --from=build /usr/src/app/packages/flux-console/dist ./dist
-COPY --from=build /usr/src/app/packages/flux-console/package.json ./package.json
-# Client source/assets are needed for the server to serve them
-COPY --from=build /usr/src/app/packages/flux-console/src/client ./src/client
-
-# Expose port
-EXPOSE 3000
-
-# Environment defaults
-ENV PORT=3000
-ENV NODE_ENV=production
-
-# Start the console
-CMD ["bun", "run", "dist/bin.js"]

package/Dockerfile.demo-worker

@@ -1,29 +0,0 @@
-# Use Bun official image
-FROM oven/bun:1.1.26 AS base
-WORKDIR /usr/src/app
-
-# ---- 1. Install Dependencies ----
-FROM base AS install
-COPY package.json bun.lock ./
-COPY packages/photon/package.json ./packages/photon/
-COPY packages/stream/package.json ./packages/stream/
-COPY packages/flux-console/package.json ./packages/flux-console/
-RUN bun install --frozen-lockfile
-
-# ---- 2. Copy Source ----
-FROM base AS build
-COPY --from=install /usr/src/app/node_modules ./node_modules
-COPY --from=install /usr/src/app/packages ./packages
-COPY . .
-
-# ---- 3. Runner ----
-FROM base AS release
-WORKDIR /usr/src/app
-COPY --from=build /usr/src/app ./
-
-# Env defaults
-ENV NODE_ENV=production
-
-# Start the demo worker
-# It uses the local packages/dist if available, but Bun can run TS directly
-CMD ["bun", "run", "packages/flux-console/scripts/demo-worker.ts"]

package/bin/flux-console.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env bun
-import '../src/server/index'

package/doc/ECOSYSTEM_EXPANSION_RFC.md

@@ -1,130 +0,0 @@
-# Zenith Ecosystem Expansion RFC
-
-**Status**: Draft
-**Date**: 2026-01-10
-**Goal**: Expand Zenith monitoring capabilities beyond Gravito/Laravel to Python, Node.js, and Go ecosystems.
-
----
-
-## 1. Executive Summary
-
-Gravito Zenith (Flux Console) is a unified control plane for background job processing. Currently, it supports **Gravito Stream** (Native) and **Laravel Queues** (via `laravel-zenith`). To become a true polyglot observability platform, we need to implement connectors for other popular queue systems.
-
-This RFC defines the **Universal Zenith Protocol (UZP)** and proposes implementation roadmaps for Python (Celery) and Node.js (BullMQ).
-
----
-
-## 2. The Universal Zenith Protocol (UZP)
-
-Any background job system can be monitored by Zenith if it implements the following Redis-based interfaces.
-
-### 2.1. Discovery (Heartbeat)
-Workers must announce their presence every 30 seconds to avoid being marked as "Offline".
-
-*   **Command**: `SETEX flux_console:worker:<worker_id> 60 <payload>`
-*   **Payload (JSON)**:
-    ```json
-    {
-      "id": "celery@worker-1",
-      "hostname": "pod-xyz",
-      "pid": 1234,
-      "uptime": 3600,
-      "queues": ["high", "default"],
-      "concurrency": 4,
-      "memory": { "rss": "50MB", "heapUsed": "N/A" },
-      "framework": "celery", // "laravel", "bullmq", "asynq"
-      "language": "python",  // "php", "typescript", "go"
-      "timestamp": "2026-01-10T12:00:00Z"
-    }
-    ```
-
-### 2.2. Event Stream (Logs)
-Workers publish lifecycle events to a shared Pub/Sub channel.
-
-*   **Command**: `PUBLISH flux_console:logs <payload>`
-*   **Payload (JSON)**:
-    ```json
-    {
-      "level": "info", // "info" (start), "success", "error"
-      "message": "Processing Task: tasks.send_email",
-      "workerId": "celery@worker-1",
-      "queue": "default",
-      "jobId": "uuid-v4",
-      "timestamp": "2026-01-10T12:00:01Z",
-      "metadata": {
-        "attempt": 1,
-        "latency": 45 // ms (for success/error events)
-      }
-    }
-    ```
-
-### 2.3. Metrics (Optional but Recommended)
-Connectors should increment counters for throughput aggregation.
-
-*   `INCR flux_console:metrics:processed`
-*   `INCR flux_console:metrics:failed`
-
----
-
-## 3. Implementation Plan: Python (Celery)
-
-**Target**: `gravito/zenith-celery` (PyPI Package)
-
-### Architecture
-Celery has a rich Signal system. We can hook into `worker_ready`, `task_prerun`, `task_success`, and `task_failure`.
-
-### Component Design
-1.  **ZenithMonitor**: A Celery Bootstep that starts a background thread for Heartbeats.
-2.  **SignalHandlers**:
-    *   `task_prerun`: Publish `level: info` log.
-    *   `task_success`: Publish `level: success` log + metrics.
-    *   `task_failure`: Publish `level: error` log with traceback.
-
-### Configuration
-```python
-# celery.py
-app.conf.zenith_redis_url = "redis://localhost:6379/0"
-app.conf.zenith_enabled = True
-```
-
----
-
-## 4. Implementation Plan: Node.js (BullMQ)
-
-**Target**: `@gravito/zenith-bullmq` (NPM Package)
-
-*Note: Gravito Stream is based on BullMQ principles but internal. This adapter allows *standard* BullMQ instances (e.g., in a NestJS app) to report to Zenith.*
-
-### Architecture
-BullMQ uses `QueueEvents` (which listens to Redis streams). A separate "Monitor" process is the best approach to avoid modifying the worker code too much.
-
-### Component Design
-1.  **ZenithMonitor Class**:
-    ```typescript
-    const monitor = new ZenithMonitor({
-      connection: redisOptions,
-      queues: ['email', 'reports']
-    });
-    monitor.start();
-    ```
-2.  It listens to BullMQ global events (completed, failed) and bridges them to UZP.
-3.  **Heartbeat**: Since BullMQ workers don't have a central registry, the Monitor acts as a "Virtual Worker" or we require users to instantiate a `ZenithWorker` wrapper.
-
----
-
-## 5. Implementation Plan: Go (Asynq)
-
-**Target**: `github.com/gravito-framework/zenith-asynq`
-
-### Architecture
-Asynq provides `Server` middleware.
-
-### Component Design
-1.  **Middleware**: `zenith.NewMiddleware(redisClient)`.
-2.  Wraps handler execution to capture Start/Success/Fail times.
-3.  Publishes to Redis asynchronously.
-
----
-
-## 6. Future Work: Rust (Faktory?)
-(To be determined based on demand)

package/docker-compose.yml

@@ -1,40 +0,0 @@
-version: '3.8'
-
-services:
-  # Main Persistence for Archive
-  mysql:
-    image: mysql:8.0
-    container_name: flux-mysql
-    ports:
-      - "3306:3306"
-    environment:
-      MYSQL_ROOT_PASSWORD: root
-      MYSQL_DATABASE: flux
-    healthcheck:
-      test: [ "CMD", "mysqladmin", "ping", "-h", "localhost" ]
-      timeout: 20s
-      retries: 10
-
-  # Real-time state store
-  redis:
-    image: redis:7-alpine
-    container_name: flux-redis
-    ports:
-      - "6379:6379"
-  # Flux Console (Optional: run locally via npm dev instead)
-  # console:
-  #   build: .
-  #   ports:
-  #     - "3000:3000"
-  #   environment:
-  #     - REDIS_URL=redis://redis:6379
-  #     - DB_DRIVER=mysql
-  #     - DB_HOST=mysql
-  #     - DB_USER=root
-  #     - DB_PASSWORD=root
-  #     - DB_NAME=flux
-  #   depends_on:
-  #     mysql:
-  #       condition: service_healthy
-  #     redis:
-  #       condition: service_started

package/docs/ALERTING_GUIDE.md

@@ -1,71 +0,0 @@
-# 🔔 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/DEPLOYMENT.md

@@ -1,157 +0,0 @@
-# Flux Console Deployment Guide
-
-This whitepaper outlines the recommended deployment strategies for Gravito Flux Console in various environments, from local development to enterprise-scale production clusters.
-
-## 1. Deployment Philosophy: "Zero-Config, Anywhere"
-
-Flux Console is designed to be infrastructure-agnostic. It acts as a stateless monitoring interface that connects to your existing infrastructure (Redis). It does not require its own dedicated database for basic operation.
-
-### Core Dependencies
-- **Runtime**: Node.js 18+ OR Bun 1.0+ (or use standard binary)
-- **Infrastructure**: Redis 6.0+ (Required for state coordination)
-- **Optional**: SQL Database (MySQL/PostgreSQL) for History Persistence (Future Feature)
-
----
-
-## 2. Deployment Scenarios
-
-### Scenario A: Local Development (The "NPM" Way)
-Best for individual developers debugging workers locally.
-
-**Prerequisites:** Node.js or Bun installed.
-
-```bash
-# S1. Run directly via npx (Zero Installation)
-npx @gravito/flux-console
-# Automatically detects local Redis at localhost:6379 and opens browser.
-
-# S2. Install globally for frequent use
-npm install -g @gravito/flux-console
-flux-console start
-```
-
-### Scenario B: Traditional VM / EC2 (The "Process" Way)
-Best for bare-metal servers or performance-critical environments where avoiding Docker overhead is desired.
-
-**Option 1: Node.js + PM2 (Recommended)**
-```bash
-# 1. Install globally
-npm install -g @gravito/flux-console pm2
-
-# 2. Start with PM2 for auto-restart and log management
-pm2 start flux-console --name flux-monitor -- --port 3000
-
-# 3. Configure Env Vars (if Redis is remote)
-pm2 set flux-monitor:env.REDIS_URL redis://prod-redis:6379
-```
-
-**Option 2: Standalone Binary (The "Go" Way)**
-*Ideal for restricted environments without Node.js installed.*
-1. Download the binary: `flux-console-linux-x64`
-2. `chmod +x ./flux-console-linux-x64`
-3. `./flux-console-linux-x64`
-
-### Scenario C: Docker & Container Platforms (The "Cloud-Native" Way)
-Best for Kubernetes, AWS ECS, Google Cloud Run, or simple Docker Compose setups.
-
-**1. Docker Run**
-```bash
-docker run -d \
-  -p 3000:3000 \
-  -e REDIS_URL=redis://your-redis-host:6379 \
-  -e AUTH_SECRET=my-super-secret-password \
-  --name flux-console \
-  gravito/flux-console:latest
-```
-
-**2. Docker Compose (Full Stack Example)**
-```yaml
-version: '3.8'
-services:
-  redis:
-    image: redis:alpine
-    ports:
-      - "6379:6379"
-
-  flux-console:
-    image: gravito/flux-console:latest
-    ports:
-      - "3000:3000"
-    environment:
-      - REDIS_URL=redis://redis:6379
-      - PORT=3000
-    depends_on:
-      - redis
-
-  # Your Application Workers
-  worker-orders:
-    build: .
-    command: npm run start:worker
-    environment:
-      - REDIS_URL=redis://redis:6379
-```
-
-**3. Kubernetes (K8s)**
-Deploy as a simple Deployment + Service.
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: flux-console
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app: flux-console
-  template:
-    metadata:
-      labels:
-        app: flux-console
-    spec:
-      containers:
-        - name: flux-console
-          image: gravito/flux-console:latest
-          env:
-            - name: REDIS_URL
-              valueFrom:
-                secretKeyRef:
-                  name: redis-secrets
-                  key: url
-          ports:
-            - containerPort: 3000
-```
-
----
-
-## 3. Security Best Practices
-
-Since Flux Console provides administrative capabilities (Pause Queue, Retry Job, Delete Job), security is paramount in production.
-
-1. **Network Isolation (Private VPC)**:
-   - **Recommendation**: Do NOT expose Flux Console to the public internet.
-   - Deploy it within your VPN / Private Subnet.
-   - Access via VPN or SSH Tunnel.
-
-2. **Authentication**:
-   - Enable built-in simple auth by setting `AUTH_PASSWORD` env var.
-   - For enterprise, put it behind an Identity Aware Proxy (e.g., Cloudflare Access, AWS ALB OIDC) to enforce SSO (Google/Okta) login.
-
-3. **Read-Only Mode (Future Feature)**:
-   - For giving access to support teams, run a separate instance with `READ_ONLY=true` env var (Roadmap item).
-
-## 4. Scaling (High Availability)
-
-Flux Console is **stateless**. You can run multiple instances behind a Load Balancer for high availability.
-
-- **Session Affinity**: Not required (JWT based Auth).
-- **Resource Usage**: Very low (mostly forwarding Redis data). A standard `t3.micro` or `256MB` container is usually sufficient for monitoring even large clusters.
-
----
-
-## 5. Troubleshooting
-
-**Common Issue: "Cannot connect to Redis"**
-- **Docker**: Ensure you use the service name (e.g., `redis`) not `localhost` if inside the same network. Host networking might be needed for accessing host Redis.
-- **AWS ElastiCache**: Ensure Security Groups allow traffic on port 6379 from the Console's security group.
-- **Encryption**: If Redis uses TLS (rediss://), ensure certificates are trusted or use `REDIS_TLS_REJECT_UNAUTHORIZED=0` (not recommended for prod).

package/docs/DOCS_INTERNAL.md

@@ -1,73 +0,0 @@
-# Internal Technical Documentation
-
-This document records technical implementations for Dead Letter Queues (DLQ) and Worker Metrics within the Flux system.
-
-## 1. Dead Letter Queue (DLQ)
-
-### Storage (Redis)
-Failed jobs are moved to a specific list with the suffix `:failed`.
-- **Key**: `{queue}:failed`
-- **Cap**: 1,000 items (capped via `LTRIM` in `RedisDriver.fail`).
-
-### Life Cycle
-1. `Worker` attempts to process a job.
-2. On failure, `Worker` calculates retry delay using `job.getRetryDelay(attempt)`.
-3. If `attempt >= maxAttempts`, `Consumer` catches the error.
-4. `Consumer` calls `QueueManager.fail(job, error)`.
-5. Driver pushes the job to the `:failed` list with `error` and `failedAt` metadata.
-
----
-
-## 2. Worker Metrics
-
-Workers report health metrics during their heartbeat cycle (default: every 5s).
-
-### Metric Payload Schema
-```json
-{
-  "cpu": 0.15,         // Load average (normalized by cores)
-  "ram": {
-    "rss": 120,        // Resident Set Size (MB)
-    "heapUsed": 45,    // V8 Heap Used (MB)
-    "heapTotal": 64    // V8 Heap Total (MB)
-  }
-}
-```
-
-### Storage
-In Redis, metrics are stored as part of the `flux_console:workers:{id}` hash.
-- **Field**: `metrics` (JSON string)
-
----
-
-## 3. Bulk Retry Logic (Lua)
-
-To ensure atomicity and performance, bulk retries of failed jobs use Lua scripts.
-
-### Retry All Script
-Moves all elements from `{queue}:failed` to `{queue}` then deletes the failed list.
-```lua
-local jobs = redis.call('LRANGE', KEYS[1], 0, -1)
-for i, job in ipairs(jobs) do
-  redis.call('RPUSH', KEYS[2], job)
-end
-redis.call('DEL', KEYS[1])
-return #jobs
-```
-
----
-
-## 4. System Logs & Archiving
-
-To maintain a permanent record of system events while keeping Redis memory usage low, Flux Console uses an asynchronous archiving pattern.
-
-### Live Logs (Redis)
-* **Key**: `flux_console:logs:system` (List)
-* **Strategy**: LILO (Last-In-Last-Out) capped at 100 items.
-* **Update**: Every `publishLog` call pushes to this list and trims it.
-
-### Persistent Archiving (SQL)
-* **Trigger**: Every `QueueService.publishLog` call asynchronously sends the log to the configured `PersistenceAdapter`.
-* **Table**: `flux_system_logs` (MySQL or SQLite).
-* **Search**: The `/api/logs/archive` endpoint performs direct SQL queries with filters on `level`, `worker_id`, `queue`, and `message` content.
-* **Retention**: Cleanup is handled via `PersistenceAdapter.cleanup`, removing logs older than the configured threshold (default: 30 days).