bgrun 3.3.1

package/examples/bgr-startup.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# bgr-startup.sh - Example startup script for BGR processes
+# Place in /usr/local/bin/bgr-startup.sh and make executable
+
+# Wait for network to be ready
+sleep 5
+
+# Start database services
+echo "Starting database services..."
+bgr --name postgres --command "postgres -D /var/lib/postgresql/data"
+bgr --name redis --command "redis-server /etc/redis/redis.conf"
+
+# Wait for databases to be ready
+sleep 3
+
+# Start web server / reverse proxy
+echo "Starting web server..."
+bgr --name caddy --directory /etc/caddy --command "caddy run"
+
+# Start application services
+echo "Starting application services..."
+bgr --name api \
+    --directory /var/www/api \
+    --command "node dist/server.js" \
+    --config production.toml
+
+bgr --name worker \
+    --directory /var/www/worker \
+    --command "python worker.py" \
+    --config production.toml
+
+# Optional: Start monitoring guards
+echo "Starting process guards..."
+bgr --name api-guard \
+    --directory /var/www/api \
+    --command "bun /opt/bgr/examples/guard.ts api 30"
+
+# Show final status
+echo "All services started. Current status:"
+bgr

package/package.json

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

package/src/api.ts

@@ -0,0 +1,31 @@
+/**
+ * BGR Public API (package: bgrun)
+ * 
+ * Import from 'bgrun' to use these functions in your own process-managing apps.
+ * 
+ * @example
+ * ```ts
+ * import { getAllProcesses, isProcessRunning, handleRun } from 'bgrun'
+ * 
+ * // List all managed processes
+ * const processes = getAllProcesses()
+ * 
+ * // Check if a process is running
+ * const alive = await isProcessRunning(process.pid)
+ * 
+ * // Start a new managed process
+ * await handleRun({ name: 'my-app', command: 'bun run dev', directory: './my-app', action: 'run', remoteName: '' })
+ * ```
+ */
+
+// --- Database Operations ---
+export { db, getAllProcesses, getProcess, insertProcess, removeProcess, removeProcessByName, removeAllProcesses, retryDatabaseOperation } from './db'
+
+// --- Process Operations ---
+export { isProcessRunning, terminateProcess, readFileTail, getProcessPorts, findChildPid, findPidByPort, getShellCommand, killProcessOnPort, waitForPortFree, ensureDir, getHomeDir, isWindows } from './platform'
+
+// --- High-Level Commands ---
+export { handleRun } from './commands/run'
+
+// --- Utilities ---
+export { getVersion, calculateRuntime, parseEnvString, validateDirectory } from './utils'

package/src/build.ts

@@ -0,0 +1,26 @@
+import { EOL } from 'os';
+
+console.log("Starting build process for bgrun...");
+
+const result = await Bun.build({
+  entrypoints: ['./src/index.ts'],
+  outdir: './dist',
+  target: 'bun',
+  format: 'esm',
+  minify: false,
+  // Mark all packages as external to rely on node_modules
+  // This avoids bundling native modules or mismatched React versions
+  packages: "external",
+});
+
+if (!result.success) {
+  console.error("Build failed");
+  for (const message of result.logs) {
+    console.error(message);
+  }
+  process.exit(1);
+}
+
+const outFile = result.outputs[0].path;
+
+console.log(`Build successful! Executable created at: ${outFile}`);

package/src/commands/cleanup.ts

