bgrun 3.11.0 → 3.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bgrun",
-  "version": "3.11.0",
+  "version": "3.12.1",
   "description": "bgrun — A lightweight process manager for Bun",
   "type": "module",
   "main": "./src/api.ts",
@@ -19,6 +19,7 @@
     "dist",
     "src",
     "dashboard/app",
+    "scripts",
     "README.md",
     "image.png",
     "examples/bgr-startup.sh"
@@ -50,7 +51,7 @@
     "chalk": "^5.4.1",
     "dedent": "^1.5.3",
     "measure-fn": "3.10.1",
-    "melina": "2.3.3",
+    "melina": "2.3.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "sqlite-zod-orm": "3.26.1"
@@ -58,4 +59,4 @@
   "engines": {
     "bun": ">=1.0.0"
   }
-}
+}

package/scripts/bgr-startup.ps1

@@ -0,0 +1,118 @@
+# bgr-startup.ps1 — Auto-start bgrun guard on Windows login
+# Ensures all guarded processes (and the dashboard itself) start on boot.
+#
+# Installation:
+#   1. Run this script once with -Install flag:
+#      powershell -ExecutionPolicy Bypass -File bgr-startup.ps1 -Install
+#
+#   2. Or manually create a Task Scheduler task:
+#      - Trigger: At log on
+#      - Action: powershell -WindowStyle Hidden -ExecutionPolicy Bypass -File "C:\Code\bgr\scripts\bgr-startup.ps1"
+#      - Run whether user is logged on or not: Yes
+#
+# Usage:
+#   bgr-startup.ps1           # Start bgrun guard
+#   bgr-startup.ps1 -Install  # Register Task Scheduler entry
+
+param(
+    [switch]$Install
+)
+
+$BunPath = "$env:USERPROFILE\.bun\bin\bun.exe"
+$BgrunPath = "C:\Code\bgr"
+$LogPath = "$env:USERPROFILE\.bgr\startup.log"
+
+function Write-Log {
+    param([string]$Message)
+    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+    $line = "[$timestamp] $Message"
+    Write-Host $line
+    Add-Content -Path $LogPath -Value $line -ErrorAction SilentlyContinue
+}
+
+# Ensure .bgr directory exists
+$bgrDir = "$env:USERPROFILE\.bgr"
+if (-not (Test-Path $bgrDir)) {
+    New-Item -ItemType Directory -Path $bgrDir -Force | Out-Null
+}
+
+if ($Install) {
+    Write-Log "Installing bgrun auto-start task..."
+
+    $scriptPath = $PSCommandPath
+    if (-not $scriptPath) {
+        $scriptPath = Join-Path $BgrunPath "scripts\bgr-startup.ps1"
+    }
+
+    # Remove existing task if present
+    $existingTask = Get-ScheduledTask -TaskName "bgrun-guard" -ErrorAction SilentlyContinue
+    if ($existingTask) {
+        Unregister-ScheduledTask -TaskName "bgrun-guard" -Confirm:$false
+        Write-Log "Removed existing bgrun-guard task"
+    }
+
+    # Create the scheduled task
+    $action = New-ScheduledTaskAction `
+        -Execute "powershell.exe" `
+        -Argument "-WindowStyle Hidden -ExecutionPolicy Bypass -File `"$scriptPath`""
+
+    $trigger = New-ScheduledTaskTrigger -AtLogon
+    $settings = New-ScheduledTaskSettingsSet `
+        -AllowStartIfOnBatteries `
+        -DontStopIfGoingOnBatteries `
+        -StartWhenAvailable `
+        -RestartInterval (New-TimeSpan -Minutes 5) `
+        -RestartCount 3
+
+    Register-ScheduledTask `
+        -TaskName "bgrun-guard" `
+        -Description "bgrun process manager - auto-starts all guarded processes on login" `
+        -Action $action `
+        -Trigger $trigger `
+        -Settings $settings `
+        -RunLevel Highest `
+        -Force
+
+    Write-Log "[OK] Task 'bgrun-guard' registered. Will start on next login."
+    Write-Log "  Script: $scriptPath"
+    exit 0
+}
+
+# ── Main: Start bgrun guard ─────────────────────────────────
+Write-Log "bgrun startup initiated"
+
+# Check bun exists
+if (-not (Test-Path $BunPath)) {
+    Write-Log "ERROR: bun not found at $BunPath"
+    exit 1
+}
+
+# Check bgrun repo exists
+if (-not (Test-Path "$BgrunPath\src\guard.ts")) {
+    Write-Log "ERROR: bgrun not found at $BgrunPath"
+    exit 1
+}
+
+# Start the dashboard first (guard needs it)
+Write-Log "Starting bgrun dashboard..."
+$dashboardProc = Start-Process -FilePath $BunPath `
+    -ArgumentList "run", "$BgrunPath\src\index.ts", "--dashboard", "--port", "3000" `
+    -WindowStyle Hidden `
+    -PassThru `
+    -WorkingDirectory $BgrunPath
+
+Write-Log "Dashboard PID: $($dashboardProc.Id)"
+
+# Wait for dashboard to be ready
+Start-Sleep -Seconds 5
+
+# Start the guard (watches dashboard + all guarded processes)
+Write-Log "Starting bgrun guard..."
+$guardProc = Start-Process -FilePath $BunPath `
+    -ArgumentList "run", "$BgrunPath\src\index.ts", "--guard" `
+    -WindowStyle Hidden `
+    -PassThru `
+    -WorkingDirectory $BgrunPath
+
+Write-Log "Guard PID: $($guardProc.Id)"
+Write-Log "[OK] bgrun startup complete. Dashboard: $($dashboardProc.Id), Guard: $($guardProc.Id)"

package/scripts/bgrun-startup.ps1

@@ -0,0 +1,91 @@
+# bgrun-startup.ps1 — Persistent bgr-dashboard launcher
+# Ensures the bgrun dashboard survives terminal closures.
+# Individual services (geeksy, mm-dash, galaxy-canvas, etc.) are managed
+# by bgr-guard INSIDE the dashboard — this script only keeps the dashboard alive.
+#
+# Usage:
+#   .\bgrun-startup.ps1                  # Start bgr-dashboard
+#   .\bgrun-startup.ps1 -Install         # Register as logon scheduled task
+#   .\bgrun-startup.ps1 -Uninstall       # Remove scheduled task
+#   .\bgrun-startup.ps1 -Guard           # Run guard loop (auto-restart dashboard)
+
+param(
+    [switch]$Install,
+    [switch]$Uninstall,
+    [switch]$Guard
+)
+
+$TaskName = "bgrun-persistence"
+$ScriptPath = $MyInvocation.MyCommand.Path
+
+# ─── Install as Scheduled Task ────────────────────────────
+if ($Install) {
+    $action = New-ScheduledTaskAction `
+        -Execute "pwsh.exe" `
+        -Argument "-WindowStyle Hidden -NonInteractive -File `"$ScriptPath`" -Guard"
+    
+    $trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
+    $settings = New-ScheduledTaskSettingsSet `
+        -AllowStartIfOnBatteries `
+        -DontStopIfGoingOnBatteries `
+        -StartWhenAvailable `
+        -RestartInterval (New-TimeSpan -Minutes 1) `
+        -RestartCount 3 `
+        -ExecutionTimeLimit (New-TimeSpan -Hours 0)  # No time limit
+
+    Register-ScheduledTask `
+        -TaskName $TaskName `
+        -Action $action `
+        -Trigger $trigger `
+        -Settings $settings `
+        -Description "Keeps bgr-dashboard alive across terminal closures. Dashboard's own bgr-guard handles individual services." `
+        -Force
+
+    Write-Host "✅ Scheduled task '$TaskName' registered for user $env:USERNAME"
+    Write-Host "   Runs at logon — keeps bgr-dashboard alive"
+    Write-Host "   To start immediately: schtasks /run /tn '$TaskName'"
+    exit 0
+}
+
+# ─── Uninstall ────────────────────────────────────────────
+if ($Uninstall) {
+    Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction SilentlyContinue
+    Write-Host "🗑️  Scheduled task '$TaskName' removed"
+    exit 0
+}
+
+# ─── Guard mode: keep bgr-dashboard alive ─────────────────
+if ($Guard) {
+    Write-Host "🛡️  bgrun dashboard guard started at $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
+    
+    while ($true) {
+        try {
+            $dashboard = & bgrun --json 2>$null | ConvertFrom-Json | Where-Object { $_.name -eq 'bgr-dashboard' }
+            
+            if (-not $dashboard -or $dashboard.status -ne "running") {
+                Write-Host "[$(Get-Date -Format 'HH:mm:ss')] ⚠️  bgr-dashboard is DOWN — restarting..."
+                & bgrun --restart bgr-dashboard --force 2>$null
+                Start-Sleep -Seconds 3
+            }
+        } catch {
+            Write-Host "[$(Get-Date -Format 'HH:mm:ss')] ❌ Guard check failed: $_"
+        }
+        
+        Start-Sleep -Seconds 60
+    }
+    exit 0
+}
+
+# ─── Default: one-time start ──────────────────────────────
+Write-Host "🚀 Starting bgr-dashboard..."
+$dashboard = & bgrun --json 2>$null | ConvertFrom-Json | Where-Object { $_.name -eq 'bgr-dashboard' }
+if ($dashboard -and $dashboard.status -eq "running") {
+    Write-Host "  ✓ bgr-dashboard already running (PID $($dashboard.pid))"
+} else {
+    & bgrun --restart bgr-dashboard --force 2>$null
+    Start-Sleep -Seconds 2
+    Write-Host "  ✓ bgr-dashboard started"
+}
+Write-Host "`n✅ Done. Dashboard's bgr-guard handles individual services."
+Write-Host "   💡 Run with -Install to persist across terminal closures"
+

