pm2-orbit 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PM2 Orbit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# PM2 Orbit
+
+> High-performance, real-time PM2 monitoring dashboard. Event-driven architecture supporting 1000+ processes with zero configuration.
+
+<!-- Add screenshot here: ![Dashboard](screenshot.png) -->
+
+## Why PM2 Orbit?
+
+Most PM2 dashboards poll the daemon every few hundred milliseconds, wasting resources and introducing latency. PM2 Orbit subscribes directly to PM2's event bus — updates arrive the instant they happen, with zero polling overhead.
+
+```bash
+npx pm2-orbit
+```
+
+That's it. No config files, no databases, no Docker required. Opens in your browser and starts monitoring.
+
+---
+
+## Features
+
+**Process Monitoring**
+- Real-time process status via WebSocket (online, stopped, errored, launching)
+- Virtualized table handling 1000+ processes at 60fps
+- Per-process CPU/memory sparklines with 120-point history
+- Cluster mode support with per-worker breakdown
+- One-click restart, stop, start, reload, delete for any process
+- Bulk actions: Restart All, Stop All, Start All, Delete All
+
+**Log Viewer**
+- Live SSE log tailing from PM2's event bus
+- ANSI escape code stripping for clean display
+- Per-process or merged view with color coding
+- Regex search with highlight
+- Pause/resume without disconnecting
+- Copy individual lines or download full buffer
+
+**System Metrics**
+- Host CPU, memory, load average, network I/O, disk I/O
+- Auto-collecting via `systeminformation` with smart caching
+- Historical charts with 1h / 6h / 24h time ranges
+
+**Alert Engine**
+- Rule-based alerts: CPU > N%, memory > NMB, restarts > N, process offline
+- Multi-channel notifications: Slack, Discord, webhook, email, browser push
+- Per-rule channel configuration with enable/disable toggles
+- Cooldown to prevent alert fatigue
+- Alert history with severity levels
+
+**Developer Experience**
+- Keyboard shortcuts: `R` restart, `S` stop, `End` scroll to bottom, `Ctrl+K` command palette
+- Command palette for fuzzy process search and quick actions
+- Dark / Light / System theme with smooth transitions
+- Export/import settings as JSON
+
+---
+
+## Install
+
+```bash
+# One command — installs pm2 automatically if missing
+npm install -g pm2-orbit
+pm2-orbit
+```
+
+Or run without installing:
+
+```bash
+npx pm2-orbit
+```
+
+---
+
+## CLI Options
+
+```
+pm2-orbit [options]
+
+Options:
+  -p, --port <port>     Port to listen on (default: 9823)
+  -H, --host <host>     Host to bind to (default: 127.0.0.1)
+  -t, --theme <theme>   Theme: dark | light | system
+  -n, --no-open         Don't open browser on start
+  -h, --help            Show help
+  -v, --version         Show version
+
+Examples:
+  pm2-orbit                      # Start on default port
+  pm2-orbit -p 3000              # Start on port 3000
+  pm2-orbit --host 0.0.0.0       # Allow remote access
+  pm2-orbit --no-open            # Don't open browser
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PM2_ORBIT_PORT` | Server port | `9823` |
+| `PM2_ORBIT_TOKEN` | Bearer auth token (required for non-localhost) | — |
+| `PM2_ORBIT_LOG_BUFFER` | Max log lines per process | `2000` |
+| `LOG_LEVEL` | Logger level: `debug`, `info`, `warn`, `error` | `info` |
+| `CORS_ORIGINS` | Comma-separated allowed origins | `http://127.0.0.1:9823,http://localhost:9823` |
+
+### Notification Channels
+
+Notifications can be configured via environment variables **or** the Settings UI (accessible at `/settings` in the browser). The Settings UI saves to `~/.pm2-orbit/settings.json` and applies values at startup.
+
+| Variable | Description |
+|----------|-------------|
+| `SLACK_WEBHOOK_URL` | Slack incoming webhook URL |
+| `DISCORD_WEBHOOK_URL` | Discord webhook URL |
+| `WEBHOOK_URL` | Generic POST webhook URL |
+| `SMTP_HOST` | SMTP server hostname |
+| `SMTP_PORT` | SMTP port (default: 587) |
+| `SMTP_USER` | SMTP username |
+| `SMTP_PASS` | SMTP password |
+| `SMTP_FROM` | Sender email address |
+| `SMTP_TO` | Recipient email address |
+| `NOTIFY_*_ENABLED` | Set to `0` to disable a channel (e.g., `NOTIFY_SLACK_ENABLED=0`) |
+
+---
+
+## Docker
+
+```bash
+# Build
+docker build -t pm2-orbit .
+
+# Run (mount PM2 socket for process access)
+docker run -p 9823:9823 -v /run/pm2.sock:/run/pm2.sock pm2-orbit
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/ihssmaheel-dev/pm2-orbit.git
+cd pm2-orbit
+npm install
+npm run dev
+```
+
+Starts Vite dev server on port 5151 with API proxy to the backend on port 9823.
+
+### Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start dev mode (UI + server with hot reload) |
+| `npm run build` | Build for production |
+| `npm start` | Start production server |
+| `npm run lint` | Type-check backend |
+| `npm run typecheck` | Type-check both backend and frontend |
+| `npm test` | Run tests |
+
+---
+
+## Architecture
+
+```
+PM2 Daemon
+    │
+    │ pm2.launchBus() — event-driven, zero polling
+    ▼
+PM2 Bridge
+    │
+    ├──► Event Pipeline (batched, debounced)
+    │
+    ├──► Circular Buffer (120 points × typed arrays)
+    │
+    ├──► Alert Engine (rule evaluation, per-process indexed)
+    │
+    ├──► SQLite Store (optional, 24h retention)
+    │
+    └──► WebSocket Broadcaster
+              │
+              ▼
+         React Frontend
+              │
+              ├──► Zustand Store (single source of truth)
+              ├──► Virtual Table (1000+ rows)
+              ├──► Log Viewer (SSE + virtual scroll)
+              └──► Charts (uPlot, canvas-rendered)
+```
+
+### Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Runtime** | Node.js 18+ |
+| **HTTP** | Fastify 5 |
+| **WebSocket** | ws |
+| **PM2 Integration** | `pm2.launchBus()` event subscription |
+| **Metrics** | `systeminformation` |
+| **Persistence** | better-sqlite3 (optional) |
+| **Frontend** | React 19, Tailwind CSS, Zustand |
+| **Virtualization** | TanStack Virtual |
+| **Charts** | uPlot |
+| **Build** | esbuild (backend), Vite (frontend) |
+
+---
+
+## Security
+
+- Bearer token authentication via `PM2_ORBIT_TOKEN`
+- CORS locked to localhost by default
+- Rate limiting: 100 requests/minute per IP
+- WebSocket connection limiting: 5 per IP
+- Helmet security headers (XSS, CSP, HSTS)
+- Environment variables masked in UI by default
+- Process name sanitization in file paths
+- Request ID tracking for audit trails
+
+---
+
+## License
+
+[MIT](LICENSE)