@@ -0,0 +1,142 @@
+
+import { getProcess, removeProcessByName, removeProcess, getAllProcesses, removeAllProcesses } from "../db";
+import { isProcessRunning, terminateProcess } from "../platform";
+import { announce, error } from "../logger";
+import type { ProcessRecord } from "../types";
+import * as fs from "fs";
+
+export async function handleDelete(name: string) {
+    const process = getProcess(name); // Wrapper or raw query needed if getProcess doesn't return full type
+    // getProcess returns ProcessRecord | null
+
+    if (!process) {
+        error(`No process found named '${name}'`);
+        // error calls process.exit(1), so we return but TS doesn't know. 
+        return;
+    }
+
+    const isRunning = await isProcessRunning(process.pid);
+    if (isRunning) {
+        await terminateProcess(process.pid);
+    }
+
+    if (fs.existsSync(process.stdout_path)) {
+        try { fs.unlinkSync(process.stdout_path); } catch { }
+    }
+    if (fs.existsSync(process.stderr_path)) {
+        try { fs.unlinkSync(process.stderr_path); } catch { }
+    }
+
+    removeProcessByName(name);
+    announce(`Process '${name}' has been ${isRunning ? 'stopped and ' : ''}deleted`, "Process Deleted");
+}
+
+export async function handleClean() {
+    const processes = getAllProcesses();
+    let cleanedCount = 0;
+    let deletedLogs = 0;
+
+    for (const proc of processes) {
+        const running = await isProcessRunning(proc.pid);
+        if (!running) {
+            removeProcess(proc.pid);
+            cleanedCount++;
+
+            if (fs.existsSync(proc.stdout_path)) {
+                try { fs.unlinkSync(proc.stdout_path); deletedLogs++; } catch { }
+            }
+            if (fs.existsSync(proc.stderr_path)) {
+                try { fs.unlinkSync(proc.stderr_path); deletedLogs++; } catch { }
+            }
+        }
+    }
+
+    if (cleanedCount === 0) {
+        announce("No stopped processes found to clean.", "Clean Complete");
+    } else {
+        announce(
+            `Cleaned ${cleanedCount} stopped ${cleanedCount === 1 ? 'process' : 'processes'} and removed ${deletedLogs} log ${deletedLogs === 1 ? 'file' : 'files'}.`,
+            "Clean Complete"
+        );
+    }
+}
+
+export async function handleStop(name: string) {
+    const proc = getProcess(name);
+
+    if (!proc) {
+        error(`No process found named '${name}'`);
+        return;
+    }
+
+    const isRunning = await isProcessRunning(proc.pid);
+    if (!isRunning) {
+        announce(`Process '${name}' is already stopped.`, "Process Stop");
+        return;
+    }
+
+    // Detect ports the process is using BEFORE killing it
+    const { getProcessPorts, killProcessOnPort } = await import("../platform");
+    const ports = await getProcessPorts(proc.pid);
+
+    await terminateProcess(proc.pid);
+
+    // Also kill by detected ports as safety net
+    for (const port of ports) {
+        await killProcessOnPort(port);
+    }
+
+    announce(`Process '${name}' has been stopped (kept in registry).`, "Process Stopped");
+}
+
+export async function handleDeleteAll() {
+    const processes = getAllProcesses();
+    if (processes.length === 0) {
+        announce("There are no processes to delete.", "Delete All");
+        return;
+    }
+
+    const { getProcessPorts, killProcessOnPort, waitForPortFree } = await import("../platform");
+    let killedCount = 0;
+    let portsFreed = 0;
+
+    for (const proc of processes) {
+        const running = await isProcessRunning(proc.pid);
+
+        if (running) {
+            // Detect ports BEFORE killing so we can clean them up
+            const ports = await getProcessPorts(proc.pid);
+
+            // Force-kill the process tree
+            await terminateProcess(proc.pid, true);
+            killedCount++;
+
+            // Kill anything still holding the ports
+            for (const port of ports) {
+                await killProcessOnPort(port);
+                const freed = await waitForPortFree(port, 3000);
+                if (!freed) {
+                    await killProcessOnPort(port);
+                    await waitForPortFree(port, 2000);
+                }
+                portsFreed++;
+            }
+        }
+
+        // Clean up log files
+        if (fs.existsSync(proc.stdout_path)) {
+            try { fs.unlinkSync(proc.stdout_path); } catch { }
+        }
+        if (fs.existsSync(proc.stderr_path)) {
+            try { fs.unlinkSync(proc.stderr_path); } catch { }
+        }
+    }
+
+    removeAllProcesses();
+
+    const parts = [`${processes.length} ${processes.length === 1 ? 'process' : 'processes'} deleted`];
+    if (killedCount > 0) parts.push(`${killedCount} force-killed`);
+    if (portsFreed > 0) parts.push(`${portsFreed} ${portsFreed === 1 ? 'port' : 'ports'} freed`);
+
+    announce(parts.join(', ') + '.', "Nuke Complete");
+}

package/src/commands/details.ts

