bgrun 3.10.1 → 3.11.0

package/README.md

@@ -75,7 +75,8 @@ Features:
 - Real-time process status via SSE (no polling)
 - Start, stop, restart, and delete processes from the UI
 - Live stdout/stderr log viewer with search
-- Memory, PID, port, and runtime at a glance
+- Memory, PID, port, runtime, and guard restarts at a glance
+- Guard toggle per-process (auto-restart on crash)
 - Responsive mobile layout
 - Collapsible directory groups
 
@@ -91,6 +92,9 @@ Features:
 - [Caddy Reverse Proxy](#caddy-reverse-proxy)
 - [TOML Configuration](#toml-configuration)
 - [Programmatic API](#programmatic-api)
+- [Process Dependencies](#process-dependencies)
+- [Log Rotation](#log-rotation)
+- [Guard (Auto-Restart)](#guard-auto-restart)
 - [Migrating from PM2](#migrating-from-pm2)
 - [Edge Cases & Behaviors](#edge-cases--behaviors)
 - [Full CLI Reference](#full-cli-reference)
@@ -555,12 +559,80 @@ bgrun --name worker --directory ./workers --command "node worker.js" --force
    WantedBy=multi-user.target
    ```
 
-3. **No log rotation** — bgrun writes to plain text files in `~/.bgr/`. Use `logrotate` or similar tools, or specify custom log paths with `--stdout` and `--stderr`.
+3. **Built-in log rotation** — bgrun automatically rotates logs when they exceed 10MB, keeping the last 5000 lines. Manual rotation is also available via the dashboard API.
 
 4. **Bun required** — bgrun runs on Bun, but the *processes it manages* can be anything: Node.js, Python, Ruby, Go, Docker, shell scripts.
 
 ---
 
+## Process Dependencies
+
+bgrun supports declaring process startup dependencies via the `BGR_DEPENDS_ON` environment variable:
+
+```bash
+# Start a price listener (no dependencies)
+bgrun --name price-feed --command "bun run sqd.ts" --force
+
+# Start a worker that depends on the price feed
+BGR_DEPENDS_ON=price-feed bgrun --name mm-worker --command "bun run worker.ts" --force
+```
+
+When you start `mm-worker`, bgrun will automatically start `price-feed` first if it's not already running.
+
+### Features
+
+- **Topological sort** — processes start in correct dependency order
+- **Cycle detection** — bgrun warns if dependencies form a cycle
+- **Auto-start** — unmet dependencies are started automatically
+- **API** — `GET /api/deps` returns the full dependency graph with startup order
+
+### Setting dependencies via API
+
+```bash
+curl -X POST http://localhost:3001/api/deps \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "mm-worker", "dependsOn": ["price-feed", "redis"]}'
+```
+
+---
+
+## Log Rotation
+
+bgrun includes automatic log rotation to prevent unbounded log file growth:
+
+- **Size-based rotation**: Files exceeding 10MB are truncated, keeping the last 5000 lines
+- **Automatic checks**: Rotation runs every 60 seconds alongside the dashboard
+- **Rotation header**: Rotated files include a timestamp header for auditability
+- **Manual rotation**: Trigger via the dashboard API
+
+```bash
+# Check log sizes
+curl http://localhost:3001/api/logs/rotate
+
+# Force rotation now
+curl -X POST http://localhost:3001/api/logs/rotate
+```
+
+---
+
+## Guard (Auto-Restart)
+
+bgrun includes a standalone guard process that monitors and auto-restarts crashed processes:
+
+```bash
+# Enable guard for a process
+BGR_KEEP_ALIVE=true bgrun --name my-api --command "bun run server.ts" --force
+```
+
+The guard checks processes every 30 seconds and restarts any that have stopped. Features:
+
+- **Exponential backoff** — avoids restart storms for processes that keep crashing
+- **Per-process toggle** — enable/disable guard via the dashboard shield icon
+- **Guard sentinel** — dashboard shows a pulsing green dot when the guard is active
+- **Restart counter** — dashboard tracks total guard restarts across all processes
+
+---
+
 ## Edge Cases & Behaviors
 
 ### What happens when a process crashes?
@@ -702,6 +774,8 @@ All state lives in `~/.bgr/`. To reset everything, delete this directory.
 |----------|-------------|---------|
 | `DB_NAME` | Custom database file name | `bgr` |
 | `BGR_GROUP` | Assign process to a group | *(none)* |
+| `BGR_KEEP_ALIVE` | Enable guard auto-restart for this process | `false` |
+| `BGR_DEPENDS_ON` | Comma-separated list of process dependencies | *(none)* |
 | `BUN_PORT` | Dashboard port (explicit, no fallback) | *(auto: 3000+)* |
 
 ---

package/dashboard/app/api/deps/route.ts

@@ -0,0 +1,49 @@
+/**
+ * GET  /api/deps — Get the process dependency graph
+ * POST /api/deps — Set dependencies for a process
+ *   Body: { name: string, dependsOn: string[] }
+ */
+
+import { getProcess, updateProcessEnv } from '../../../../src/db'
+import { buildDepGraph } from '../../../../src/deps'
+import { parseEnvString } from '../../../../src/utils'
+
+export async function GET() {
+    const graph = await buildDepGraph()
+    return Response.json(graph)
+}
+
+export async function POST(req: Request) {
+    try {
+        const body = await req.json() as { name: string; dependsOn: string[] }
+        if (!body.name) {
+            return Response.json({ error: 'Missing process name' }, { status: 400 })
+        }
+
+        const proc = getProcess(body.name)
+        if (!proc) {
+            return Response.json({ error: `Process "${body.name}" not found` }, { status: 404 })
+        }
+
+        // Parse existing env
+        let env: Record<string, string> = {}
+        try { env = JSON.parse(proc.env) } catch { env = parseEnvString(proc.env) }
+
+        // Update dependencies
+        if (body.dependsOn && body.dependsOn.length > 0) {
+            env.BGR_DEPENDS_ON = body.dependsOn.join(',')
+        } else {
+            delete env.BGR_DEPENDS_ON
+        }
+
+        updateProcessEnv(body.name, JSON.stringify(env))
+
+        return Response.json({
+            ok: true,
+            name: body.name,
+            dependsOn: body.dependsOn || [],
+        })
+    } catch (err: any) {
+        return Response.json({ error: err.message }, { status: 500 })
+    }
+}

package/dashboard/app/api/guard/route.ts

@@ -0,0 +1,50 @@
+/**
+ * POST /api/guard — Toggle BGR_KEEP_ALIVE for a process
+ * Body: { name: string, enabled: boolean }
+ * 
+ * When enabled=true, the built-in guard will auto-restart this process if it dies.
+ * When enabled=false, the process is left alone.
+ */
+import { getProcess, updateProcessEnv } from '../../../../src/db';
+
+export async function POST(req: Request) {
+    try {
+        const body = await req.json() as { name: string; enabled: boolean };
+        if (!body.name) {
+            return Response.json({ error: 'Missing process name' }, { status: 400 });
+        }
+
+        const proc = getProcess(body.name);
+        if (!proc) {
+            return Response.json({ error: `Process "${body.name}" not found` }, { status: 404 });
+        }
+
+        // Parse existing env
+        let env: Record<string, string> = {};
+        if (proc.env) {
+            try { env = JSON.parse(proc.env); } catch { env = {}; }
+        }
+
+        // Toggle BGR_KEEP_ALIVE
+        if (body.enabled) {
+            env.BGR_KEEP_ALIVE = 'true';
+        } else {
+            delete env.BGR_KEEP_ALIVE;
+        }
+
+        // Save back
+        updateProcessEnv(body.name, JSON.stringify(env));
+
+        return Response.json({
+            ok: true,
+            name: body.name,
+            guarded: body.enabled
+        });
+    } catch (err: any) {
+        return Response.json({ error: err.message }, { status: 500 });
+    }
+}
+
+export async function GET() {
+    return Response.json({ error: 'Use POST to toggle guard' }, { status: 405 });
+}

package/dashboard/app/api/guard-all/route.ts

@@ -0,0 +1,50 @@
+/**
+ * POST /api/guard-all — Bulk toggle guard for all processes
+ * Body: { enabled: boolean }
+ * 
+ * When enabled=true, sets BGR_KEEP_ALIVE=true for ALL processes (except bgr-dashboard).
+ * When enabled=false, removes BGR_KEEP_ALIVE from ALL processes.
+ */
+import { getAllProcesses, getProcess, updateProcessEnv } from '../../../../src/db';
+
+const SKIP = new Set(['bgr-dashboard']);
+
+export async function POST(req: Request) {
+    try {
+        const body = await req.json() as { enabled: boolean };
+        const processes = getAllProcesses();
+        let count = 0;
+
+        for (const proc of processes) {
+            if (SKIP.has(proc.name)) continue;
+
+            // Parse existing env
+            let env: Record<string, string> = {};
+            if (proc.env) {
+                try { env = JSON.parse(proc.env); } catch { env = {}; }
+            }
+
+            const alreadyGuarded = env.BGR_KEEP_ALIVE === 'true';
+            if (body.enabled && alreadyGuarded) continue;
+            if (!body.enabled && !alreadyGuarded) continue;
+
+            if (body.enabled) {
+                env.BGR_KEEP_ALIVE = 'true';
+            } else {
+                delete env.BGR_KEEP_ALIVE;
+            }
+
+            updateProcessEnv(proc.name, JSON.stringify(env));
+            count++;
+        }
+
+        return Response.json({
+            ok: true,
+            action: body.enabled ? 'guarded' : 'unguarded',
+            count,
+            total: processes.length,
+        });
+    } catch (err: any) {
+        return Response.json({ error: err.message }, { status: 500 });
+    }
+}

package/dashboard/app/api/logs/rotate/route.ts

@@ -0,0 +1,45 @@
+/**
+ * POST /api/logs/rotate — Rotate all log files
+ * GET  /api/logs/rotate — Get log file sizes
+ */
+
+import { getAllProcesses } from '../../../../../src/db'
+import { rotateAllLogs } from '../../../../../src/log-rotation'
+import { existsSync, statSync } from 'fs'
+
+export function POST() {
+    const result = rotateAllLogs(() => getAllProcesses())
+    return Response.json({
+        ok: true,
+        rotated: result.rotated,
+        checked: result.checked,
+    })
+}
+
+export function GET() {
+    const processes = getAllProcesses()
+    const files: Array<{ name: string; type: string; path: string; sizeBytes: number; sizeMB: string }> = []
+
+    for (const proc of processes) {
+        for (const [type, path] of [['stdout', proc.stdout_path], ['stderr', proc.stderr_path]] as const) {
+            if (path && existsSync(path)) {
+                const stat = statSync(path)
+                files.push({
+                    name: proc.name,
+                    type,
+                    path,
+                    sizeBytes: stat.size,
+                    sizeMB: (stat.size / 1_000_000).toFixed(2),
+                })
+            }
+        }
+    }
+
+    const totalBytes = files.reduce((sum, f) => sum + f.sizeBytes, 0)
+
+    return Response.json({
+        files,
+        totalBytes,
+        totalMB: (totalBytes / 1_000_000).toFixed(2),
+    })
+}

package/dashboard/app/api/processes/route.ts

@@ -1,6 +1,7 @@
 import { getAllProcesses, updateProcessPid } from '../../../../src/db';
 import { calculateRuntime } from '../../../../src/utils';
-import { getProcessBatchMemory, reconcileProcessPids } from '../../../../src/platform';
+import { getProcessBatchResources, reconcileProcessPids } from '../../../../src/platform';
+import { guardRestartCounts } from '../../../../src/server';
 import { measure, createMeasure } from 'measure-fn';
 import { $ } from 'bun';
 
@@ -14,7 +15,12 @@ const g = globalThis as any;
 if (!g.__bgrProcessCache) {
     g.__bgrProcessCache = { data: null, timestamp: 0, inflight: null };
 }
+if (!g.__bgrResourceHistory) {
+    // Map of process name -> { memory: number[], cpu: number[], lastCpuTime: number, lastCheck: number }
+    g.__bgrResourceHistory = new Map<string, { memory: number[], cpu: number[], lastCpuTime: number, lastCheck: number }>();
+}
 const cache = g.__bgrProcessCache;
+const history = g.__bgrResourceHistory;
 
 function withTimeout<T>(promise: Promise<T>, fallback: T): Promise<T> {
     return Promise.race([
@@ -109,10 +115,10 @@ async function fetchProcesses(): Promise<any[]> {
         const pids = procs.map((p: any) => p.pid);
 
         // Three subprocess calls total (not 3×N)
-        let [runningPids, portMap, memoryMap] = await Promise.all([
+        let [runningPids, portMap, resourceMap] = await Promise.all([
             m('Running PIDs', () => withTimeout(getRunningPids(pids), new Set<number>())),
             m('Port map', () => withTimeout(getPortsByPid(pids), new Map<number, number[]>())),
-            m('Memory map', () => withTimeout(getProcessBatchMemory(pids), new Map<number, number>())),
+            m('Resource map', () => withTimeout(getProcessBatchResources(pids), new Map<number, { memory: number, cpu: number }>())),
         ]);
 
         // PID reconciliation: if stored PIDs are dead, try to find the real process
@@ -139,22 +145,69 @@ async function fetchProcesses(): Promise<any[]> {
                 if (!runningPids) runningPids = new Set();
                 for (const pid of newPids) runningPids.add(pid);
 
-                // Re-fetch ports and memory for the new PIDs
-                const [newPorts, newMem] = await Promise.all([
+                // Re-fetch ports and resources for the new PIDs
+                const [newPorts, newResources] = await Promise.all([
                     withTimeout(getPortsByPid(newPids), new Map<number, number[]>()),
-                    withTimeout(getProcessBatchMemory(newPids), new Map<number, number>()),
+                    withTimeout(getProcessBatchResources(newPids), new Map<number, { memory: number, cpu: number }>()),
                 ]);
                 if (!portMap) portMap = new Map();
-                if (!memoryMap) memoryMap = new Map();
+                if (!resourceMap) resourceMap = new Map();
                 for (const [pid, ports] of newPorts) portMap.set(pid, ports);
-                for (const [pid, mem] of newMem) memoryMap.set(pid, mem);
+                for (const [pid, res] of newResources) resourceMap.set(pid, res);
             }
         }
 
+        const now = Date.now();
+        const isWin = process.platform === 'win32';
+
         return procs.map((p: any) => {
             const running = runningPids?.has(p.pid) ?? false;
             const ports = running ? (portMap?.get(p.pid) || []) : [];
-            const memory = running ? (memoryMap?.get(p.pid) || 0) : 0;
+            const res = running ? (resourceMap?.get(p.pid) || { memory: 0, cpu: 0 }) : { memory: 0, cpu: 0 };
+
+            // Manage history tracking for sparklines (up to 60 points = 5 minutes at 5s polling)
+            let h = history.get(p.name);
+            if (!h) {
+                h = { memory: [], cpu: [], lastCpuTime: 0, lastCheck: 0 };
+                history.set(p.name, h);
+            }
+
+            let cpuPercent = 0;
+            if (running) {
+                if (isWin) {
+                    // Windows: cpu is cumulative seconds. Calculate delta percentage across time.
+                    if (h.lastCheck > 0 && h.lastCpuTime > 0) {
+                        const timeDeltaSec = (now - h.lastCheck) / 1000;
+                        const cpuDeltaSec = res.cpu - h.lastCpuTime;
+                        if (timeDeltaSec > 0 && cpuDeltaSec >= 0) {
+                            // Max it at 100% per core? We'll just display the total usage
+                            cpuPercent = (cpuDeltaSec / timeDeltaSec) * 100;
+                        }
+                    }
+                    h.lastCpuTime = res.cpu;
+                } else {
+                    // Unix: it's already a percentage from \`ps\`
+                    cpuPercent = res.cpu;
+                }
+
+                // Add points
+                h.memory.push(res.memory);
+                h.cpu.push(cpuPercent);
+                if (h.memory.length > 60) h.memory.shift();
+                if (h.cpu.length > 60) h.cpu.shift();
+            } else {
+                // Not running, push zeros if not already zeroed out to bring graphs down
+                if (h.memory.length > 0 && h.memory[h.memory.length - 1] !== 0) {
+                    h.memory.push(0);
+                    h.cpu.push(0);
+                    if (h.memory.length > 60) h.memory.shift();
+                    if (h.cpu.length > 60) h.cpu.shift();
+                }
+                h.lastCheck = 0;
+                h.lastCpuTime = 0;
+            }
+
+            if (running) h.lastCheck = now;
 
             return {
                 name: p.name,
@@ -164,7 +217,10 @@ async function fetchProcesses(): Promise<any[]> {
                 running,
                 port: ports.length > 0 ? ports[0] : null,
                 ports,
-                memory, // Bytes
+                memory: res.memory, // Bytes
+                cpu: cpuPercent, // Percentage
+                memoryHistory: [...h.memory],
+                cpuHistory: [...h.cpu],
                 group: getProcessGroup(p.env),
                 runtime: calculateRuntime(p.timestamp),
                 timestamp: p.timestamp,
@@ -172,6 +228,7 @@ async function fetchProcesses(): Promise<any[]> {
                 configPath: p.configPath || '',
                 stdoutPath: p.stdout_path || '',
                 stderrPath: p.stderr_path || '',
+                guardRestarts: guardRestartCounts.get(p.name) || 0,
             };
         });
     }) ?? [];