bs9 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BS9 (Bun Sentinel 9)
+
+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,532 @@
+# BS9 (Bun Sentinel 9)
+
+> Mission-critical process manager CLI with real-time monitoring dashboard, historical metrics storage, alert system, container support, and enterprise-grade security.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# One-click installer (installs Bun + BS9)
+curl -fsSL https://raw.githubusercontent.com/xarhang/bs9/main/setup.sh | bash
+
+# Or manual install
+git clone https://github.com/xarhang/bs9.git
+cd bs9
+bun install
+cp bin/bs9 ~/.local/bin/bs9
+chmod +x ~/.local/bin/bs9
+```
+
+---
+
+## 📋 Complete CLI Commands
+
+### Service Management
+```bash
+# Start service with TypeScript JIT/AOT support
+bs9 start app.js                    # JavaScript app
+bs9 start app.ts --build          # TypeScript AOT compilation
+bs9 start app.ts --name myapp --port 8080 --env NODE_ENV=production
+
+# Service lifecycle
+bs9 stop myapp
+bs9 restart myapp
+bs9 status                         # SRE metrics dashboard
+bs9 logs myapp --follow
+```
+
+### Monitoring & Observability
+```bash
+# Real-time terminal dashboard
+bs9 monit                         # 2s refresh default
+bs9 monit --refresh 5              # Custom refresh interval
+
+# Web-based dashboard
+bs9 web --port 8080               # Start web dashboard
+bs9 web --detach --port 8080       # Run in background
+
+# Alert management
+bs9 alert --list                   # Show alert configuration
+bs9 alert --cpu 80 --memory 85      # Set thresholds
+bs9 alert --webhook https://hooks.slack.com/...
+bs9 alert --test                   # Test webhook
+
+# Historical data
+bs9 export --format json --hours 24 # Export metrics
+bs9 export --service myapp --format csv
+```
+
+---
+
+## 🎯 Key Features
+
+### 🔍 Real-time Monitoring
+- **Terminal Dashboard**: Live terminal UI with color-coded status
+- **Web Dashboard**: Browser-based monitoring with auto-refresh
+- **Health Checks**: Automatic `/healthz`, `/readyz`, `/metrics` endpoints
+- **SRE Metrics**: CPU, Memory, Uptime, Task tracking
+
+### 📊 Historical Metrics Storage
+- **Local Storage**: JSON-based metrics storage in `~/.config/bs9/metrics/`
+- **Data Export**: JSON and CSV export formats
+- **Time-based Queries**: Filter by hours/days
+- **Aggregated Analytics**: CPU/Memory averages, uptime calculations
+
+### 🔔 Advanced Alert System
+- **Configurable Thresholds**: CPU, Memory, Error Rate, Uptime
+- **Webhook Notifications**: HTTP webhook support for alerts
+- **Service-specific Configs**: Per-service alert settings
+- **Cooldown Period**: Prevent alert spam
+- **Alert Testing**: Webhook connectivity validation
+
+### 🐳 Container & Orchestration
+- **Docker Support**: Complete Dockerfile and docker-compose setup
+- **Kubernetes**: Full K8s deployment with ServiceMonitor
+- **Health Checks**: Container health endpoints
+- **Resource Limits**: Memory and CPU constraints
+- **Security Policies**: PodSecurityPolicy, RBAC
+
+### 🛡️ Enterprise Security
+- **Pre-start Audit**: Scan for eval(), child_process.exec(), etc.
+- **User-mode Systemd**: Zero root operation required
+- **Systemd Hardening**: PrivateTmp, ProtectSystem, NoNewPrivileges
+- **Resource Limits**: CPU, memory, file descriptor limits
+- **Port Warnings**: Alert for privileged ports (< 1024)
+
+### ⚡ TypeScript JIT/AOT Support
+- **JIT Mode**: Run `.ts` files directly (default)
+- **AOT Mode**: Compile to optimized JS for production (`--build`)
+- **Performance**: Faster startup vs runtime optimization
+- **Build Directory**: `.bs9-build/` for compiled artifacts
+
+---
+
+## 📊 Monitoring Dashboards
+
+### Terminal Dashboard (`bs9 monit`)
+```
+🔍 BS9 Real-time Monitoring Dashboard
+========================================================================================================================
+Refresh: 2s | Last update: 12:23:45 AM | Press Ctrl+C to exit
+
+SERVICE              STATE           HEALTH    CPU       MEMORY     UPTIME      TASKS   DESCRIPTION
+------------------------------------------------------------------------------------------------------------------------
+myapp                active/running   ✅ OK      12.3ms    45.2MB     2h 15m      3       BS9 Service: myapp
+api                  active/running   ✅ OK      8.1ms     32.1MB     1h 42m      2       BS9 Service: api
+webapp               failed/failed    ❌ FAIL    -         -          -           -       BS9 Service: webapp
+
+========================================================================================================================
+📊 Summary: 2/3 services running | Total Memory: 77.3MB | Services: 3
+
+⚠️  ALERTS:
+   Failed services: webapp
+   Unhealthy services: webapp
+```
+
+### Web Dashboard (`bs9 web`)
+- **Modern UI**: Responsive web interface
+- **Real-time Updates**: Auto-refresh every 5 seconds
+- **Service Cards**: Visual status indicators
+- **Metrics Charts**: CPU, Memory, Uptime graphs
+- **Historical Data**: View trends over time
+- **Alert Status**: Current alert configuration
+
+---
+
+## 🔧 Alert Configuration
+
+### Global Alert Settings
+```bash
+# Configure global thresholds
+bs9 alert --cpu 80 --memory 85 --errorRate 5 --uptime 95
+bs9 alert --webhook https://hooks.slack.com/services/...
+bs9 alert --cooldown 300  # 5 minutes cooldown
+```
+
+### Service-specific Alerts
+```bash
+# Configure alerts for specific service
+bs9 alert --service myapp --cpu 90 --memory 90
+bs9 alert --service critical-app --enable
+bs9 alert --service test-app --disable
+```
+
+### Alert Management
+```bash
+# View current configuration
+bs9 alert --list
+
+# Test webhook connectivity
+bs9 alert --test
+
+# Enable/disable alerts
+bs9 alert --enable
+bs9 alert --disable
+```
+
+---
+
+## 📈 Historical Metrics
+
+### Data Storage
+- **Location**: `~/.config/bs9/metrics/`
+- **Format**: JSON files with timestamp naming
+- **Retention**: Automatic cleanup (1000 snapshots)
+- **Compression**: Efficient JSON storage
+
+### Export Options
+```bash
+# Export all metrics (last 24 hours)
+bs9 export --format json --hours 24
+
+# Export specific service
+bs9 export --service myapp --format csv --hours 48
+
+# Custom output file
+bs9 export --format json --output my-metrics.json
+```
+
+### Data Analysis
+```bash
+# Get aggregated metrics
+const storage = new MetricsStorage();
+const metrics = storage.getAggregatedMetrics(24); // Last 24 hours
+console.log(`Average CPU: ${metrics.avgCpu}ms`);
+console.log(`Average Memory: ${metrics.avgMemory}B`);
+console.log(`Uptime: ${metrics.uptime}%`);
+```
+
+---
+
+## 🐳 Docker Deployment
+
+### Quick Start
+```bash
+# Build and run with Docker Compose
+docker-compose up -d
+
+# Access services
+# Web Dashboard: http://localhost:8080
+# Grafana: http://localhost:3001
+# Prometheus: http://localhost:9090
+```
+
+### Dockerfile Features
+- **Multi-stage**: Optimized production builds
+- **Security**: Non-root user, read-only filesystem
+- **Health Checks**: Built-in health endpoints
+- **Resource Limits**: Memory and CPU constraints
+
+### Docker Compose Stack
+- **BS9 Manager**: Main process manager
+- **Prometheus**: Metrics collection
+- **Grafana**: Visualization dashboard
+- **Persistent Storage**: Data volumes for metrics
+
+---
+
+## ☸️ Kubernetes Deployment
+
+### Quick Deploy
+```bash
+# Deploy to Kubernetes
+kubectl apply -f src/k8s/bs9-deployment.yaml
+
+# Check deployment
+kubectl get pods -n bs9-system
+kubectl get services -n bs9-system
+```
+
+### K8s Features
+- **Namespace Isolation**: `bs9-system` namespace
+- **Service Monitor**: Prometheus integration
+- **Security**: PodSecurityPolicy, RBAC
+- **Health Checks**: Liveness and readiness probes
+- **Resource Limits**: Memory and CPU constraints
+
+---
+
+## 🔄 Migration from PM2
+
+| PM2 Command | BS9 Equivalent | Enhanced Features |
+|-------------|----------------|------------------|
+| `pm2 start app.js` | `bs9 start app.js` | Security audit, systemd hardening |
+| `pm2 stop app` | `bs9 stop app` | User-mode operation |
+| `pm2 restart app` | `bs9 restart app` | Health monitoring |
+| `pm2 list` | `bs9 status` | SRE metrics dashboard |
+| `pm2 logs app` | `bs9 logs app` | Journalctl integration |
+| `pm2 monit` | `bs9 monit` | Enhanced terminal dashboard |
+| - | `bs9 web` | Web-based dashboard |
+| - | `bs9 alert` | Alert system with webhooks |
+| - | `bs9 export` | Historical metrics |
+
+---
+
+## 🛠️ Configuration
+
+### BS9 Config (`~/.config/bs9/config.toml`)
+```toml
+[default]
+port = 3000
+otel_enabled = true
+prometheus_enabled = true
+environment = "production"
+
+[security]
+security_audit = true
+block_eval = true
+block_child_process_exec = true
+block_fs_access = true
+
+[monitoring]
+refresh_interval = 2
+health_check_timeout = 1000
+
+[logging]
+level = "info"
+structured = true
+```
+
+### Alert Config (`~/.config/bs9/alerts.json`)
+```json
+{
+  "enabled": true,
+  "webhookUrl": "https://hooks.slack.com/services/...",
+  "thresholds": {
+    "cpu": 80,
+    "memory": 85,
+    "errorRate": 5,
+    "uptime": 95
+  },
+  "cooldown": 300,
+  "services": {
+    "myapp": {
+      "enabled": true,
+      "customThresholds": {
+        "cpu": 90
+      }
+    }
+  }
+}
+```
+
+---
+
+## 📚 Examples
+
+### Simple JavaScript App
+```javascript
+// examples/simple-app.js
+import { serve } from "bun";
+
+serve({
+  port: process.env.PORT || 3000,
+  fetch(req) {
+    const url = new URL(req.url);
+    
+    if (url.pathname === "/healthz") return new Response("ok");
+    if (url.pathname === "/readyz") return new Response("ready");
+    if (url.pathname === "/metrics") {
+      return new Response(JSON.stringify({
+        uptime: process.uptime(),
+        memory: process.memoryUsage(),
+        timestamp: new Date().toISOString(),
+      }), {
+        headers: { "Content-Type": "application/json" }
+      });
+    }
+    
+    return new Response("Hello from BS9!");
+  },
+});
+```
+
+### TypeScript App with AOT
+```typescript
+// examples/typescript-app.ts
+import { serve } from "bun";
+
+interface RequestMetrics {
+  method: string;
+  route: string;
+  timestamp: number;
+}
+
+const metrics: RequestMetrics[] = [];
+
+serve({
+  port: Number(process.env.PORT) || 3000,
+  fetch(req: Request) {
+    const url = new URL(req.url);
+    const method = req.method;
+    const route = url.pathname;
+    
+    // Record metrics
+    metrics.push({
+      method,
+      route,
+      timestamp: Date.now(),
+    });
+    
+    if (url.pathname === "/healthz") return new Response("ok");
+    if (url.pathname === "/readyz") return new Response("ready");
+    
+    return new Response(`Hello from TypeScript BS9 app!\nMethod: ${method}\nRoute: ${route}`);
+  },
+});
+```
+
+---
+
+## 🔧 Development
+
+### Setup
+```bash
+# Clone and install
+git clone https://github.com/xarhang/bs9.git
+cd bs9
+bun install
+
+# Run CLI in development
+bun run bin/bs9 --help
+
+# Build for distribution
+bun run build
+```
+
+### Project Structure
+```
+BS9/
+├── bin/
+│   └── bs9                 # CLI entry point
+├── src/
+│   ├── commands/           # CLI commands
+│   │   ├── start.ts        # Service management
+│   │   ├── stop.ts         # Stop services
+│   │   ├── restart.ts      # Restart services
+│   │   ├── status.ts       # Status dashboard
+│   │   ├── logs.ts         # Log viewing
+│   │   ├── monit.ts        # Terminal dashboard
+│   │   ├── web.ts          # Web dashboard
+│   │   ├── alert.ts        # Alert management
+│   │   └── export.ts       # Data export
+│   ├── web/                # Web dashboard
+│   │   └── dashboard.ts    # Web server
+│   ├── storage/            # Metrics storage
+│   │   └── metrics.ts       # Historical data
+│   ├── alerting/           # Alert system
+│   │   └── config.ts       # Alert management
+│   ├── injectors/          # Auto-injection
+│   │   └── otel.ts         # OpenTelemetry
+│   ├── docker/             # Docker files
+│   │   └── Dockerfile       # Container setup
+│   └── k8s/                # Kubernetes manifests
+│       └── bs9-deployment.yaml
+├── examples/               # Example apps
+├── configs/                # Configuration templates
+├── setup.sh               # One-click installer
+├── docker-compose.yml      # Docker stack
+└── README.md
+```
+
+---
+
+## 🚀 Production Deployment
+
+### System Requirements
+- **OS**: Linux (systemd user mode)
+- **Runtime**: Bun 1.3.6+
+- **Memory**: 512MB minimum per service
+- **Disk**: 1GB for metrics storage
+
+### Installation
+```bash
+# One-click install
+curl -fsSL https://raw.githubusercontent.com/xarhang/bs9/main/setup.sh | bash
+
+# Manual install
+git clone https://github.com/xarhang/bs9.git
+cd bs9
+bun install
+cp bin/bs9 ~/.local/bin/bs9
+chmod +x ~/.local/bin/bs9
+```
+
+### Production Setup
+```bash
+# Enable user services persistence
+loginctl enable-linger $USER
+
+# Start first service
+bs9 start examples/simple-app.js --name production-app
+
+# Verify monitoring
+bs9 status
+bs9 monit
+bs9 web --detach
+
+# Configure alerts
+bs9 alert --cpu 80 --memory 85 --webhook https://hooks.slack.com/...
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Service Issues
+```bash 
+# Check service status
+systemctl --user status myservice
+
+# View logs
+bs9 logs myservice --follow
+
+# Check systemd unit
+systemctl --user daemon-reload
+```
+
+### Monitoring Issues
+```bash
+# Check web dashboard
+curl http://localhost:8080/api/metrics
+
+# Test alerts
+bs9 alert --test
+
+# Export metrics for analysis
+bs9 export --format json --hours 1
+```
+
+### Performance Issues
+```bash
+# Check resource usage
+bs9 status
+
+# Monitor with terminal dashboard
+bs9 monit --refresh 1
+
+# Export historical data
+bs9 export --service myapp --hours 24
+```
+
+---
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+---
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+
+---
+
+## 🔗 Links
+
+- **GitHub**: https://github.com/xarhang/bs9
+- **Issues**: https://github.com/xarhang/bs9/issues
+- **Documentation**: https://github.com/xarhang/bs9/wiki
+- **Discussions**: https://github.com/xarhang/bs9/discussions