@@ -0,0 +1,46 @@
+
+import { error, announce } from "../logger";
+import { getProcess } from "../db";
+import { isProcessRunning, calculateRuntime, parseEnvString } from "../utils";
+import { getProcessPorts } from "../platform";
+import chalk from "chalk";
+
+export async function showDetails(name: string) {
+    const proc = getProcess(name);
+    if (!proc) {
+        error(`No process found named '${name}'`);
+        return;
+    }
+
+    const isRunning = await isProcessRunning(proc.pid, proc.command);
+    const runtime = calculateRuntime(proc.timestamp);
+    const envVars = parseEnvString(proc.env);
+
+    // Detect actual ports via OS
+    const ports = isRunning ? await getProcessPorts(proc.pid) : [];
+
+    const portDisplay = ports.length > 0
+        ? ports.map(p => chalk.hex('#FF6B6B')(`:${p}`)).join(', ')
+        : null;
+
+    const details = `
+${chalk.bold('Process Details:')}
+${chalk.gray('═'.repeat(50))}
+${chalk.cyan.bold('Name:')} ${proc.name}
+${chalk.yellow.bold('PID:')} ${proc.pid}${portDisplay ? `\n${chalk.hex('#FF6B6B').bold('Port:')} ${portDisplay}` : ''}
+${chalk.bold('Status:')} ${isRunning ? chalk.green.bold("● Running") : chalk.red.bold("○ Stopped")}
+${chalk.magenta.bold('Runtime:')} ${runtime}
+${chalk.blue.bold('Working Directory:')} ${proc.workdir}
+${chalk.white.bold('Command:')} ${proc.command}
+${chalk.gray.bold('Config Path:')} ${proc.configPath}
+${chalk.green.bold('Stdout Path:')} ${proc.stdout_path}
+${chalk.red.bold('Stderr Path:')} ${proc.stderr_path}
+
+${chalk.bold('🔧 Environment Variables:')}
+${chalk.gray('═'.repeat(50))}
+${Object.entries(envVars)
+            .map(([key, value]) => `${chalk.cyan.bold(key)} = ${chalk.yellow(value)}`)
+            .join('\n')}
+`;
+    announce(details, `Process Details: ${name}`);
+}

package/src/commands/list.ts

@@ -0,0 +1,86 @@
+import chalk from "chalk";
+import { ProcessTableRow, renderProcessTable } from "../table";
+import { ProcessRecord } from "../types";
+import { getAllProcesses } from "../db";
+import { announce } from "../logger";
+import { isProcessRunning, calculateRuntime, parseEnvString } from "../utils";
+import { getProcessPorts } from "../platform";
+
+export async function showAll(opts?: { json?: boolean; filter?: string }) {
+    const processes = getAllProcesses();
+
+    // Apply filter by env.BGR_GROUP if provided
+    const filtered = processes.filter((proc) => {
+        if (!opts?.filter) return true;
+        const envVars = parseEnvString(proc.env);
+        return envVars["BGR_GROUP"] === opts.filter;
+    });
+
+    if (opts?.json) {
+        // JSON output with filtered env variables
+        const jsonData: any[] = [];
+
+        for (const proc of filtered) {
+            const isRunning = await isProcessRunning(proc.pid, proc.command);
+            const envVars = parseEnvString(proc.env);
+
+            const ports = isRunning ? await getProcessPorts(proc.pid) : [];
+            jsonData.push({
+                pid: proc.pid,
+                name: proc.name,
+                ports: ports.length > 0 ? ports : undefined,
+                status: isRunning ? "running" : "stopped",
+                env: envVars,
+            });
+        }
+
+        console.log(JSON.stringify(jsonData, null, 2));
+        return;
+    }
+
+    // Table output
+    const tableData: ProcessTableRow[] = [];
+
+    for (const proc of filtered) {
+        const isRunning = await isProcessRunning(proc.pid, proc.command);
+        const runtime = calculateRuntime(proc.timestamp);
+
+        const ports = isRunning ? await getProcessPorts(proc.pid) : [];
+        tableData.push({
+            id: proc.id,
+            pid: proc.pid,
+            name: proc.name,
+            port: ports.length > 0 ? ports.map(p => `:${p}`).join(',') : '-',
+            command: proc.command,
+            workdir: proc.workdir,
+            status: isRunning
+                ? chalk.green.bold("● Running")
+                : chalk.red.bold("○ Stopped"),
+            runtime: runtime,
+        });
+    }
+
+    if (tableData.length === 0) {
+        if (opts?.filter) {
+            announce(`No processes matched filter BGR_GROUP='${opts.filter}'.`, "No Matches");
+        } else {
+            announce("No processes found.", "Empty");
+        }
+        return;
+    }
+
+    const tableOutput = renderProcessTable(tableData, {
+        padding: 1,
+        borderStyle: "rounded",
+        showHeaders: true,
+    });
+    console.log(tableOutput);
+
+    const runningCount = tableData.filter((p) => p.status.includes("Running")).length;
+    const stoppedCount = tableData.filter((p) => p.status.includes("Stopped")).length;
+    console.log(
+        chalk.cyan(
+            `Total: ${tableData.length} processes (${chalk.green(`${runningCount} running`)}, ${chalk.red(`${stoppedCount} stopped`)})`
+        )
+    );
+}

