bgrun 3.4.0 → 3.7.1

package/README.md

@@ -1,8 +1,8 @@
 <div align="center">
 
-# ⚡ bgrun
+<img src="./image.png" alt="bgrun" width="600" />
 
-**Bun Background Runner — a modern process manager built on Bun**
+**Production-ready process manager with dashboard and programmatic API, designed for running your containers, services, and AI agents.**
 
 [![npm](https://img.shields.io/npm/v/bgrun?color=F7A41D&label=npm&logo=npm)](https://www.npmjs.com/package/bgrun)
 [![bun](https://img.shields.io/badge/runtime-bun-F7A41D?logo=bun)](https://bun.sh/)
@@ -58,6 +58,29 @@ That's it. bgrun tracks the PID, captures stdout/stderr, detects the port, and s
 
 ---
 
+## 📊 Web Dashboard
+
+
+Launch with `bgrun --dashboard` and open `http://localhost:3001`. Processes are auto-grouped by working directory.
+
+**Expose with Caddy** for remote access:
+
+```
+bgrun.yourdomain.com {
+    reverse_proxy localhost:3001
+}
+```
+
+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
+- Responsive mobile layout
+- Collapsible directory groups
+
+---
+
 ## Table of Contents
 
 - [Core Commands](#core-commands)
@@ -697,6 +720,6 @@ MIT
 
 <div align="center">
 
-Built by [Mements](https://github.com/Mements) with ⚡ Bun
+Built with ⚡ Bun
 
 </div>

package/dashboard/app/api/config/[name]/route.ts

@@ -0,0 +1,55 @@
+/**
+ * GET  /api/config/:name — Read .config.toml content
+ * PUT  /api/config/:name — Write .config.toml content
+ */
+import { getProcess } from '../../../../../src/db';
+import { join } from 'path';
+import { readFile, writeFile } from 'fs/promises';
+
+function resolveConfigPath(proc: any): string | null {
+    if (!proc.configPath) return null;
+    return join(proc.workdir, proc.configPath);
+}
+
+export async function GET(req: Request, { params }: { params: { name: string } }) {
+    const name = decodeURIComponent(params.name);
+    const proc = getProcess(name);
+
+    if (!proc) {
+        return Response.json({ error: 'Process not found' }, { status: 404 });
+    }
+
+    const configPath = resolveConfigPath(proc);
+    if (!configPath) {
+        return Response.json({ content: '', path: null, exists: false });
+    }
+
+    try {
+        const content = await readFile(configPath, 'utf-8');
+        return Response.json({ content, path: configPath, exists: true });
+    } catch {
+        return Response.json({ content: '', path: configPath, exists: false });
+    }
+}
+
+export async function PUT(req: Request, { params }: { params: { name: string } }) {
+    const name = decodeURIComponent(params.name);
+    const proc = getProcess(name);
+
+    if (!proc) {
+        return Response.json({ error: 'Process not found' }, { status: 404 });
+    }
+
+    const configPath = resolveConfigPath(proc);
+    if (!configPath) {
+        return Response.json({ error: 'No config path configured' }, { status: 400 });
+    }
+
+    try {
+        const body = await req.json();
+        await writeFile(configPath, body.content, 'utf-8');
+        return Response.json({ success: true, path: configPath });
+    } catch (e: any) {
+        return Response.json({ error: e.message }, { status: 500 });
+    }
+}

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

@@ -3,10 +3,11 @@
  * 
  * Returns DB path, BGR home dir, platform info for diagnostics.
  */
-import { getDbInfo } from 'bgrun';
+import { getDbInfo } from '../../../../src/db';
+import { measureSync } from 'measure-fn';
 
 export async function GET() {
-    const info = getDbInfo();
+    const info = measureSync('DB info', () => getDbInfo());
     return Response.json({
         ...info,
         platform: process.platform,

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

@@ -0,0 +1,60 @@
+/**
+ * GET /api/events — Server-Sent Events endpoint
+ * 
+ * Streams process data every 3 seconds. Replaces client-side polling.
+ * The client connects once via EventSource and receives updates automatically.
+ * 
+ * Delegates to /api/processes for data enrichment (including PID reconciliation).
+ */
+
+const INTERVAL_MS = 3_000;
+
+export async function GET(req: Request) {
+    const url = new URL(req.url);
+    const origin = url.origin; // e.g. http://localhost:3001
+
+    const encoder = new TextEncoder();
+
+    const stream = new ReadableStream({
+        async start(controller) {
+            // Send initial data immediately
+            try {
+                const res = await fetch(`${origin}/api/processes?t=${Date.now()}`);
+                const data = await res.json();
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));
+            } catch {
+                controller.enqueue(encoder.encode(`data: []\n\n`));
+            }
+
+            controller.enqueue(encoder.encode(`: keepalive\n\n`));
+
+            // Then send updates every INTERVAL_MS
+            const interval = setInterval(async () => {
+                try {
+                    const res = await fetch(`${origin}/api/processes?t=${Date.now()}`);
+                    const data = await res.json();
+                    controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));
+                } catch {
+                    // Skip this tick, send on next
+                }
+            }, INTERVAL_MS);
+
+            // Store cleanup for when the stream is cancelled
+            (stream as any).__cleanup = () => clearInterval(interval);
+        },
+        cancel() {
+            if ((stream as any).__cleanup) {
+                (stream as any).__cleanup();
+            }
+        }
+    });
+
+    return new Response(stream, {
+        headers: {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no',
+        },
+    });
+}

package/dashboard/app/api/logs/[name]/route.ts

@@ -1,7 +1,52 @@
 /**
- * GET /api/logs/:name — Read last 100 lines of process stdout/stderr
+ * GET /api/logs/:name — Read process stdout/stderr logs
+ *
+ * Supports incremental loading via query params:
+ *   ?tab=stdout|stderr   — which log to read (default: stdout)
+ *   ?offset=N            — byte offset to start reading from (default: 0 = full file)
+ *
+ * Returns:
+ *   { text, size, mtime, filePath }
+ *
+ * On first call (offset=0), returns full file content.
+ * On subsequent calls (offset=previousSize), returns only new bytes.
+ * Client uses `size` as the offset for the next request.
  */
-import { getProcess, readFileTail } from 'bgrun';
+import { getProcess } from '../../../../../src/db';
+import { stat, open } from 'fs/promises';
+
+interface FileInfo {
+    text: string;
+    size: number;
+    mtime: string | null;
+    filePath: string;
+}
+
+async function readLogFile(path: string, offset: number): Promise<FileInfo> {
+    try {
+        const s = await stat(path);
+        const size = s.size;
+        const mtime = s.mtime.toISOString();
+
+        // If offset >= current size, no new data
+        if (offset >= size) {
+            return { text: '', size, mtime, filePath: path };
+        }
+
+        // Read from offset to end
+        const handle = await open(path, 'r');
+        try {
+            const bytesToRead = size - offset;
+            const buffer = Buffer.alloc(bytesToRead);
+            await handle.read(buffer, 0, bytesToRead, offset);
+            return { text: buffer.toString('utf-8'), size, mtime, filePath: path };
+        } finally {
+            await handle.close();
+        }
+    } catch {
+        return { text: '', size: 0, mtime: null, filePath: path };
+    }
+}
 
 export async function GET(req: Request, { params }: { params: { name: string } }) {
     const name = decodeURIComponent(params.name);
@@ -11,7 +56,12 @@ export async function GET(req: Request, { params }: { params: { name: string } }
         return Response.json({ error: 'Process not found' }, { status: 404 });
     }
 
-    const stdout = await readFileTail(proc.stdout_path, 100);
-    const stderr = await readFileTail(proc.stderr_path, 100);
-    return Response.json({ stdout, stderr });
+    const url = new URL(req.url);
+    const tab = url.searchParams.get('tab') || 'stdout';
+    const offset = parseInt(url.searchParams.get('offset') || '0', 10) || 0;
+
+    const path = tab === 'stderr' ? proc.stderr_path : proc.stdout_path;
+    const info = await readLogFile(path, offset);
+
+    return Response.json(info);
 }

package/dashboard/app/api/processes/[name]/route.ts

@@ -1,7 +1,9 @@
 /**
  * DELETE /api/processes/:name — Stop and remove a process
  */
-import { getProcess, removeProcessByName, isProcessRunning, terminateProcess } from 'bgrun';
+import { getProcess, removeProcessByName } from '../../../../../src/db';
+import { isProcessRunning, terminateProcess } from '../../../../../src/platform';
+import { measure } from 'measure-fn';
 
 export async function DELETE(req: Request, { params }: { params: { name: string } }) {
     const name = decodeURIComponent(params.name);
@@ -12,8 +14,9 @@ export async function DELETE(req: Request, { params }: { params: { name: string
     }
 
     if (await isProcessRunning(proc.pid)) {
-        await terminateProcess(proc.pid);
+        await measure(`Terminate "${name}" before delete`, () => terminateProcess(proc.pid));
     }
+
     removeProcessByName(name);
     return Response.json({ success: true });
 }

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

@@ -1,13 +1,11 @@
-/**
- * GET /api/processes — Enriched process list
- * 
- * Uses batch subprocess calls (single tasklist + single netstat)
- * instead of per-process calls to avoid subprocess pile-up on Windows.
- * Results are cached for 5 seconds via globalThis.
- */
-import { getAllProcesses, calculateRuntime, getProcessBatchMemory, getDbInfo } from 'bgrun';
+import { getAllProcesses, updateProcessPid } from '../../../../src/db';
+import { calculateRuntime } from '../../../../src/utils';
+import { getProcessBatchMemory, reconcileProcessPids } from '../../../../src/platform';
+import { measure, createMeasure } from 'measure-fn';
 import { $ } from 'bun';
 
+const api = createMeasure('api');
+
 const CACHE_TTL_MS = 5_000;
 const SUBPROCESS_TIMEOUT_MS = 4_000;
 
@@ -105,46 +103,87 @@ function getProcessGroup(envStr: string): string | null {
     return match ? match[1] : null;
 }
 
-// ... existing code ...
-
 async function fetchProcesses(): Promise<any[]> {
-    const procs = getAllProcesses();
-    const pids = procs.map((p: any) => p.pid);
-
-    // Three subprocess calls total (not 3×N)
-    const [runningPids, portMap, memoryMap] = await Promise.all([
-        withTimeout(getRunningPids(pids), new Set<number>()),
-        withTimeout(getPortsByPid(pids), new Map<number, number[]>()),
-        // Use the new batch memory fetcher
-        withTimeout(getProcessBatchMemory(pids), new Map<number, number>()),
-    ]);
+    return await api.measure('Fetch processes', async (m) => {
+        const procs = getAllProcesses();
+        const pids = procs.map((p: any) => p.pid);
+
+        // Three subprocess calls total (not 3×N)
+        let [runningPids, portMap, memoryMap] = 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>())),
+        ]);
+
+        // PID reconciliation: if stored PIDs are dead, try to find the real process
+        const allPids = new Set(pids);
+        const deadPids = new Set(pids.filter((pid: number) => !runningPids?.has(pid)));
+
+        if (deadPids.size > 0) {
+            const reconciled = await m('Reconcile dead PIDs', () =>
+                withTimeout(reconcileProcessPids(procs, deadPids), new Map<string, number>())
+            );
+
+            if (reconciled && reconciled.size > 0) {
+                // Update stored PIDs in DB and refresh running status
+                const newPids: number[] = [];
+                for (const [name, newPid] of reconciled) {
+                    updateProcessPid(name, newPid);
+                    newPids.push(newPid);
+                    // Update the proc object in-place so the response uses the new PID
+                    const proc = procs.find((p: any) => p.name === name);
+                    if (proc) proc.pid = newPid;
+                }
 
-    return procs.map((p: any) => {
-        const running = runningPids.has(p.pid);
-        const ports = running ? (portMap.get(p.pid) || []) : [];
-        const memory = running ? (memoryMap.get(p.pid) || 0) : 0;
-
-        return {
-            name: p.name,
-            command: p.command,
-            directory: p.workdir,
-            pid: p.pid,
-            running,
-            port: ports.length > 0 ? ports[0] : null,
-            ports,
-            memory, // Bytes
-            group: getProcessGroup(p.env),
-            runtime: calculateRuntime(p.timestamp),
-            timestamp: p.timestamp,
-        };
-    });
+                // Mark reconciled PIDs as running
+                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([
+                    withTimeout(getPortsByPid(newPids), new Map<number, number[]>()),
+                    withTimeout(getProcessBatchMemory(newPids), new Map<number, number>()),
+                ]);
+                if (!portMap) portMap = new Map();
+                if (!memoryMap) memoryMap = new Map();
+                for (const [pid, ports] of newPorts) portMap.set(pid, ports);
+                for (const [pid, mem] of newMem) memoryMap.set(pid, mem);
+            }
+        }
+
+        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;
+
+            return {
+                name: p.name,
+                command: p.command,
+                directory: p.workdir,
+                pid: p.pid,
+                running,
+                port: ports.length > 0 ? ports[0] : null,
+                ports,
+                memory, // Bytes
+                group: getProcessGroup(p.env),
+                runtime: calculateRuntime(p.timestamp),
+                timestamp: p.timestamp,
+                env: p.env || '',
+                configPath: p.configPath || '',
+                stdoutPath: p.stdout_path || '',
+                stderrPath: p.stderr_path || '',
+            };
+        });
+    }) ?? [];
 }
 
-export async function GET() {
+export async function GET(req: Request) {
+    const url = new URL(req.url);
+    const bustCache = url.searchParams.has('t');
     const now = Date.now();
 
-    // Return cached data if still fresh
-    if (cache.data && (now - cache.timestamp) < CACHE_TTL_MS) {
+    // Return cached data if still fresh and no bust param
+    if (!bustCache && cache.data && (now - cache.timestamp) < CACHE_TTL_MS) {
         return Response.json(cache.data);
     }
 
@@ -161,6 +200,11 @@ export async function GET() {
         });
     }
 
-    const result = await cache.inflight;
-    return Response.json(result);
+    try {
+        const result = await cache.inflight;
+        return Response.json(result);
+    } catch (err) {
+        console.error('[api/processes] Error fetching processes:', err);
+        return Response.json(cache.data ?? []);
+    }
 }

package/dashboard/app/api/restart/[name]/route.ts

@@ -1,18 +1,19 @@
 /**
  * POST /api/restart/:name — Force-restart a process
  */
-import { handleRun } from 'bgrun';
+import { handleRun } from '../../../../../src/commands/run';
+import { measure } from 'measure-fn';
 
 export async function POST(req: Request, { params }: { params: { name: string } }) {
     const name = decodeURIComponent(params.name);
 
     try {
-        await handleRun({
+        await measure(`Restart "${name}"`, () => handleRun({
             action: 'run',
             name,
             force: true,
             remoteName: '',
-        });
+        }));
         return Response.json({ success: true });
     } catch (e: any) {
         return Response.json({ error: e.message }, { status: 500 });

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

@@ -1,20 +1,21 @@
 /**
  * POST /api/start — Create or start a process
  */
-import { handleRun } from 'bgrun';
+import { handleRun } from '../../../../src/commands/run';
+import { measure } from 'measure-fn';
 
 export async function POST(req: Request) {
     const body = await req.json();
 
     try {
-        await handleRun({
+        await measure(`Start process "${body.name}"`, () => handleRun({
             action: 'run',
             name: body.name,
             command: body.command,
             directory: body.directory,
             force: body.force || false,
             remoteName: '',
-        });
+        }));
         return Response.json({ success: true });
     } catch (e: any) {
         return Response.json({ error: e.message }, { status: 500 });

package/dashboard/app/api/stop/[name]/route.ts

@@ -1,16 +1,23 @@
 /**
  * POST /api/stop/:name — Stop a running process
  */
-import { getProcess, isProcessRunning, terminateProcess } from 'bgrun';
+import { getProcess } from '../../../../../src/db';
+import { isProcessRunning, terminateProcess } from '../../../../../src/platform';
+import { measure } from 'measure-fn';
 
 export async function POST(req: Request, { params }: { params: { name: string } }) {
     const name = decodeURIComponent(params.name);
     const proc = getProcess(name);
 
-    if (!proc || !(await isProcessRunning(proc.pid))) {
-        return Response.json({ error: 'Process not found or not running' }, { status: 404 });
+    if (!proc) {
+        return Response.json({ error: 'Process not found' }, { status: 404 });
     }
 
-    await terminateProcess(proc.pid);
+    const running = await isProcessRunning(proc.pid);
+    if (!running) {
+        return Response.json({ error: 'Process not running' }, { status: 404 });
+    }
+
+    await measure(`Stop "${name}" (PID ${proc.pid})`, () => terminateProcess(proc.pid));
     return Response.json({ success: true });
 }

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

@@ -1,8 +1,10 @@
 /**
  * GET /api/version — Return BGR version
  */
-import { getVersion } from 'bgrun';
+import { getVersion } from '../../../../src/utils';
+import { measure } from 'measure-fn';
 
 export async function GET() {
-    return Response.json({ version: await getVersion() });
+    const version = await measure('Get version', () => getVersion());
+    return Response.json({ version });
 }