package/src/bgrun.test.ts

@@ -0,0 +1,109 @@
+/**
+ * bgrun core utility tests
+ *
+ * Tests pure logic functions: env parsing, config flattening,
+ * string truncation, and runtime calculation.
+ *
+ * Run: bun test src/bgrun.test.ts
+ */
+import { describe, expect, test } from 'bun:test'
+import { parseEnvString, calculateRuntime } from './utils'
+import { stripAnsi, truncateString, truncatePath } from './table'
+
+// ─── parseEnvString ─────────────────────────────────────
+
+describe('parseEnvString', () => {
+    test('parses comma-separated key=value pairs', () => {
+        const result = parseEnvString('PORT=3000,HOST=localhost,DEBUG=true')
+        expect(result).toEqual({
+            PORT: '3000',
+            HOST: 'localhost',
+            DEBUG: 'true',
+        })
+    })
+
+    test('handles single pair', () => {
+        expect(parseEnvString('KEY=value')).toEqual({ KEY: 'value' })
+    })
+
+    test('handles empty string', () => {
+        expect(parseEnvString('')).toEqual({})
+    })
+
+    test('ignores malformed pairs (no =)', () => {
+        const result = parseEnvString('GOOD=yes,BAD,ALSO_GOOD=ok')
+        expect(result.GOOD).toBe('yes')
+        expect(result.ALSO_GOOD).toBe('ok')
+        expect(result.BAD).toBeUndefined()
+    })
+})
+
+// ─── calculateRuntime ───────────────────────────────────
+
+describe('calculateRuntime', () => {
+    test('returns 0 minutes for recent start', () => {
+        const now = new Date().toISOString()
+        expect(calculateRuntime(now)).toBe('0 minutes')
+    })
+
+    test('returns correct minutes', () => {
+        const fiveMinAgo = new Date(Date.now() - 5 * 60 * 1000).toISOString()
+        expect(calculateRuntime(fiveMinAgo)).toBe('5 minutes')
+    })
+
+    test('returns correct for 1 hour', () => {
+        const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000).toISOString()
+        expect(calculateRuntime(oneHourAgo)).toBe('60 minutes')
+    })
+})
+
+// ─── stripAnsi ──────────────────────────────────────────
+
+describe('stripAnsi', () => {
+    test('strips color codes', () => {
+        const colored = '\u001b[31mred text\u001b[0m'
+        expect(stripAnsi(colored)).toBe('red text')
+    })
+
+    test('passes through plain text', () => {
+        expect(stripAnsi('hello world')).toBe('hello world')
+    })
+
+    test('handles empty string', () => {
+        expect(stripAnsi('')).toBe('')
+    })
+})
+
+// ─── truncateString ─────────────────────────────────────
+
+describe('truncateString', () => {
+    test('returns string unchanged if within limit', () => {
+        expect(truncateString('hello', 10)).toBe('hello')
+    })
+
+    test('truncates with ellipsis', () => {
+        const result = truncateString('a very long string that exceeds limit', 15)
+        expect(result.length).toBeLessThanOrEqual(15)
+        expect(result).toContain('…')
+    })
+
+    test('handles maxLength smaller than ellipsis', () => {
+        const result = truncateString('hello world', 2)
+        expect(result.length).toBeLessThanOrEqual(2)
+    })
+})
+
+// ─── truncatePath ───────────────────────────────────────
+
+describe('truncatePath', () => {
+    test('returns path unchanged if within limit', () => {
+        expect(truncatePath('/home/user', 50)).toBe('/home/user')
+    })
+
+    test('truncates middle of long path', () => {
+        const longPath = '/home/user/projects/very/deeply/nested/directory/structure'
+        const result = truncatePath(longPath, 30)
+        expect(result.length).toBeLessThanOrEqual(30)
+        expect(result).toContain('…')
+    })
+})