package/src/commands/logs.ts

@@ -0,0 +1,49 @@
+import { getProcess } from "../db";
+import { error } from "../logger";
+import { readFileTail } from "../platform";
+import chalk from "chalk";
+import * as fs from "fs";
+
+export async function showLogs(name: string, logType: 'stdout' | 'stderr' | 'both' = 'both', lines?: number) {
+    const proc = getProcess(name);
+    if (!proc) {
+        error(`No process found named '${name}'`);
+        return; // TS shut up
+    }
+
+    if (logType === 'both' || logType === 'stdout') {
+        console.log(chalk.green.bold(`📄 Stdout logs for ${name}:`));
+        console.log(chalk.gray('═'.repeat(50)));
+
+        if (fs.existsSync(proc.stdout_path)) {
+            try {
+                const output = await readFileTail(proc.stdout_path, lines);
+                console.log(output || chalk.gray('(no output)'));
+            } catch (err) {
+                console.log(chalk.red(`Error reading stdout: ${err}`));
+            }
+        } else {
+            console.log(chalk.gray('(log file not found)'));
+        }
+
+        if (logType === 'both') {
+            console.log('\n');
+        }
+    }
+
+    if (logType === 'both' || logType === 'stderr') {
+        console.log(chalk.red.bold(`📄 Stderr logs for ${name}:`));
+        console.log(chalk.gray('═'.repeat(50)));
+
+        if (fs.existsSync(proc.stderr_path)) {
+            try {
+                const output = await readFileTail(proc.stderr_path, lines);
+                console.log(output || chalk.gray('(no errors)'));
+            } catch (err) {
+                console.log(chalk.red(`Error reading stderr: ${err}`));
+            }
+        } else {
+            console.log(chalk.gray('(log file not found)'));
+        }
+    }
+}

package/src/commands/run.ts