package/bin/pm2-orbit.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+'use strict';
+
+const mri = require('mri');
+const path = require('path');
+const fs = require('fs');
+
+const args = mri(process.argv.slice(2), {
+  alias: {
+    port: 'p',
+    theme: 't',
+    'no-open': 'n',
+    help: 'h',
+    version: 'v',
+    host: 'H',
+  },
+  default: {
+    port: parseInt(process.env.PM2_ORBIT_PORT || '9823', 10),
+    'no-open': false,
+    host: '127.0.0.1',
+  },
+  boolean: ['no-open', 'help', 'version'],
+  string: ['port', 'theme', 'host'],
+});
+
+if (args.help) {
+  console.log(`
+  PM2 Orbit — High-performance PM2 monitoring dashboard
+
+  Usage:
+    $ pm2-orbit [options]
+
+  Options:
+    --port, -p       Port to listen on (default: 9823)
+    --host, -H       Host to bind to (default: 127.0.0.1)
+    --no-open, -n    Don't open browser automatically
+    --theme, -t      Force theme (dark|light|system)
+    --help, -h       Show this help
+    --version, -v    Show version
+
+  Examples:
+    $ pm2-orbit                    # Start on default port
+    $ pm2-orbit -p 3000            # Start on port 3000
+    $ pm2-orbit --host 0.0.0.0     # Allow remote access
+    $ pm2-orbit --no-open          # Don't open browser
+  `);
+  process.exit(0);
+}
+
+if (args.version) {
+  console.log(require('../package.json').version);
+  process.exit(0);
+}
+
+// Check and auto-install pm2 if missing
+function checkDependency(name, installCmd) {
+  try {
+    require.resolve(name);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function installDependency(name, label) {
+  console.log(`\n  \x1b[33m⚠\x1b[0m ${label} not found. Installing...`);
+  try {
+    const { execSync } = require('child_process');
+    execSync(`npm install -g ${name}`, { stdio: 'inherit', timeout: 120000 });
+    console.log(`  \x1b[32m✓\x1b[0m ${label} installed successfully\n`);
+    return true;
+  } catch (err) {
+    console.error(`  \x1b[31m✗\x1b[0m Failed to install ${label}: ${err.message}`);
+    console.log(`  Please install manually: npm install -g ${name}\n`);
+    return false;
+  }
+}
+
+// Check dependencies
+if (!checkDependency('pm2')) {
+  if (!installDependency('pm2', 'PM2')) {
+    process.exit(1);
+  }
+}
+
+if (!checkDependency('better-sqlite3')) {
+  installDependency('better-sqlite3', 'better-sqlite3 (optional, for persistence)');
+}
+
+// Set theme from CLI
+if (args.theme) process.env.PM2_ORBIT_THEME = args.theme;
+
+// Set host from CLI
+if (args.host) process.env.PM2_ORBIT_HOST = args.host;
+
+async function main() {
+  const pkg = require('../package.json');
+  console.log('');
+  console.log('  \x1b[36mPM2 Orbit\x1b[0m v' + pkg.version);
+  console.log('  \x1b[90mHigh-performance PM2 monitoring dashboard\x1b[0m');
+  console.log('');
+
+  const { createServer } = require('../dist/server');
+  const server = await createServer({ port: args.port });
+  await server.listen({ port: args.port, host: args.host });
+
+  const url = `http://${args.host === '127.0.0.1' ? 'localhost' : args.host}:${args.port}`;
+  console.log(`  \x1b[32m→\x1b[0m ${url}`);
+  console.log('');
+
+  if (!args['no-open']) {
+    try {
+      const { default: open } = await import('open');
+      await open(url);
+    } catch {
+      // open failed — non-critical
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('\n  \x1b[31mPM2 Orbit failed to start:\x1b[0m', err.message);
+  process.exit(1);
+});