bgrun 3.10.2 → 3.11.0

package/package.json

@@ -1,60 +1,61 @@
-{
-  "name": "bgrun",
-  "version": "3.10.2",
-  "description": "bgrun — A lightweight process manager for Bun",
-  "type": "module",
-  "main": "./src/api.ts",
-  "exports": {
-    ".": "./src/api.ts"
-  },
-  "bin": {
-    "bgrun": "./dist/index.js"
-  },
-  "scripts": {
-    "build": "bun run ./src/build.ts",
-    "test": "bun test",
-    "prepublishOnly": "bun run build"
-  },
-  "files": [
-    "dist",
-    "src",
-    "dashboard/app",
-    "README.md",
-    "image.png",
-    "examples/bgr-startup.sh"
-  ],
-  "keywords": [
-    "process-manager",
-    "bun",
-    "monitoring",
-    "devops",
-    "deployment",
-    "background",
-    "daemon"
-  ],
-  "author": "7flash",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/7flash/bgrun.git"
-  },
-  "devDependencies": {
-    "bun-types": "latest"
-  },
-  "peerDependencies": {
-    "typescript": "^5.0.0"
-  },
-  "dependencies": {
-    "boxen": "^8.0.1",
-    "chalk": "^5.4.1",
-    "dedent": "^1.5.3",
-    "measure-fn": "^3.2.1",
-    "melina": "^2.2.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "sqlite-zod-orm": "^3.8.0"
-  },
-  "engines": {
-    "bun": ">=1.0.0"
-  }
-}
+{
+  "name": "bgrun",
+  "version": "3.11.0",
+  "description": "bgrun — A lightweight process manager for Bun",
+  "type": "module",
+  "main": "./src/api.ts",
+  "exports": {
+    ".": "./src/api.ts"
+  },
+  "bin": {
+    "bgrun": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "bun run ./src/build.ts",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "files": [
+    "dist",
+    "src",
+    "dashboard/app",
+    "README.md",
+    "image.png",
+    "examples/bgr-startup.sh"
+  ],
+  "keywords": [
+    "process-manager",
+    "bun",
+    "monitoring",
+    "devops",
+    "deployment",
+    "background",
+    "daemon"
+  ],
+  "author": "7flash",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/7flash/bgrun.git"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "bun-types": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "boxen": "^8.0.1",
+    "chalk": "^5.4.1",
+    "dedent": "^1.5.3",
+    "measure-fn": "3.10.1",
+    "melina": "2.3.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "sqlite-zod-orm": "3.26.1"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/api.ts

@@ -39,7 +39,7 @@ export {
     ensureDir,
     getHomeDir,
     isWindows,
-    getProcessBatchMemory,
+    getProcessBatchResources,
     getProcessMemory
 } from './platform'
 
@@ -51,13 +51,13 @@ export { getVersion, calculateRuntime, parseEnvString, validateDirectory } from
 
 // --- Default Export (namespace style) ---
 import { getAllProcesses, getProcess, insertProcess, removeProcess, removeProcessByName, removeAllProcesses, retryDatabaseOperation, getDbInfo, dbPath, bgrHome } from './db'
-import { isProcessRunning, terminateProcess, readFileTail, getProcessPorts, findChildPid, findPidByPort, getShellCommand, killProcessOnPort, waitForPortFree, ensureDir, getHomeDir, isWindows, getProcessBatchMemory, getProcessMemory } from './platform'
+import { isProcessRunning, terminateProcess, readFileTail, getProcessPorts, findChildPid, findPidByPort, getShellCommand, killProcessOnPort, waitForPortFree, ensureDir, getHomeDir, isWindows, getProcessBatchResources, getProcessMemory } from './platform'
 import { handleRun } from './commands/run'
 import { getVersion, calculateRuntime, parseEnvString, validateDirectory } from './utils'
 
 export default {
     getAllProcesses, getProcess, insertProcess, removeProcess, removeProcessByName, removeAllProcesses, retryDatabaseOperation, getDbInfo, dbPath, bgrHome,
-    isProcessRunning, terminateProcess, readFileTail, getProcessPorts, findChildPid, findPidByPort, getShellCommand, killProcessOnPort, waitForPortFree, ensureDir, getHomeDir, isWindows, getProcessBatchMemory, getProcessMemory,
+    isProcessRunning, terminateProcess, readFileTail, getProcessPorts, findChildPid, findPidByPort, getShellCommand, killProcessOnPort, waitForPortFree, ensureDir, getHomeDir, isWindows, getProcessBatchResources, getProcessMemory,
     handleRun,
     getVersion, calculateRuntime, parseEnvString, validateDirectory,
 }

package/src/commands/list.ts

@@ -4,7 +4,7 @@ import type { ProcessTableRow } from "../table";
 import { getAllProcesses } from "../db";
 import { announce } from "../logger";
 import { isProcessRunning, calculateRuntime, parseEnvString } from "../utils";
-import { getProcessPorts, getProcessBatchMemory } from "../platform";
+import { getProcessPorts, getProcessBatchResources } from "../platform";
 import { measure } from "measure-fn";
 
 function formatMemory(bytes: number): string {
@@ -51,12 +51,12 @@ export async function showAll(opts?: { json?: boolean; filter?: string }) {
 
     // Batch fetch memory for all PIDs
     const allPids = filtered.map(p => p.pid);
-    const memoryMap = await getProcessBatchMemory(allPids);
+    const resourceMap = await getProcessBatchResources(allPids);
 
     for (const proc of filtered) {
         const isRunning = await isProcessRunning(proc.pid, proc.command);
         const runtime = calculateRuntime(proc.timestamp);
-        const mem = isRunning ? (memoryMap.get(proc.pid) || 0) : 0;
+        const mem = isRunning ? (resourceMap.get(proc.pid)?.memory || 0) : 0;
 
         const ports = isRunning ? await getProcessPorts(proc.pid) : [];
         tableData.push({

package/src/commands/run.ts

@@ -17,6 +17,23 @@ export async function handleRun(options: CommandOptions) {
 
     const existingProcess = name ? getProcess(name) : null;
 
+    // Auto-start unmet dependencies before starting this process
+    if (name && existingProcess) {
+        const { getUnmetDeps } = await import('../deps');
+        const unmet = await getUnmetDeps(name);
+        if (unmet.length > 0) {
+            await run.measure(`Start ${unmet.length} dependencies for "${name}"`, async () => {
+                for (const depName of unmet) {
+                    const depProc = getProcess(depName);
+                    if (depProc) {
+                        announce(`📦 Starting dependency "${depName}" for "${name}"`, 'Dependency');
+                        await handleRun({ action: 'run', name: depName, force: true, remoteName: '' });
+                    }
+                }
+            });
+        }
+    }
+
     if (existingProcess) {
         const finalDirectory = directory || existingProcess.workdir;
         validateDirectory(finalDirectory);

package/src/deps.ts

@@ -0,0 +1,126 @@
+/**
+ * Process Dependency Graph
+ * 
+ * Defines and resolves process startup dependencies.
+ * Dependencies are stored in process env as BGR_DEPENDS_ON=name1,name2
+ * 
+ * Features:
+ * - Topological sort for startup order
+ * - Cycle detection
+ * - Dependency graph as adjacency list
+ * - Auto-start dependencies on process run
+ */
+
+import { getAllProcesses, getProcess } from './db'
+import { isProcessRunning } from './platform'
+import { parseEnvString } from './utils'
+
+export interface DepNode {
+    name: string
+    dependsOn: string[]      // processes this depends ON (must start first)
+    dependedBy: string[]     // processes that depend on THIS
+    running: boolean
+    pid: number
+}
+
+export interface DepGraph {
+    nodes: DepNode[]
+    order: string[]          // topological sort (startup order)
+    hasCycle: boolean
+    cycleNodes?: string[]    // nodes involved in cycle
+}
+
+/** Parse BGR_DEPENDS_ON from a process env string */
+export function getDependencies(envStr: string): string[] {
+    const env = parseEnvString(envStr)
+    const raw = env.BGR_DEPENDS_ON || ''
+    return raw.split(',').map(s => s.trim()).filter(Boolean)
+}
+
+/** Build the full dependency graph from all registered processes */
+export async function buildDepGraph(): Promise<DepGraph> {
+    const processes = getAllProcesses()
+    const nodeMap = new Map<string, DepNode>()
+
+    // Phase 1: Create all nodes
+    for (const proc of processes) {
+        const deps = getDependencies(proc.env)
+        const alive = await isProcessRunning(proc.pid, proc.command)
+        nodeMap.set(proc.name, {
+            name: proc.name,
+            dependsOn: deps,
+            dependedBy: [],
+            running: alive,
+            pid: proc.pid,
+        })
+    }
+
+    // Phase 2: Build reverse edges (dependedBy)
+    for (const node of nodeMap.values()) {
+        for (const dep of node.dependsOn) {
+            const depNode = nodeMap.get(dep)
+            if (depNode) {
+                depNode.dependedBy.push(node.name)
+            }
+        }
+    }
+
+    // Phase 3: Topological sort (Kahn's algorithm)
+    const inDegree = new Map<string, number>()
+    for (const node of nodeMap.values()) {
+        inDegree.set(node.name, node.dependsOn.filter(d => nodeMap.has(d)).length)
+    }
+
+    const queue: string[] = []
+    for (const [name, degree] of inDegree) {
+        if (degree === 0) queue.push(name)
+    }
+
+    const order: string[] = []
+    while (queue.length > 0) {
+        const current = queue.shift()!
+        order.push(current)
+
+        const node = nodeMap.get(current)!
+        for (const dependent of node.dependedBy) {
+            const newDegree = (inDegree.get(dependent) || 0) - 1
+            inDegree.set(dependent, newDegree)
+            if (newDegree === 0) queue.push(dependent)
+        }
+    }
+
+    const hasCycle = order.length < nodeMap.size
+    const cycleNodes = hasCycle
+        ? [...nodeMap.keys()].filter(n => !order.includes(n))
+        : undefined
+
+    return {
+        nodes: [...nodeMap.values()],
+        order,
+        hasCycle,
+        cycleNodes,
+    }
+}
+
+/** Get unmet dependencies for a specific process */
+export async function getUnmetDeps(name: string): Promise<string[]> {
+    const proc = getProcess(name)
+    if (!proc) return []
+
+    const deps = getDependencies(proc.env)
+    const unmet: string[] = []
+
+    for (const depName of deps) {
+        const depProc = getProcess(depName)
+        if (!depProc) {
+            unmet.push(depName) // dependency not even registered
+            continue
+        }
+        const alive = await isProcessRunning(depProc.pid, depProc.command)
+        if (!alive) {
+            unmet.push(depName)
+        }
+    }
+
+    return unmet
+}

package/src/guard.ts

@@ -0,0 +1,157 @@
+/**
+ * BGR Standalone Process Guard
+ * 
+ * Runs as an independent process that monitors ALL guarded processes
+ * (BGR_KEEP_ALIVE=true) and the dashboard itself. If the dashboard
+ * crashes, the guard restarts it. If any guarded process dies, the 
+ * guard restarts it.
+ * 
+ * This is the "outer shell" — it cannot be killed by a dashboard crash.
+ * 
+ * Usage:
+ *   bgrun --guard              # Start guard as a managed bgrun process
+ *   bgrun --_guard-loop        # (Internal) Actually run the guard loop
+ *   bgrun --_guard-loop 30     # Check every 30 seconds
+ */
+
+import { getAllProcesses, getProcess } from './db';
+import { isProcessRunning, getProcessPorts, findChildPid } from './platform';
+import { handleRun } from './commands/run';
+import { parseEnvString } from './utils';
+
+const DEFAULT_INTERVAL_MS = 30_000;
+const MAX_BACKOFF_MS = 5 * 60_000; // 5 minutes max
+const CRASH_THRESHOLD = 5; // Start backoff after this many restarts
+const STABILITY_WINDOW_MS = 120_000; // 2 minutes stable = reset counter
+
+interface GuardState {
+    restartCounts: Map<string, number>;
+    nextRestartTime: Map<string, number>;
+    lastSeenAlive: Map<string, number>;
+}
+
+const state: GuardState = {
+    restartCounts: new Map(),
+    nextRestartTime: new Map(),
+    lastSeenAlive: new Map(),
+};
+
+async function restartProcess(name: string): Promise<boolean> {
+    try {
+        await handleRun({
+            action: 'run',
+            name,
+            force: true,
+            remoteName: '',
+        });
+        return true;
+    } catch (err: any) {
+        console.error(`[guard] ✗ Failed to restart "${name}": ${err.message}`);
+        return false;
+    }
+}
+
+function getBackoffMs(restartCount: number): number {
+    if (restartCount <= CRASH_THRESHOLD) return 0;
+    const exponent = restartCount - CRASH_THRESHOLD;
+    return Math.min(30_000 * Math.pow(2, exponent - 1), MAX_BACKOFF_MS);
+}
+
+async function guardCycle(): Promise<void> {
+    try {
+        const processes = getAllProcesses();
+        if (processes.length === 0) return;
+
+        const now = Date.now();
+        let checked = 0;
+        let restarted = 0;
+        let skipped = 0;
+
+        for (const proc of processes) {
+            // Skip the guard process itself
+            if (proc.name === 'bgr-guard') continue;
+
+            const env = proc.env ? parseEnvString(proc.env) : {};
+            const isGuarded = env.BGR_KEEP_ALIVE === 'true';
+            const isDashboard = proc.name === 'bgr-dashboard';
+
+            // Guard both: explicitly guarded processes AND the dashboard
+            if (!isGuarded && !isDashboard) continue;
+
+            checked++;
+
+            try {
+                const alive = await isProcessRunning(proc.pid, proc.command);
+
+                if (!alive && proc.pid > 0) {
+                    // Check backoff
+                    const nextRestart = state.nextRestartTime.get(proc.name) || 0;
+                    if (now < nextRestart) {
+                        const waitSecs = Math.round((nextRestart - now) / 1000);
+                        skipped++;
+                        continue;
+                    }
+
+                    console.log(`[guard] ⚠ "${proc.name}" (PID ${proc.pid}) is dead — restarting...`);
+
+                    const success = await restartProcess(proc.name);
+                    if (success) {
+                        const count = (state.restartCounts.get(proc.name) || 0) + 1;
+                        state.restartCounts.set(proc.name, count);
+                        state.lastSeenAlive.delete(proc.name);
+
+                        const backoff = getBackoffMs(count);
+                        if (backoff > 0) {
+                            state.nextRestartTime.set(proc.name, now + backoff);
+                            console.log(`[guard] ✓ Restarted "${proc.name}" (#${count}). Crash loop: next check in ${Math.round(backoff / 1000)}s`);
+                        } else {
+                            console.log(`[guard] ✓ Restarted "${proc.name}" (#${count})`);
+                        }
+                        restarted++;
+                    }
+                } else if (alive) {
+                    // Track stability — if alive for STABILITY_WINDOW, reset counters
+                    const count = state.restartCounts.get(proc.name) || 0;
+                    if (count > 0) {
+                        const lastSeen = state.lastSeenAlive.get(proc.name);
+                        if (!lastSeen) {
+                            state.lastSeenAlive.set(proc.name, now);
+                        } else if (now - lastSeen > STABILITY_WINDOW_MS) {
+                            state.restartCounts.delete(proc.name);
+                            state.nextRestartTime.delete(proc.name);
+                            state.lastSeenAlive.delete(proc.name);
+                            console.log(`[guard] ✓ "${proc.name}" stable for ${Math.round(STABILITY_WINDOW_MS / 1000)}s — reset counters`);
+                        }
+                    }
+                }
+            } catch (err: any) {
+                console.error(`[guard] Error checking "${proc.name}": ${err.message}`);
+            }
+        }
+
+        if (restarted > 0) {
+            console.log(`[guard] Cycle: ${checked} checked, ${restarted} restarted, ${skipped} in backoff`);
+        }
+    } catch (err: any) {
+        console.error(`[guard] Error in guard cycle: ${err.message}`);
+    }
+}
+
+export async function startGuardLoop(intervalMs: number = DEFAULT_INTERVAL_MS) {
+    const interval = intervalMs || DEFAULT_INTERVAL_MS;
+
+    console.log(`[guard] ═══════════════════════════════════════════`);
+    console.log(`[guard] 🛡️  BGR Standalone Guard started`);
+    console.log(`[guard]    Check interval: ${interval / 1000}s`);
+    console.log(`[guard]    Crash backoff threshold: ${CRASH_THRESHOLD} restarts`);
+    console.log(`[guard]    Stability window: ${STABILITY_WINDOW_MS / 1000}s`);
+    console.log(`[guard]    Monitoring: BGR_KEEP_ALIVE=true + bgr-dashboard`);
+    console.log(`[guard]    Started: ${new Date().toLocaleString()}`);
+    console.log(`[guard] ═══════════════════════════════════════════`);
+
+    // Run initial check immediately
+    await guardCycle();
+
+    // Then run on interval
+    setInterval(guardCycle, interval);
+}

package/src/index.ts

@@ -12,7 +12,7 @@ import type { CommandOptions } from "./types";
 import { error, announce } from "./logger";
 // startServer is dynamically imported only when --_serve is used
 // to avoid loading melina (which has side-effects) on every bgrun command
-import { getHomeDir, getShellCommand, findChildPid, isProcessRunning, terminateProcess, getProcessPorts, killProcessOnPort, waitForPortFree } from "./platform";
+import { getHomeDir, getShellCommand, findChildPid, isProcessRunning, terminateProcess, getProcessPorts, killProcessOnPort, waitForPortFree, isPortFree } from "./platform";
 import { insertProcess, removeProcessByName, getProcess, retryDatabaseOperation, getDbInfo } from "./db";
 import dedent from "dedent";
 import chalk from "chalk";
@@ -38,6 +38,7 @@ async function showHelp() {
       bgrun                     List all processes
       bgrun [name]             Show details for a process
       bgrun --dashboard        Launch web dashboard (managed by bgrun)
+      bgrun --guard            Launch standalone process guard
       bgrun --restart [name]   Restart a process
       bgrun --restart-all      Restart ALL registered processes
       bgrun --stop [name]      Stop a process (keep in registry)
@@ -105,8 +106,10 @@ async function run() {
       stdout: { type: 'string' },
       stderr: { type: 'string' },
       dashboard: { type: 'boolean' },
+      guard: { type: 'boolean' },
       debug: { type: 'boolean' },
       "_serve": { type: 'boolean' },
+      "_guard-loop": { type: 'boolean' },
       port: { type: 'string' },
     },
     strict: false,
@@ -122,6 +125,15 @@ async function run() {
     return;
   }
 
+  // Internal: actually run the guard loop (spawned by --guard)
+  if (values['_guard-loop']) {
+    const { startGuardLoop } = await import("./guard");
+    const intervalStr = positionals[0];
+    const intervalMs = intervalStr ? parseInt(intervalStr) * 1000 : undefined;
+    await startGuardLoop(intervalMs);
+    return;
+  }
+
   // Dashboard: spawn the dashboard server as a bgr-managed process
   if (values.dashboard) {
     const dashboardName = 'bgr-dashboard';
@@ -186,6 +198,21 @@ async function run() {
       spawnEnv.BUN_PORT = requestedPort;
     }
 
+    // Resolve the target port: --port flag > BUN_PORT env > default 3000
+    const targetPort = parseInt(requestedPort || Bun.env.BUN_PORT || '3000');
+    if (!isNaN(targetPort) && targetPort > 0) {
+      // Auto-kill whatever occupies the target port so dashboard always reclaims it
+      const portFree = await isPortFree(targetPort);
+      if (!portFree) {
+        console.log(chalk.yellow(`  ⚡ Port ${targetPort} is occupied — reclaiming...`));
+        await killProcessOnPort(targetPort);
+        const freed = await waitForPortFree(targetPort, 5000);
+        if (!freed) {
+          console.log(chalk.red(`  ⚠ Could not free port ${targetPort} — dashboard may pick a fallback port`));
+        }
+      }
+    }
+
     const newProcess = Bun.spawn(getShellCommand(spawnCommand), {
       env: spawnEnv,
       cwd: bgrDir,
@@ -246,6 +273,85 @@ async function run() {
     return;
   }
 
+  // Guard: spawn the standalone guard as a bgr-managed process
+  if (values.guard) {
+    const guardName = 'bgr-guard';
+    const homePath = getHomeDir();
+    const bgrDir = join(homePath, '.bgr');
+
+    // Check if guard is already running
+    const existing = getProcess(guardName);
+    if (existing && await isProcessRunning(existing.pid)) {
+      announce(
+        `Guard is already running (PID ${existing.pid})\n\n` +
+        `  Use ${chalk.yellow(`bgrun --stop ${guardName}`)} to stop it\n` +
+        `  Use ${chalk.yellow(`bgrun --guard --force`)} to restart`,
+        'BGR Guard'
+      );
+      return;
+    }
+
+    // Kill existing if force
+    if (existing) {
+      if (await isProcessRunning(existing.pid)) {
+        await terminateProcess(existing.pid);
+      }
+      await retryDatabaseOperation(() => removeProcessByName(guardName));
+    }
+
+    const { resolve } = require('path');
+    const scriptPath = resolve(process.argv[1]);
+    const spawnCommand = `bun run ${scriptPath} --_guard-loop`;
+    const command = `bgrun --_guard-loop`;
+    const stdoutPath = join(bgrDir, `${guardName}-out.txt`);
+    const stderrPath = join(bgrDir, `${guardName}-err.txt`);
+
+    await Bun.write(stdoutPath, '');
+    await Bun.write(stderrPath, '');
+
+    const newProcess = Bun.spawn(getShellCommand(spawnCommand), {
+      env: { ...Bun.env },
+      cwd: bgrDir,
+      stdout: Bun.file(stdoutPath),
+      stderr: Bun.file(stderrPath),
+    });
+
+    newProcess.unref();
+    await sleep(1000);
+    const actualPid = await findChildPid(newProcess.pid);
+
+    await retryDatabaseOperation(() =>
+      insertProcess({
+        pid: actualPid,
+        workdir: bgrDir,
+        command,
+        name: guardName,
+        env: 'BGR_KEEP_ALIVE=false', // Guard doesn't guard itself
+        configPath: '',
+        stdout_path: stdoutPath,
+        stderr_path: stderrPath,
+      })
+    );
+
+    const msg = dedent`
+      ${chalk.bold('🛡️  BGR Standalone Guard launched')}
+      ${chalk.gray('─'.repeat(40))}
+
+        Monitors: All processes with BGR_KEEP_ALIVE=true
+        Also watches: bgr-dashboard (auto-restart if it dies)
+        Check interval: 30 seconds
+        Backoff: Exponential after 5 rapid crashes
+
+      ${chalk.gray('─'.repeat(40))}
+        Process: ${chalk.white(guardName)}  |  PID: ${chalk.white(String(actualPid))}
+
+        ${chalk.yellow(`bgrun ${guardName} --logs`)}    View guard logs
+        ${chalk.yellow(`bgrun --stop ${guardName}`)}    Stop the guard
+    `;
+    announce(msg, 'BGR Guard');
+    return;
+  }
+
   if (values.version) {
     console.log(`bgrun version: ${await getVersion()}`);
     return;
@@ -435,6 +541,5 @@ async function run() {
 }
 
 run().catch(err => {
-  console.error(chalk.red(err));
-  process.exit(1);
+  error(err);
 });