@@ -0,0 +1,151 @@
+import { CommandOptions } from "../types";
+import { getProcess, removeProcessByName, retryDatabaseOperation, insertProcess } from "../db";
+import { isProcessRunning, terminateProcess, getHomeDir, getShellCommand, killProcessOnPort, findChildPid, getProcessPorts, waitForPortFree } from "../platform";
+import { error, announce } from "../logger";
+import { validateDirectory, parseEnvString } from "../utils";
+import { parseConfigFile } from "../config";
+import { $ } from "bun";
+import { sleep } from "bun";
+import { join } from "path";
+
+const homePath = getHomeDir();
+
+export async function handleRun(options: CommandOptions) {
+    const { command, directory, env, name, configPath, force, fetch, stdout, stderr } = options;
+
+    const existingProcess = name ? getProcess(name) : null;
+
+    if (existingProcess) {
+        const finalDirectory = directory || existingProcess.workdir;
+        validateDirectory(finalDirectory);
+        $.cwd(finalDirectory);
+
+        if (fetch) {
+            if (!require('fs').existsSync(require('path').join(finalDirectory, '.git'))) {
+                error(`Cannot --fetch: '${finalDirectory}' is not a Git repository.`);
+            }
+            try {
+                await $`git fetch origin`;
+                const localHash = (await $`git rev-parse HEAD`.text()).trim();
+                const remoteHash = (await $`git rev-parse origin/$(git rev-parse --abbrev-ref HEAD)`.text()).trim();
+
+                if (localHash !== remoteHash) {
+                    await $`git pull origin $(git rev-parse --abbrev-ref HEAD)`;
+                    announce("📥 Pulled latest changes", "Git Update");
+                }
+            } catch (err) {
+                error(`Failed to pull latest changes: ${err}`);
+            }
+        }
+
+        const isRunning = await isProcessRunning(existingProcess.pid);
+        if (isRunning && !force) {
+            error(`Process '${name}' is currently running. Use --force to restart.`);
+        }
+
+        // Detect ports BEFORE killing so we can clean them up
+        let detectedPorts: number[] = [];
+        if (isRunning) {
+            detectedPorts = await getProcessPorts(existingProcess.pid);
+        }
+
+        if (isRunning) {
+            await terminateProcess(existingProcess.pid);
+            announce(`🔥 Terminated existing process '${name}'`, "Process Terminated");
+        }
+
+        // Kill anything still on the ports the old process was using
+        for (const port of detectedPorts) {
+            await killProcessOnPort(port);
+        }
+
+        // Wait for all detected ports to free up
+        for (const port of detectedPorts) {
+            const freed = await waitForPortFree(port, 5000);
+            if (!freed) {
+                // Retry kill and wait once more
+                await killProcessOnPort(port);
+                await waitForPortFree(port, 3000);
+            }
+        }
+
+        await retryDatabaseOperation(() =>
+            removeProcessByName(name!)
+        );
+    } else {
+        if (!directory || !name || !command) {
+            error("'directory', 'name', and 'command' parameters are required for new processes.");
+        }
+        validateDirectory(directory!);
+        $.cwd(directory!);
+    }
+
+    const finalCommand = command || existingProcess!.command;
+    const finalDirectory = directory || (existingProcess?.workdir!);
+    let finalEnv = env || (existingProcess ? parseEnvString(existingProcess.env) : {});
+
+    let finalConfigPath: string | undefined | null;
+    if (configPath !== undefined) {
+        finalConfigPath = configPath;
+    } else if (existingProcess) {
+        finalConfigPath = existingProcess.configPath;
+    } else {
+        finalConfigPath = '.config.toml';
+    }
+
+    if (finalConfigPath) {
+        const fullConfigPath = join(finalDirectory, finalConfigPath);
+
+        if (await Bun.file(fullConfigPath).exists()) {
+            try {
+                const newConfigEnv = await parseConfigFile(fullConfigPath);
+                finalEnv = { ...finalEnv, ...newConfigEnv };
+                console.log(`Loaded config from ${finalConfigPath}`);
+            } catch (err: any) {
+                console.warn(`Warning: Failed to parse config file ${finalConfigPath}: ${err.message}`);
+            }
+        } else {
+            console.log(`Config file '${finalConfigPath}' not found, continuing without it.`);
+        }
+    }
+
+    const stdoutPath = stdout || existingProcess?.stdout_path || join(homePath, ".bgr", `${name}-out.txt`);
+    Bun.write(stdoutPath, '');
+    const stderrPath = stderr || existingProcess?.stderr_path || join(homePath, ".bgr", `${name}-err.txt`);
+    Bun.write(stderrPath, '');
+
+    const newProcess = Bun.spawn(getShellCommand(finalCommand!), {
+        env: { ...Bun.env, ...finalEnv },
+        cwd: finalDirectory,
+        stdout: Bun.file(stdoutPath),
+        stderr: Bun.file(stderrPath),
+    });
+
+    newProcess.unref();
+    // Give shell a moment to spawn child, then find PID before shell exits
+    await sleep(100);
+    // Find the actual child PID (shell wrapper exits immediately after spawning)
+    const actualPid = await findChildPid(newProcess.pid);
+    // Wait more for subprocess to initialize
+    await sleep(400);
+
+    await retryDatabaseOperation(() =>
+        insertProcess({
+            pid: actualPid,
+            workdir: finalDirectory,
+            command: finalCommand!,
+            name: name!,
+            env: Object.entries(finalEnv).map(([k, v]) => `${k}=${v}`).join(","),
+            configPath: finalConfigPath || '',
+            stdout_path: stdoutPath,
+            stderr_path: stderrPath,
+        })
+    );
+
+    announce(
+        `${existingProcess ? '🔄 Restarted' : '🚀 Launched'} process "${name}" with PID ${actualPid}`,
+        "Process Started"
+    );
+}
+
+