bgrun 3.12.16 → 3.12.22

package/README.md

@@ -12,8 +12,8 @@
 Start, stop, restart, and monitor any process — from dev servers to Docker containers.
 Zero config. One command. Beautiful dashboard included.
 
-```
-bun install -g bgrun
+```bash
+bunx bgrun --help
 ```
 
 </div>
@@ -35,24 +35,36 @@ bun install -g bgrun
 | Programmatic API | ✅ | ✅ (first-class TypeScript) |
 | Process persistence | ✅ | ✅ (SQLite) |
 
-> **Note:** The CLI is available as both `bgrun` and `bgr` (alias). All examples below use `bgrun`.
+> **Note:** Prefer `bunx bgrun`. Bare `bgrun` only works if you installed it globally or already have a matching shim on `PATH`.
 
 ---
 
 ## Quick Start
 
 ```bash
-# Install globally
-bun install -g bgrun
+# Run without a global install
+bunx bgrun --help
+
+# Skip automatic .config.toml loading for one-off commands
+bunx bgrun --no-config -- bun run script.ts
+
+# Start a process
+bunx bgrun --name my-api --directory ./my-project --command "bun run server.ts"
+
+# Start a managed process with an auto-generated date name
+bunx bgrun -- bun run server.ts
 
-# Start a process
-bgrun --name my-api --directory ./my-project --command "bun run server.ts"
+# Run in the current terminal with config env loaded
+bunx bgrun inline -- bun run dev
+
+# Export config env into your current shell
+Invoke-Expression (bunx bgrun envit)
 
 # List all processes
-bgrun
+bunx bgrun
 
 # Open the web dashboard
-bgrun --dashboard
+bunx bgrun --dashboard
 ```
 
 That's it. bgrun tracks the PID, captures stdout/stderr, detects the port, and survives terminal close.
@@ -62,7 +74,7 @@ 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.
+Launch with `bunx bgrun --dashboard` and open `http://localhost:3001`. Processes are auto-grouped by working directory.
 
 **Expose with Caddy** for remote access:
 
@@ -117,6 +129,14 @@ bgrun --name my-api \
     --command "bun run server.ts"
 ```
 
+Anonymous managed start:
+
+```bash
+bgrun -- bun run server.ts
+```
+
+This generates a date-based name such as `april-fifth`. If that name already exists, bgrun appends `-hhmmss`.
+
 Short form — if you're already *in* the project directory:
 
 ```bash
@@ -403,14 +423,33 @@ The convention: `[section]` becomes the prefix, `key` becomes the suffix, joined
 
 If no `--config` is specified, bgrun looks for `.config.toml` in the working directory automatically.
 
----
+### Loading config env without managing the process
+
+Run a command in the current terminal with config env applied:
+
+```bash
+bgrun inline -- bun run dev
+```
 
-## Programmatic API
+Print shell commands that export config values into your current shell:
 
-bgrun exposes its internals as importable TypeScript functions:
+```powershell
+Invoke-Expression (bgrun envit)
+```
+
+```bash
+eval "$(bgrun envit --shell sh)"
+```
+
+---
 