package/src/commands/details.ts

@@ -1,8 +1,8 @@
 
 import { error, announce } from "../logger";
-import { getProcess } from "../db";
+import { getProcess, updateProcessPid } from "../db";
 import { isProcessRunning, calculateRuntime, parseEnvString } from "../utils";
-import { getProcessPorts } from "../platform";
+import { getProcessPorts, reconcileProcessPids } from "../platform";
 import chalk from "chalk";
 
 export async function showDetails(name: string) {
@@ -12,7 +12,21 @@ export async function showDetails(name: string) {
         return;
     }
 
-    const isRunning = await isProcessRunning(proc.pid, proc.command);
+    let isRunning = await isProcessRunning(proc.pid, proc.command);
+
+    // Reconcile stale PID: cmd.exe wrapper may have exited while bun.exe child lives
+    if (!isRunning && proc.pid > 0) {
+        const reconciled = await reconcileProcessPids(
+            [{ name: proc.name, pid: proc.pid, command: proc.command, workdir: proc.workdir }],
+            new Set([proc.pid]),
+        );
+        const newPid = reconciled.get(proc.name);
+        if (newPid) {
+            updateProcessPid(proc.name, newPid);
+            (proc as any).pid = newPid;
+            isRunning = true;
+        }
+    }
     const runtime = calculateRuntime(proc.timestamp);
     const envVars = parseEnvString(proc.env);
 

package/src/commands/list.ts

@@ -1,10 +1,10 @@
 import chalk from "chalk";
 import { renderProcessTable } from "../table";
 import type { ProcessTableRow } from "../table";
-import { getAllProcesses } from "../db";
+import { getAllProcesses, updateProcessPid } from "../db";
 import { announce } from "../logger";
 import { isProcessRunning, calculateRuntime, parseEnvString } from "../utils";
-import { getProcessPorts, getProcessBatchResources } from "../platform";
+import { getProcessPorts, getProcessBatchResources, reconcileProcessPids } from "../platform";
 import { measure } from "measure-fn";
 
 function formatMemory(bytes: number): string {
@@ -24,12 +24,45 @@ export async function showAll(opts?: { json?: boolean; filter?: string }) {
         return envVars["BGR_GROUP"] === opts.filter;
     });
 
+    // ─── PID Reconciliation ──────────────────────────────────────────
+    // On Windows, the stored PID may be a dead cmd.exe wrapper while the
+    // actual bun.exe child is still running.  Detect dead PIDs up-front,
+    // reconcile them in one batch PowerShell call, and patch the DB so
+    // subsequent invocations are stable (no flicker).
+    const deadPids = new Set<number>();
+    const aliveCache = new Map<number, boolean>();
+
+    for (const proc of filtered) {
+        const alive = await isProcessRunning(proc.pid, proc.command);
+        aliveCache.set(proc.pid, alive);
+        if (!alive && proc.pid > 0) deadPids.add(proc.pid);
+    }
+
+    if (deadPids.size > 0) {
+        const reconciled = await reconcileProcessPids(
+            filtered.map(p => ({ name: p.name, pid: p.pid, command: p.command, workdir: p.workdir })),
+            deadPids,
+        );
+
+        for (const [name, newPid] of reconciled) {
+            updateProcessPid(name, newPid);
+            // Patch the in-memory record so the rest of this function sees
+            // the corrected PID without re-querying the DB.
+            const proc = filtered.find(p => p.name === name);
+            if (proc) {
+                (proc as any).pid = newPid;
+                aliveCache.set(newPid, true);
+            }
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+
     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 isRunning = aliveCache.get(proc.pid) ?? await isProcessRunning(proc.pid, proc.command);
             const envVars = parseEnvString(proc.env);
 
             const ports = isRunning ? await getProcessPorts(proc.pid) : [];
@@ -54,7 +87,7 @@ export async function showAll(opts?: { json?: boolean; filter?: string }) {
     const resourceMap = await getProcessBatchResources(allPids);
 
     for (const proc of filtered) {
-        const isRunning = await isProcessRunning(proc.pid, proc.command);
+        const isRunning = aliveCache.get(proc.pid) ?? await isProcessRunning(proc.pid, proc.command);
         const runtime = calculateRuntime(proc.timestamp);
         const mem = isRunning ? (resourceMap.get(proc.pid)?.memory || 0) : 0;
 

package/src/commands/run.ts

@@ -1,6 +1,6 @@
 import type { CommandOptions } from "../types";
 import { getProcess, removeProcessByName, retryDatabaseOperation, insertProcess } from "../db";
-import { isProcessRunning, terminateProcess, getHomeDir, getShellCommand, killProcessOnPort, findChildPid, getProcessPorts, waitForPortFree } from "../platform";
+import { isProcessRunning, terminateProcess, getHomeDir, getShellCommand, killProcessOnPort, findChildPid, getProcessPorts, waitForPortFree, psExec } from "../platform";
 import { error, announce } from "../logger";
 import { validateDirectory, parseEnvString } from "../utils";
 import { parseConfigFile } from "../config";
@@ -95,12 +95,25 @@ export async function handleRun(options: CommandOptions) {
 
         // Zombie sweep: kill any remaining bun processes matching this command
         // This catches orphaned children that survived taskkill when the parent shell exited
+        // IMPORTANT: Exclude the current bgrun process and dashboard to avoid self-kill
         const cmdToMatch = existingProcess.command;
         if (cmdToMatch) {
             await run.measure('Zombie sweep', async () => {
                 try {
-                    const result = await $`powershell -Command "Get-Process -Name bun -ErrorAction SilentlyContinue | Where-Object { $_.CommandLine -match '${cmdToMatch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').split(' ')[1] || cmdToMatch}' } | Select-Object -ExpandProperty Id"`.nothrow().text();
-                    const zombiePids = result.split('\n').map((l: string) => parseInt(l.trim())).filter((n: number) => !isNaN(n) && n > 0);
+                    const cmdKeyword = cmdToMatch.split(' ')[1] || cmdToMatch;
+                    // Skip sweep if keyword is too generic (would match unrelated processes)
+                    const GENERIC_KEYWORDS = ['dev', 'run', 'start', 'serve', 'build', 'test'];
+                    if (GENERIC_KEYWORDS.includes(cmdKeyword.toLowerCase())) {
+                        return; // Too dangerous — skip zombie sweep for generic commands
+                    }
+                    const currentPid = process.pid;
+                    const result = await psExec(
+                        `Get-CimInstance Win32_Process -Filter "Name='bun.exe'" | Where-Object { $_.CommandLine -match '${cmdKeyword.replace(/'/g, "''")}' -and $_.ProcessId -ne ${currentPid} } | Select-Object -ExpandProperty ProcessId`,
+                        3000
+                    );
+                    const zombiePids = result.split('\n')
+                        .map((l: string) => parseInt(l.trim()))
+                        .filter((n: number) => !isNaN(n) && n > 0 && n !== currentPid);
                     for (const zPid of zombiePids) {
                         await $`taskkill /F /T /PID ${zPid}`.nothrow().quiet();
                     }
@@ -125,6 +138,11 @@ export async function handleRun(options: CommandOptions) {
     const finalCommand = command || existingProcess!.command;
     const finalDirectory = directory || (existingProcess?.workdir!);
     let finalEnv = env || (existingProcess ? parseEnvString(existingProcess.env) : {});
+    
+    // Default BGR_KEEP_ALIVE=true for new processes unless explicitly disabled
+    if (!('BGR_KEEP_ALIVE' in finalEnv)) {
+        finalEnv.BGR_KEEP_ALIVE = 'true';
+    }
 
     let finalConfigPath: string | undefined | null;
     if (configPath !== undefined) {

package/src/db.ts

@@ -18,10 +18,32 @@ export const ProcessSchema = z.object({
     stdout_path: z.string(),
     stderr_path: z.string(),
     timestamp: z.string().default(() => new Date().toISOString()),
+    group: z.string().default(''),
 });
 
 export type Process = z.infer<typeof ProcessSchema> & { id: number };
 
+export const TemplateSchema = z.object({
+    name: z.string(),
+    command: z.string(),
+    workdir: z.string().default(''),
+    env: z.string().default(''),
+    group: z.string().default(''),
+    created_at: z.string().default(() => new Date().toISOString()),
+});
+
+export type Template = z.infer<typeof TemplateSchema> & { id: number };
+
+export const HistorySchema = z.object({
+    process_name: z.string(),
+    event: z.string(), // 'start', 'stop', 'restart', 'crash', 'guard_on', 'guard_off'
+    pid: z.number().optional(),
+    timestamp: z.string().default(() => new Date().toISOString()),
+    metadata: z.string().default(''), // JSON string for extra info
+});
+
+export type History = z.infer<typeof HistorySchema> & { id: number };
+
 // =============================================================================
 // DATABASE INITIALIZATION
 // =============================================================================
@@ -48,9 +70,13 @@ if (!existsSync(dbPath) && existsSync(legacyDbPath)) {
 
 export const db = new Database(dbPath, {
     process: ProcessSchema,
+    template: TemplateSchema,
+    history: HistorySchema,
 }, {
     indexes: {
         process: ['name', 'timestamp', 'pid'],
+        template: ['name'],
+        history: ['process_name', 'timestamp'],
     },
 });
 
@@ -127,6 +153,95 @@ export function updateProcessEnv(name: string, envJson: string) {
     }
 }
 
+// =============================================================================
+// TEMPLATE FUNCTIONS
+// =============================================================================
+
+export function getAllTemplates() {
+    return db.template.select().all();
+}
+
+export function getTemplate(name: string) {
+    return db.template.select().where({ name }).limit(1).get() || null;
+}
+
+export function saveTemplate(data: {
+    name: string;
+    command: string;
+    workdir?: string;
+    env?: string;
+    group?: string;
+}) {
+    const existing = db.template.select().where({ name: data.name }).limit(1).get();
+    if (existing) {
+        db.template.update(existing.id, {
+            command: data.command,
+            workdir: data.workdir || '',
+            env: data.env || '',
+            group: data.group || '',
+        });
+    } else {
+        db.template.insert({
+            name: data.name,
+            command: data.command,
+            workdir: data.workdir || '',
+            env: data.env || '',
+            group: data.group || '',
+        });
+    }
+}
+
+export function deleteTemplate(name: string) {
+    const tmpl = db.template.select().where({ name }).limit(1).get();
+    if (tmpl) {
+        db.template.delete(tmpl.id);
+    }
+}
+
+// =============================================================================
+// HISTORY FUNCTIONS
+// =============================================================================
+
+export function getProcessHistory(name: string, limit = 50) {
+    return db.history.select()
+        .where({ process_name: name })
+        .orderBy('timestamp', 'desc')
+        .limit(limit)
+        .all();
+}
+
+export function addHistoryEntry(processName: string, event: string, pid?: number, metadata = {}) {
+    return db.history.insert({
+        process_name: processName,
+        event,
+        pid,
+        metadata: JSON.stringify(metadata),
+    });
+}
+
+export function getRecentHistory(limit = 100) {
+    return db.history.select()
+        .orderBy('timestamp', 'desc')
+        .limit(limit)
+        .all();
+}
+
+export function clearOldHistory(daysToKeep = 30) {
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - daysToKeep);
+    const cutoffStr = cutoff.toISOString();
+    
+    const oldEntries = db.history.select()
+        .where('timestamp', '<', cutoffStr)
+        .all();
+    
+    for (const entry of oldEntries) {
+        db.history.delete(entry.id);
+    }
+    
+    return oldEntries.length;
+}
+
 // =============================================================================
 // DEBUG / INFO
 // =============================================================================