package/bin/bs9

@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+import { startCommand } from "../src/commands/start.js";
+import { stopCommand } from "../src/commands/stop.js";
+import { restartCommand } from "../src/commands/restart.js";
+import { statusCommand } from "../src/commands/status.js";
+import { logsCommand } from "../src/commands/logs.js";
+import { monitCommand } from "../src/commands/monit.js";
+import { webCommand } from "../src/commands/web.js";
+import { alertCommand } from "../src/commands/alert.js";
+import { exportCommand } from "../src/commands/export.js";
+
+const program = new Command();
+
+program
+  .name("bs9")
+  .description("BS9 (Bun Sentinel 9) — Mission-critical process manager CLI")
+  .version("1.0.0");
+
+program
+  .command("start")
+  .description("Start a process with hardened systemd unit")
+  .argument("<file>", "Script or executable to run")
+  .option("-n, --name <name>", "Service name (defaults to filename)")
+  .option("-p, --port <port>", "Port to expose (for metrics/health)", "3000")
+  .option("--env <env...>", "Environment variables (KEY=VALUE)")
+  .option("--no-otel", "Disable automatic OpenTelemetry injection")
+  .option("--no-prometheus", "Disable automatic Prometheus metrics")
+  .option("--build", "Build TypeScript to optimized JavaScript for production (AOT)")
+  .action(startCommand);
+
+program
+  .command("stop")
+  .description("Stop a managed service")
+  .argument("<name>", "Service name")
+  .action(stopCommand);
+
+program
+  .command("restart")
+  .description("Restart a managed service")
+  .argument("<name>", "Service name")
+  .action(restartCommand);
+
+program
+  .command("status")
+  .description("Show status and SRE metrics for all services")
+  .option("-w, --watch", "Watch mode (refresh every 2s)")
+  .action(statusCommand);
+
+program
+  .command("logs")
+  .description("Show logs for a service (via journalctl)")
+  .argument("<name>", "Service name")
+  .option("-f, --follow", "Follow logs")
+  .option("-n, --lines <number>", "Number of lines", "50")
+  .action(logsCommand);
+
+program
+  .command("monit")
+  .description("Real-time terminal dashboard for all services")
+  .option("-r, --refresh <seconds>", "Refresh interval in seconds", "2")
+  .action(monitCommand);
+
+program
+  .command("web")
+  .description("Start web-based monitoring dashboard")
+  .option("-p, --port <port>", "Port for web dashboard", "8080")
+  .option("-d, --detach", "Run in background")
+  .action(webCommand);
+
+program
+  .command("alert")
+  .description("Configure alert thresholds and webhooks")
+  .option("--enable", "Enable alerts")
+  .option("--disable", "Disable alerts")
+  .option("--webhook <url>", "Set webhook URL for alerts")
+  .option("--cpu <percentage>", "CPU threshold percentage")
+  .option("--memory <percentage>", "Memory threshold percentage")
+  .option("--errorRate <percentage>", "Error rate threshold percentage")
+  .option("--uptime <percentage>", "Uptime threshold percentage")
+  .option("--cooldown <seconds>", "Alert cooldown period in seconds")
+  .option("--service <name>", "Configure alerts for specific service")
+  .option("--list", "List current alert configuration")
+  .option("--test", "Test webhook connectivity")
+  .action(alertCommand);
+
+program
+  .command("export")
+  .description("Export historical metrics data")
+  .option("-f, --format <format>", "Export format (json|csv)", "json")
+  .option("-h, --hours <hours>", "Hours of data to export", "24")
+  .option("-o, --output <file>", "Output file path")
+  .option("-s, --service <name>", "Export specific service metrics")
+  .action(exportCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "bs9",
+  "version": "1.0.0",
+  "description": "Bun Sentinel 9 - High-performance, non-root process manager for Bun",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "bs9": "./bin/bs9",
+    "bsn": "./bin/bs9"
+  },
+  "files": [
+    "bin",
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "build": "bun build ./bin/bs9 --outdir ./dist --target bun",
+    "audit": "bun audit"
+  },
+  "keywords": [
+    "bun",
+    "process-manager",
+    "sentinel",
+    "cli",
+    "monitoring"
+  ],
+  "author": "xarhang",
+  "license": "MIT",
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.50.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.50.0",
+    "@opentelemetry/resources": "^1.23.0",
+    "@opentelemetry/sdk-node": "^0.50.0",
+    "@opentelemetry/semantic-conventions": "^1.23.0",
+    "commander": "^12.0.0",
+    "pg": "^8.12.0",
+    "pino": "^9.3.1",
+    "prom-client": "^15.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "bun-types": "^1.1.0"
+  }
+}