-> **Packaging note:** the CLI ships from `dist/index.js`, the Bun programmatic API resolves through `dist/api.js`, and the dashboard backend uses built `dist/*` runtime artifacts via `dashboard/lib/runtime.ts`.
-> Published packages are now `dist`-first; repository `src/` files remain the development/build source of truth and are not part of the runtime package surface.
+## Programmatic API
+
+bgrun exposes its internals as importable TypeScript functions:
+
+> **Packaging note:** the CLI ships from `dist/index.js`, the Bun programmatic API resolves through `dist/api.js`, and the dashboard backend uses built `dist/*` runtime artifacts via `dashboard/lib/runtime.ts`.
+> Published packages are now `dist`-first; repository `src/` files remain the development/build source of truth and are not part of the runtime package surface.
+> **Build hooks:** `npm`/`bun` runs the package `prepare` script on local install from the repo and before packing/publishing, so `bun run build` is triggered to refresh `dist/`. `prepublishOnly` also runs `bun run build` right before `npm publish`.
 
 ```bash
 bun add bgrun

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

@@ -1,11 +1,8 @@
 /**
- * POST /api/guard — Toggle BGR_KEEP_ALIVE for a process
+ * POST /api/guard — Toggle per-process watcher guard
  * 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, addHistoryEntry } from '../../../lib/runtime';
+import { getProcess, updateProcessEnv, addHistoryEntry, parseEnvString, stringifyEnvString, syncProcessWatcher } from '../../../lib/runtime';
 
 export async function POST(req: Request) {
     try {
@@ -20,22 +17,17 @@ export async function POST(req: Request) {
         }
 
         // Parse existing env
-        let env: Record<string, string> = {};
-        if (proc.env) {
-            try { env = JSON.parse(proc.env); } catch { env = {}; }
-        }
+        const env = parseEnvString(proc.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));
+        updateProcessEnv(body.name, stringifyEnvString(env));
+        await syncProcessWatcher(body.name, env);
 
-        // Record history
         addHistoryEntry(body.name, body.enabled ? 'guard_on' : 'guard_off');
 
         return Response.json({

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

@@ -1,13 +1,8 @@
 /**
- * POST /api/guard-all — Bulk toggle guard for all processes
+ * POST /api/guard-all — Bulk toggle per-process watcher guard
  * 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 '../../../lib/runtime';
-
-const SKIP = new Set(['bgr-dashboard']);
+import { getAllProcesses, updateProcessEnv, parseEnvString, stringifyEnvString, syncProcessWatcher, isInternalProcessName } from '../../../lib/runtime';
 
 export async function POST(req: Request) {
     try {
@@ -16,13 +11,9 @@ export async function POST(req: Request) {
         let count = 0;
 
         for (const proc of processes) {
-            if (SKIP.has(proc.name)) continue;
+            if (isInternalProcessName(proc.name)) continue;
 
-            // Parse existing env
-            let env: Record<string, string> = {};
-            if (proc.env) {
-                try { env = JSON.parse(proc.env); } catch { env = {}; }
-            }
+            const env = parseEnvString(proc.env || '');
 
             const alreadyGuarded = env.BGR_KEEP_ALIVE === 'true';
             if (body.enabled && alreadyGuarded) continue;
@@ -34,7 +25,8 @@ export async function POST(req: Request) {
                 delete env.BGR_KEEP_ALIVE;
             }
 
-            updateProcessEnv(proc.name, JSON.stringify(env));
+            updateProcessEnv(proc.name, stringifyEnvString(env));
+            await syncProcessWatcher(proc.name, env);
             count++;
         }
 

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

@@ -1,5 +1,5 @@
-import { guardEvents } from '../../../lib/runtime';
+import { getRecentGuardEvents } from '../../../lib/runtime';
 
 export async function GET() {
-    return Response.json(guardEvents);
-}
+    return Response.json(getRecentGuardEvents());
+}

package/dashboard/app/api/next-port/route.ts

@@ -4,7 +4,7 @@
  * Scans existing processes' env for PORT= values,
  * then returns the next unused port starting from a base (default 3001).
  */
-import { getAllProcesses } from '../../../lib/runtime';
+import { getAllProcesses, parseCommandEnv } from '../../../lib/runtime';
 
 export async function GET(req: Request) {
     const url = new URL(req.url);
@@ -14,19 +14,39 @@ export async function GET(req: Request) {
     const usedPorts = new Set<number>();
 
     for (const proc of processes) {
-        // Parse PORT from env string (comma-separated KEY=VAL)
+        // Parse PORT/BUN_PORT from both stored env and inline command env.
         const envStr = proc.env || '';
-        const portMatch = envStr.match(/(?:^|,)PORT=(\d+)/);
-        if (portMatch) {
-            usedPorts.add(parseInt(portMatch[1]));
+        const storedPortMatch = envStr.match(/(?:^|,)(?:PORT|BUN_PORT)=(\d+)/);
+        if (storedPortMatch) {
+            usedPorts.add(parseInt(storedPortMatch[1]));
+        }
+
+        const commandEnv = parseCommandEnv(proc.command || '');
+        const commandPort = parseInt(commandEnv.PORT || commandEnv.BUN_PORT || '', 10);
+        if (!isNaN(commandPort) && commandPort > 0) {
+            usedPorts.add(commandPort);
         }
     }
 
-    // Find next available port
+    // Find next available port, skipping both registered and actually-bound ports
     let nextPort = base;
-    while (usedPorts.has(nextPort)) {
+    while (usedPorts.has(nextPort) || await isPortInUse(nextPort)) {
         nextPort++;
     }
 
     return Response.json({ port: nextPort, usedPorts: Array.from(usedPorts).sort((a, b) => a - b) });
 }
+
+async function isPortInUse(port: number): Promise<boolean> {
+    try {
+        const server = Bun.serve({
+            port,
+            hostname: '127.0.0.1',
+            fetch() { return new Response(''); },
+        });
+        server.stop(true);
+        return false;
+    } catch {
+        return true;
+    }
+}

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

@@ -1,7 +1,5 @@
-import { getAllProcesses, updateProcessPid } from '../../../lib/runtime';
-import { calculateRuntime } from '../../../lib/runtime';
-import { getProcessBatchResources, reconcileProcessPids } from '../../../lib/runtime';
-import { guardRestartCounts } from '../../../lib/runtime';
+import { getAllProcesses, updateProcessPid, calculateRuntime, getGuardRestartCounts, isInternalProcessName } from '../../../lib/runtime';
+import { getProcessBatchResources, reconcileProcessPids, resolvePidWithPorts, getProcessPorts, findChildPid } from '../../../../dist/api.js';
 import { measure, createMeasure } from 'measure-fn';
 import { $ } from 'bun';
 
@@ -111,8 +109,9 @@ function getProcessGroup(envStr: string): string | null {
 
 async function fetchProcesses(): Promise<any[]> {
     return await api.measure('Fetch processes', async (m) => {
-        const procs = getAllProcesses();
+        const procs = getAllProcesses().filter((p: any) => !isInternalProcessName(p.name));
         const pids = procs.map((p: any) => p.pid);
+        const guardRestartCounts = getGuardRestartCounts();
 
         // Three subprocess calls total (not 3×N)
         let [runningPids, portMap, resourceMap] = await Promise.all([
@@ -160,6 +159,33 @@ async function fetchProcesses(): Promise<any[]> {
         const now = Date.now();
         const isWin = process.platform === 'win32';
 
+        for (const p of procs) {
+            const running = runningPids?.has(p.pid) ?? false;
+            const ports = running ? (portMap?.get(p.pid) || []) : [];
+            if (!running || ports.length > 0) continue;
+
+            const resolved = await m(`Resolve live wrapper PID for ${p.name}`, () =>
+                withTimeout(resolvePidWithPorts(p.pid), { pid: p.pid, ports: [] })
+            );
+            if (resolved.pid !== p.pid && resolved.ports.length > 0) {
+                const oldPid = p.pid;
+                p.pid = resolved.pid;
+                updateProcessPid(p.name, resolved.pid);
+                runningPids?.delete(oldPid);
+                runningPids?.add(resolved.pid);
+                portMap?.set(resolved.pid, resolved.ports);
+
+                const refreshedResource = await withTimeout(
+                    getProcessBatchResources([resolved.pid]),
+                    new Map<number, { memory: number, cpu: number }>()
+                );
+                const nextResource = refreshedResource.get(resolved.pid);
+                if (nextResource) {
+                    resourceMap?.set(resolved.pid, nextResource);
+                }
+            }
+        }
+
         return procs.map((p: any) => {
             const running = runningPids?.has(p.pid) ?? false;
             const ports = running ? (portMap?.get(p.pid) || []) : [];

package/dashboard/app/page.client.tsx

@@ -744,7 +744,7 @@ export default function mount(): () => void {
         if (!btn || !label) return;
 
         const targetCount = allProcesses.filter(p => {
-            if (p.name === 'bgr-dashboard' || p.name === 'bgr-guard') return false;
+            if (p.name === 'bgr-dashboard') return false;
             if (groupQuery && p.group !== groupQuery) return false;
             return true;
         }).length;
@@ -806,23 +806,6 @@ export default function mount(): () => void {
             guardAllBtn.title = allGuarded ? 'Remove guard from all processes' : 'Guard all processes (auto-restart on crash)';
         }
 
-        // Update guard sentinel pill
-        const guardPill = $('guard-sentinel-pill');
-        const guardLabel = $('guard-sentinel-label');
-        if (guardPill && guardLabel) {
-            const guardProc = processes.find(p => p.name === 'bgr-guard');
-            guardPill.classList.remove('active', 'stopped');
-            if (guardProc && guardProc.running) {
-                guardPill.classList.add('active');
-                const restarts = guardProc.guardRestarts || 0;
-                guardLabel.textContent = restarts > 0 ? `Guard: ON (${restarts}↻)` : 'Guard: ON';
-            } else if (guardProc) {
-                guardPill.classList.add('stopped');
-                guardLabel.textContent = 'Guard: OFF';
-            } else {
-                guardLabel.textContent = 'Guard: –';
-            }
-        }
     }
 
     function toggleGroup(groupDir: string) {
@@ -3428,7 +3411,7 @@ export default function mount(): () => void {
         if (!deployAllBtn || deployAllBtn.disabled) return;
 
         const targets = allProcesses.filter(p => {
-            if (p.name === 'bgr-dashboard' || p.name === 'bgr-guard') return false;
+            if (p.name === 'bgr-dashboard') return false;
             if (groupQuery && p.group !== groupQuery) return false;
             return true;
         });

package/dashboard/app/page.tsx

@@ -50,7 +50,7 @@ export default function DashboardPage() {
             {/* Guard Activity Feed */}
             <div className="guard-activity" id="guard-activity">
                 <div className="guard-activity-header">
-                    <span className="guard-activity-title">🛡️ Guard Activity</span>
+                    <span className="guard-activity-title">🛡️ Watcher Activity</span>
                     <span className="guard-activity-empty" id="guard-activity-empty">No recent activity</span>
                 </div>
                 <div className="guard-activity-list" id="guard-activity-list"></div>
@@ -122,10 +122,6 @@ export default function DashboardPage() {
                             </svg>
                         </button>
                     </div>
-                    <span className="guard-sentinel-pill" id="guard-sentinel-pill" title="Standalone guard process status">
-                        <span className="guard-sentinel-dot" id="guard-sentinel-dot" />
-                        <span id="guard-sentinel-label">Guard: –</span>
-                    </span>
                     <button className="btn btn-ghost btn-icon" id="theme-toggle-btn" title="Toggle light/dark theme">
                         <span id="theme-toggle-icon" style={{ fontSize: '0.85rem' }}>🌙</span>
                     </button>

package/dashboard/lib/runtime.ts

@@ -1,49 +1,58 @@
-export {
-  db,
-  getAllProcesses,
-  getProcess,
-  insertProcess,
-  removeProcess,
-  removeProcessByName,
-  removeAllProcesses,
-  updateProcessPid,
-  updateProcessEnv,
-  getAllTemplates,
-  saveTemplate,
-  deleteTemplate,
-  getProcessHistory,
-  getRecentHistory,
-  addHistoryEntry,
-  getDependencyGraph,
-  addDependency,
-  removeDependency,
-  getStartOrder,
-  getDbInfo,
-  dbPath,
-  bgrHome,
-  isProcessRunning,
-  terminateProcess,
-  readFileTail,
-  getProcessPorts,
-  findChildPid,
-  findPidByPort,
-  getShellCommand,
-  killProcessOnPort,
-  waitForPortFree,
-  ensureDir,
-  getHomeDir,
-  isWindows,
-  getProcessBatchResources,
-  getProcessMemory,
-  reconcileProcessPids,
-  handleRun,
-  getVersion,
-  calculateRuntime,
-  parseEnvString,
-  validateDirectory,
-} from '../../dist/api.js'
-
-export { deployProcess, deployAllProcesses } from '../../dist/deploy.js'
-export { buildDepGraph } from '../../dist/deps.js'
-export { rotateAllLogs } from '../../dist/log-rotation.js'
-export { guardEvents, guardRestartCounts } from '../../dist/server.js'
+export {
+  db,
+  getAllProcesses,
+  getProcess,
+  insertProcess,
+  removeProcess,
+  removeProcessByName,
+  removeAllProcesses,
+  updateProcessPid,
+  updateProcessEnv,
+  getAllTemplates,
+  saveTemplate,
+  deleteTemplate,
+  getProcessHistory,
+  getRecentHistory,
+  addHistoryEntry,
+  getDependencyGraph,
+  addDependency,
+  removeDependency,
+  getStartOrder,
+  getDbInfo,
+  dbPath,
+  bgrHome,
+  isProcessRunning,
+  terminateProcess,
+  readFileTail,
+  getProcessPorts,
+  findChildPid,
+  findPidByPort,
+  resolvePidWithPorts,
+  getShellCommand,
+  killProcessOnPort,
+  waitForPortFree,
+  ensureDir,
+  getHomeDir,
+  isWindows,
+  getProcessBatchResources,
+  getProcessMemory,
+  reconcileProcessPids,
+  handleRun,
+  ensureProcessWatcher,
+  stopProcessWatcher,
+  syncProcessWatcher,
+  getGuardRestartCounts,
+  getRecentGuardEvents,
+  getVersion,
+  calculateRuntime,
+  parseEnvString,
+  stringifyEnvString,
+  validateDirectory,
+} from '../../dist/api.js'
+
+export { deployProcess, deployAllProcesses } from '../../dist/deploy.js'
+export { buildDepGraph } from '../../dist/deps.js'
+export { rotateAllLogs } from '../../dist/log-rotation.js'
+
+export const guardEvents: any[] = []
+export const guardRestartCounts = new Map<string, number>()