bm2 1.0.19 → 1.0.22

package/README.md

@@ -1,3 +1,4 @@
+
 # ⚡ BM2
 
 **A blazing-fast, full-featured process manager built entirely on Bun native APIs.**
@@ -47,6 +48,20 @@ The modern PM2 replacement — zero Node.js dependencies, pure Bun performance.
   - [WebSocket API](#websocket-api)
 - [Prometheus and Grafana Integration](#prometheus-and-grafana-integration)
 - [Programmatic API](#programmatic-api)
+  - [Quick Start](#programmatic-quick-start)
+  - [Connection Lifecycle](#connection-lifecycle)
+  - [Process Management](#programmatic-process-management)
+  - [Introspection](#introspection)
+  - [Logs](#logs)
+  - [Monitoring and Metrics](#programmatic-monitoring-and-metrics)
+  - [Persistence](#persistence)
+  - [Dashboard Control](#dashboard-control)
+  - [Module Management](#module-management)
+  - [Daemon Lifecycle](#daemon-lifecycle)
+  - [Low-Level Transport](#low-level-transport)
+  - [Events](#events)
+  - [Error Handling](#error-handling)
+  - [Direct ProcessManager Usage](#direct-processmanager-usage)
 - [Architecture](#architecture)
 - [Comparison with PM2](#comparison-with-pm2)
 - [Recipes and Examples](#recipes-and-examples)
@@ -1258,10 +1273,475 @@ groups:
 
 ## Programmatic API
 
-BM2 can be used as a library in your own Bun applications:
+BM2 exposes two levels of programmatic access. The `BM2` client class communicates with the daemon over its Unix socket, giving you the same capabilities as the CLI from within any Bun application. For in-process usage without a daemon, you can use the `ProcessManager` class directly.
+
+### Programmatic Quick Start
+
+```ts
+import BM2 from "bm2";
+
+const bm2 = new BM2();
+await bm2.connect();
+
+// Start a clustered application
+await bm2.start({
+  script: "./server.ts",
+  name: "api",
+  instances: 4,
+  execMode: "cluster",
+  port: 3000,
+  env: { NODE_ENV: "production" },
+});
+
+// List all processes
+const processes = await bm2.list();
+console.log(processes);
+
+// Stream metrics every 2 seconds
+bm2.on("metrics", (snapshot) => {
+  console.log(`CPU: ${snapshot.system.cpu}%  Memory: ${snapshot.system.memory}%`);
+});
+bm2.startPolling(2000);
+
+// Graceful shutdown
+bm2.stopPolling();
+await bm2.disconnect();
+```
+
+---
+
+### Connection Lifecycle
+
+#### `bm2.connect(): Promise<BM2>`
+
+Connect to the BM2 daemon. If the daemon is not running, it is spawned automatically and the method waits up to 5 seconds for it to become responsive. Returns the `BM2` instance for chaining.
+
+```ts
+const bm2 = new BM2();
+await bm2.connect();
+console.log(`Connected to daemon PID ${bm2.daemonPid}`);
+```
+
+#### `bm2.disconnect(): Promise<void>`
+
+Disconnect from the daemon. This stops any internal polling timers but does not kill the daemon — all managed processes continue running.
+
+```ts
+await bm2.disconnect();
+console.log(bm2.connected); // false
+```
+
+#### `bm2.connected: boolean`
+
+Read-only property indicating whether the client believes the daemon is reachable.
+
+#### `bm2.daemonPid: number | null`
+
+Read-only property containing the PID of the daemon process, or `null` if unknown.
+
+---
+
+### Programmatic Process Management
+
+#### `bm2.start(options: StartOptions): Promise<ProcessState[]>`
+
+Start a new process or process group. The `script` path is automatically resolved to an absolute path. Returns the array of `ProcessState` objects for the started instances.
+
+```ts
+const procs = await bm2.start({
+  script: "./worker.ts",
+  name: "worker",
+  instances: 2,
+  env: { QUEUE: "emails" },
+  maxMemoryRestart: "256M",
+});
+console.log(`Started ${procs.length} instances`);
+```
+
+The `StartOptions` object accepts all the same fields documented in the [Process Options](#process-options) configuration reference.
+
+#### `bm2.startEcosystem(config: EcosystemConfig): Promise<ProcessState[]>`
+
+Start an entire ecosystem configuration. All script paths within the config are resolved to absolute paths before being sent to the daemon.
+
+```ts
+const procs = await bm2.startEcosystem({
+  apps: [
+    { script: "./api.ts", name: "api", instances: 4, port: 3000 },
+    { script: "./worker.ts", name: "worker", instances: 2 },
+  ],
+});
+```
+
+#### `bm2.stop(target?: string | number): Promise<ProcessState[]>`
+
+Stop one or more processes. The `target` can be a process name, numeric ID, namespace, or `"all"`. Defaults to `"all"` when omitted.
+
+```ts
+await bm2.stop("api");       // Stop by name
+await bm2.stop(0);           // Stop by ID
+await bm2.stop();            // Stop all
+```
+
+#### `bm2.restart(target?: string | number): Promise<ProcessState[]>`
+
+Hard restart one or more processes. The process is fully stopped and then re-spawned.
+
+```ts
+await bm2.restart("api");
+await bm2.restart();          // Restart all
+```
+
+#### `bm2.reload(target?: string | number): Promise<ProcessState[]>`
+
+Graceful zero-downtime reload. New instances are started before old ones are stopped, ensuring no dropped requests. Ideal for deploying new code.
+
+```ts
+await bm2.reload("api");
+await bm2.reload();           // Reload all
+```
+
+#### `bm2.delete(target?: string | number): Promise<ProcessState[]>`
+
+Stop and remove one or more processes from BM2's management entirely.
+
+```ts
+await bm2.delete("api");
+await bm2.delete();           // Delete all
+```
+
+#### `bm2.scale(target: string | number, count: number): Promise<ProcessState[]>`
+
+Scale a process group to the specified number of instances. When scaling up, new instances inherit the configuration of existing ones. When scaling down, the highest-numbered instances are removed first.
+
+```ts
+await bm2.scale("api", 8);   // Scale up to 8 instances
+await bm2.scale("api", 2);   // Scale down to 2 instances
+```
+
+#### `bm2.sendSignal(target: string | number, signal: string): Promise<void>`
+
+Send an OS signal to a managed process.
+
+```ts
+await bm2.sendSignal("api", "SIGUSR2");
+await bm2.sendSignal(0, "SIGHUP");
+```
+
+#### `bm2.reset(target?: string | number): Promise<ProcessState[]>`
+
+Reset the restart counter for one or more processes. Defaults to `"all"`.
+
+```ts
+await bm2.reset("api");
+await bm2.reset();            // Reset all
+```
+
+---
+
+### Introspection
+
+#### `bm2.list(): Promise<ProcessState[]>`
+
+List all managed processes with their current state.
+
+```ts
+const processes = await bm2.list();
+for (const proc of processes) {
+  console.log(`${proc.name} [${proc.status}] PID=${proc.pid} CPU=${proc.cpu}%`);
+}
+```
+
+#### `bm2.describe(target: string | number): Promise<ProcessState[]>`
+
+Get detailed information about a specific process or process group.
+
+```ts
+const details = await bm2.describe("api");
+console.log(details[0]);
+```
+
+---
 
+### Logs
+
+#### `bm2.logs(target?: string | number, lines?: number): Promise<Array<{ name: string; id: number; out: string; err: string }>>`
+
+Retrieve recent log lines for one or all processes. Defaults to `"all"` with `20` lines.
+
+```ts
+const logs = await bm2.logs("api", 100);
+for (const entry of logs) {
+  console.log(`[${entry.name}] stdout:\n${entry.out}`);
+  if (entry.err) console.error(`[${entry.name}] stderr:\n${entry.err}`);
+}
+```
+
+#### `bm2.flush(target?: string | number): Promise<void>`
+
+Truncate log files for one or all processes.
+
+```ts
+await bm2.flush("api");      // Flush logs for "api"
+await bm2.flush();            // Flush all logs
+```
+
+---
+
+### Programmatic Monitoring and Metrics
+
+#### `bm2.metrics(): Promise<MetricSnapshot>`
+
+Take a single metrics snapshot containing process-level and system-level telemetry.
+
+```ts
+const snapshot = await bm2.metrics();
+console.log(`System CPU: ${snapshot.system.cpu}%`);
+for (const proc of snapshot.processes) {
+  console.log(`  ${proc.name}: ${proc.memory} bytes, ${proc.cpu}% CPU`);
+}
+```
+
+#### `bm2.metricsHistory(seconds?: number): Promise<MetricSnapshot[]>`
+
+Retrieve historical metric snapshots from the daemon's in-memory ring buffer. The `seconds` parameter controls the look-back window and defaults to `300` (5 minutes). The daemon retains up to 1 hour of per-second snapshots.
+
+```ts
+const history = await bm2.metricsHistory(600);   // Last 10 minutes
+console.log(`Got ${history.length} snapshots`);
+```
+
+#### `bm2.prometheus(): Promise<string>`
+
+Get the current metrics formatted as a Prometheus exposition text string.
+
+```ts
+const text = await bm2.prometheus();
+console.log(text);
+// # HELP bm2_process_cpu CPU usage percentage
+// # TYPE bm2_process_cpu gauge
+// bm2_process_cpu{name="api-0",id="0"} 1.2
+// ...
+```
+
+#### `bm2.startPolling(intervalMs?: number): void`
+
+Start polling the daemon for metrics at a fixed interval and emitting `"metrics"` events. Defaults to `2000` ms. Calling this again replaces the existing polling timer.
+
+```ts
+bm2.on("metrics", (snapshot) => {
+  console.log(`${snapshot.processes.length} processes running`);
+});
+bm2.startPolling(1000);       // Poll every second
 ```
-// app.ts
+
+#### `bm2.stopPolling(): void`
+
+Stop the metrics polling loop.
+
+```ts
+bm2.stopPolling();
+```
+
+---
+
+### Persistence
+
+#### `bm2.save(): Promise<void>`
+
+Persist the current process list to `~/.bm2/dump.json` so it can be restored later.
+
+```ts
+await bm2.save();
+```
+
+#### `bm2.resurrect(): Promise<ProcessState[]>`
+
+Restore previously saved processes from `~/.bm2/dump.json`.
+
+```ts
+const restored = await bm2.resurrect();
+console.log(`Restored ${restored.length} processes`);
+```
+
+---
+
+### Dashboard Control
+
+#### `bm2.dashboard(port?: number, metricsPort?: number): Promise<{ port: number; metricsPort: number }>`
+
+Start the web dashboard. Defaults to port `9615` for the dashboard and `9616` for the Prometheus metrics endpoint.
+
+```ts
+const { port, metricsPort } = await bm2.dashboard(8080, 8081);
+console.log(`Dashboard: http://localhost:${port}`);
+console.log(`Metrics:   http://localhost:${metricsPort}/metrics`);
+```
+
+#### `bm2.dashboardStop(): Promise<void>`
+
+Stop the web dashboard.
+
+```ts
+await bm2.dashboardStop();
+```
+
+---
+
+### Module Management
+
+#### `bm2.moduleInstall(nameOrPath: string): Promise<{ path: string }>`
+
+Install a BM2 module from a git URL, local path, or npm package name.
+
+```ts
+const result = await bm2.moduleInstall("bm2-prometheus-pushgateway");
+console.log(`Installed to ${result.path}`);
+```
+
+#### `bm2.moduleUninstall(name: string): Promise<void>`
+
+Uninstall a BM2 module.
+
+```ts
+await bm2.moduleUninstall("bm2-prometheus-pushgateway");
+```
+
+#### `bm2.moduleList(): Promise<Array<{ name: string; version: string }>>`
+
+List all installed modules.
+
+```ts
+const modules = await bm2.moduleList();
+for (const mod of modules) {
+  console.log(`${mod.name}@${mod.version}`);
+}
+```
+
+---
+
+### Daemon Lifecycle
+
+#### `bm2.ping(): Promise<{ pid: number; uptime: number }>`
+
+Ping the daemon and return its PID and uptime in milliseconds.
+
+```ts
+const info = await bm2.ping();
+console.log(`Daemon PID ${info.pid}, up for ${Math.round(info.uptime / 1000)}s`);
+```
+
+#### `bm2.kill(): Promise<void>`
+
+Kill the daemon and all managed processes. Cleans up the socket and PID files. The daemon connection will not respond after this call, which is expected.
+
+```ts
+await bm2.kill();
+console.log(bm2.connected); // false
+```
+
+#### `bm2.daemonReload(): Promise<string>`
+
+Reload the daemon server itself without killing managed processes.
+
+```ts
+const result = await bm2.daemonReload();
+console.log(result);
+```
+
+---
+
+### Low-Level Transport
+
+#### `bm2.send(message: DaemonMessage): Promise<DaemonResponse>`
+
+Send an arbitrary message to the daemon over the Unix socket and return the raw response. This is useful for custom command types, future extensions, or direct daemon interaction.
+
+```ts
+const response = await bm2.send({ type: "ping" });
+console.log(response);
+// { success: true, data: { pid: 12345, uptime: 60000 }, id: "abc123" }
+```
+
+Messages are JSON objects with a `type` field for routing and an optional `id` field for request-response correlation (auto-generated if omitted). The `data` field carries command-specific payload.
+
+---
+
+### Events
+
+The `BM2` class extends `EventEmitter` and emits the following typed events:
+
+| Event | Payload | Description |
+|---|---|---|
+| `daemon:connected` | — | Daemon connection established |
+| `daemon:disconnected` | — | Client disconnected from daemon |
+| `daemon:launched` | `pid: number` | Daemon was spawned by this client |
+| `daemon:killed` | — | Daemon was killed via `kill()` |
+| `error` | `error: Error` | Transport or polling error |
+| `process:start` | `processes: ProcessState[]` | Process(es) started |
+| `process:stop` | `processes: ProcessState[]` | Process(es) stopped |
+| `process:restart` | `processes: ProcessState[]` | Process(es) restarted |
+| `process:reload` | `processes: ProcessState[]` | Process(es) reloaded |
+| `process:delete` | `processes: ProcessState[]` | Process(es) deleted |
+| `process:scale` | `processes: ProcessState[]` | Process group scaled |
+| `metrics` | `snapshot: MetricSnapshot` | Metrics snapshot received |
+| `log:data` | `logs: Array<{ name, id, out, err }>` | Log data retrieved |
+
+```ts
+const bm2 = new BM2();
+
+bm2.on("daemon:connected", () => console.log("Connected!"));
+bm2.on("daemon:disconnected", () => console.log("Disconnected"));
+bm2.on("process:start", (procs) => {
+  console.log("Started:", procs.map((p) => p.name).join(", "));
+});
+bm2.on("process:stop", (procs) => {
+  console.log("Stopped:", procs.map((p) => p.name).join(", "));
+});
+bm2.on("error", (err) => console.error("BM2 error:", err.message));
+bm2.on("metrics", (snapshot) => {
+  console.log(`${snapshot.processes.length} processes, system CPU ${snapshot.system.cpu}%`);
+});
+
+await bm2.connect();
+```
+
+---
+
+### Error Handling
+
+All methods that communicate with the daemon throw a `BM2Error` when the daemon returns a failure response. The error includes the command that failed and the full daemon response for inspection.
+
+```ts
+import { BM2Error } from "bm2";
+
+try {
+  await bm2.describe("nonexistent");
+} catch (err) {
+  if (err instanceof BM2Error) {
+    console.error(`Command "${err.command}" failed: ${err.message}`);
+    console.error("Full response:", err.response);
+  }
+}
+```
+
+Transport-level errors (daemon unreachable, socket closed) throw standard `Error` instances.
+
+#### `BM2Error` Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `message` | `string` | Human-readable error message |
+| `command` | `string` | The daemon command type that failed |
+| `response` | `DaemonResponse` | The full response object from the daemon |
+
+---
+
+### Direct ProcessManager Usage
+
+For in-process usage without a running daemon, you can use the `ProcessManager` class directly. This is useful for embedding BM2 into your own application or for custom tooling.
+
+```ts
 import { ProcessManager } from "bm2/process-manager";
 import { Dashboard } from "bm2/dashboard";
 
@@ -1308,6 +1788,8 @@ await pm.resurrect();
 await pm.stopAll();
 ```
 
+The `ProcessManager` provides the same process management capabilities but runs in-process rather than communicating with a daemon. Use the `BM2` client class for the standard daemon-based workflow, and `ProcessManager` when you need direct, embedded control.
+
 ---
 
 ## Architecture
@@ -1476,6 +1958,64 @@ bun install
 bm2 reload all
 ```
 
+### Programmatic Monitoring Service
+
+```ts
+import BM2 from "bm2";
+
+const bm2 = new BM2();
+await bm2.connect();
+
+// Alert when any process uses more than 512 MB
+bm2.on("metrics", (snapshot) => {
+  for (const proc of snapshot.processes) {
+    if (proc.memory > 512 * 1024 * 1024) {
+      console.warn(`⚠️  ${proc.name} using ${Math.round(proc.memory / 1024 / 1024)} MB`);
+    }
+  }
+});
+
+bm2.startPolling(5000);
+
+// Keep running
+process.on("SIGINT", async () => {
+  bm2.stopPolling();
+  await bm2.disconnect();
+  process.exit(0);
+});
+```
+
+### Programmatic Deploy Pipeline
+
+```ts
+import BM2 from "bm2";
+
+const bm2 = new BM2();
+await bm2.connect();
+
+// Deploy new code, then reload
+console.log("Reloading all processes...");
+const reloaded = await bm2.reload("all");
+console.log(`Reloaded ${reloaded.length} processes`);
+
+// Verify everything is healthy
+const processes = await bm2.list();
+const allOnline = processes.every((p) => p.status === "online");
+
+if (allOnline) {
+  console.log("✅ All processes online");
+  await bm2.save();
+} else {
+  console.error("❌ Some processes failed to come online");
+  const failed = processes.filter((p) => p.status !== "online");
+  for (const p of failed) {
+    console.error(`  ${p.name}: ${p.status}`);
+  }
+}
+
+await bm2.disconnect();
+```
+
 ---
 
 ## Troubleshooting

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "bm2",
-  "version": "1.0.19",
+  "version": "1.0.22",
   "description": "A blazing-fast, full-featured process manager built entirely on Bun native APIs. The modern PM2 replacement — zero Node.js dependencies, pure Bun performance.",
-  "main": "src/index.ts",
-  "module": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "src/api.ts",
+  "module": "src/api.ts",
+  "types": "src/api.ts",
+  "exports": {
+    ".": "./src/api.ts",
+    "./cli": "./src/index.ts"
+  },
   "bin": {
     "bm2": "./src/index.ts"
   },
@@ -42,7 +46,7 @@
     "email": "hello@maxxpainn.com",
     "url": "https://maxxpainn.com"
   },
-  "license": "MIT",
+  "license": "GPL-3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bun-bm2/bm2.git"

package/src/api.ts

@@ -0,0 +1,598 @@
+/**
+ * BM2 — Bun Process Manager
+ * Programmatic API
+ *
+ * Usage:
+ *   import BM2 from "bm2";
+ *   const bm2 = new BM2();
+ *   await bm2.connect();
+ *   const list = await bm2.list();
+ *   await bm2.start({ script: "./app.ts", name: "my-app" });
+ *   await bm2.disconnect();
+ *
+ * License: GPL-3.0-only
+ * Author: Zak <zak@maxxpainn.com>
+ */
+
+import { EventEmitter } from "events";
+import { existsSync, readFileSync, unlinkSync } from "fs";
+import { join } from "path";
+import { resolve } from "path";
+import {
+  DAEMON_SOCKET,
+  DAEMON_PID_FILE,
+  BM2_HOME,
+  DASHBOARD_PORT,
+  METRICS_PORT,
+  DAEMON_OUT_LOG_FILE,
+  DAEMON_ERR_LOG_FILE,
+} from "./constants";
+import { ensureDirs, generateId } from "./utils";
+import type {
+  DaemonMessage,
+  DaemonResponse,
+  StartOptions,
+  EcosystemConfig,
+  ProcessState,
+  MetricSnapshot,
+  ProcessStatus,
+} from "./types";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Bus event types emitted by BM2
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface BM2Events {
+  /** Daemon successfully connected */
+  "daemon:connected": [];
+  /** Daemon connection lost */
+  "daemon:disconnected": [];
+  /** Daemon launched by this client */
+  "daemon:launched": [pid: number];
+  /** Daemon killed */
+  "daemon:killed": [];
+  /** Error on the transport layer */
+  "error": [error: Error];
+  /** Process started */
+  "process:start": [processes: ProcessState[]];
+  /** Process stopped */
+  "process:stop": [processes: ProcessState[]];
+  /** Process restarted */
+  "process:restart": [processes: ProcessState[]];
+  /** Process reloaded */
+  "process:reload": [processes: ProcessState[]];
+  /** Process deleted */
+  "process:delete": [processes: ProcessState[]];
+  /** Process scaled */
+  "process:scale": [processes: ProcessState[]];
+  /** Metrics snapshot received */
+  "metrics": [snapshot: MetricSnapshot];
+  /** Log data received */
+  "log:data": [logs: Array<{ name: string; id: number; out: string; err: string }>];
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Main API class
+// ────────────────────────────────────────────────────────────────────────────
+
+export class BM2 extends EventEmitter<BM2Events> {
+  private _connected: boolean = false;
+  private _daemonPid: number | null = null;
+  private _pollTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** Whether the client believes the daemon is reachable. */
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  /** PID of the daemon process (if known). */
+  get daemonPid(): number | null {
+    return this._daemonPid;
+  }
+
+  // ──────────────────────────── lifecycle ────────────────────────────────
+
+  /**
+   * Connect to the BM2 daemon.
+   * If the daemon is not running it will be spawned automatically
+   * (same behaviour as the CLI).
+   */
+  async connect(): Promise<this> {
+    ensureDirs();
+
+    if (!(await this.isDaemonAlive())) {
+      await this.launchDaemon();
+    }
+
+    // Verify connectivity
+    const pong = await this.send({ type: "ping" });
+    if (!pong.success) {
+      throw new Error("Failed to connect to BM2 daemon");
+    }
+
+    this._connected = true;
+    this._daemonPid = pong.data?.pid ?? null;
+    this.emit("daemon:connected");
+
+    return this;
+  }
+
+  /**
+   * Disconnect from the daemon. Stops any internal polling but does **not**
+   * kill the daemon — processes keep running.
+   */
+  async disconnect(): Promise<void> {
+    this.stopPolling();
+    this._connected = false;
+    this.emit("daemon:disconnected");
+  }
+
+  // ─────────────────────── process management ───────────────────────────
+
+  /**
+   * Start a new process (or ecosystem).
+   *
+   * ```ts
+   * await bm2.start({ script: "./server.ts", name: "api", instances: 4 });
+   * ```
+   */
+  async start(options: StartOptions): Promise<ProcessState[]> {
+    if (options.script) {
+      options.script = resolve(options.script);
+    }
+    const res = await this.sendOrThrow({ type: "start", data: options });
+    this.emit("process:start", res.data);
+    return res.data;
+  }
+
+  /**
+   * Start an ecosystem configuration object.
+   *
+   * ```ts
+   * await bm2.startEcosystem({ apps: [{ script: "./a.ts" }, { script: "./b.ts" }] });
+   * ```
+   */
+  async startEcosystem(config: EcosystemConfig): Promise<ProcessState[]> {
+    // Resolve scripts to absolute paths
+    for (const app of config.apps) {
+      if (app.script) app.script = resolve(app.script);
+    }
+    const res = await this.sendOrThrow({ type: "ecosystem", data: config });
+    this.emit("process:start", res.data);
+    return res.data;
+  }
+
+  /**
+   * Stop one or more processes.
+   * @param target Process id, name, namespace, or `"all"`.
+   */
+  async stop(target: string | number = "all"): Promise<ProcessState[]> {
+    const type = target === "all" ? "stopAll" : "stop";
+    const data = target === "all" ? undefined : { target: String(target) };
+    const res = await this.sendOrThrow({ type, data });
+    this.emit("process:stop", res.data);
+    return res.data;
+  }
+
+  /**
+   * Restart one or more processes (hard restart).
+   */
+  async restart(target: string | number = "all"): Promise<ProcessState[]> {
+    const type = target === "all" ? "restartAll" : "restart";
+    const data = target === "all" ? undefined : { target: String(target) };
+    const res = await this.sendOrThrow({ type, data });
+    this.emit("process:restart", res.data);
+    return res.data;
+  }
+
+  /**
+   * Graceful zero-downtime reload.
+   */
+  async reload(target: string | number = "all"): Promise<ProcessState[]> {
+    const type = target === "all" ? "reloadAll" : "reload";
+    const data = target === "all" ? undefined : { target: String(target) };
+    const res = await this.sendOrThrow({ type, data });
+    this.emit("process:reload", res.data);
+    return res.data;
+  }
+
+  /**
+   * Stop and remove one or more processes from BM2's list.
+   */
+  async delete(target: string | number = "all"): Promise<ProcessState[]> {
+    const type = target === "all" ? "deleteAll" : "delete";
+    const data = target === "all" ? undefined : { target: String(target) };
+    const res = await this.sendOrThrow({ type, data });
+    this.emit("process:delete", res.data);
+    return res.data;
+  }
+
+  /**
+   * Scale a process group to `count` instances.
+   */
+  async scale(target: string | number, count: number): Promise<ProcessState[]> {
+    const res = await this.sendOrThrow({
+      type: "scale",
+      data: { target: String(target), count },
+    });
+    this.emit("process:scale", res.data);
+    return res.data;
+  }
+
+  /**
+   * Send an OS signal to a process.
+   */
+  async sendSignal(target: string | number, signal: string): Promise<void> {
+    await this.sendOrThrow({
+      type: "signal",
+      data: { target: String(target), signal },
+    });
+  }
+
+  /**
+   * Reset restart counters for one or more processes.
+   */
+  async reset(target: string | number = "all"): Promise<ProcessState[]> {
+    const res = await this.sendOrThrow({
+      type: "reset",
+      data: { target: String(target) },
+    });
+    return res.data;
+  }
+
+  // ───────────────────────── introspection ──────────────────────────────
+
+  /**
+   * List all managed processes.
+   */
+  async list(): Promise<ProcessState[]> {
+    const res = await this.sendOrThrow({ type: "list" });
+    return res.data;
+  }
+
+  /**
+   * Get detailed description(s) of a process.
+   */
+  async describe(target: string | number): Promise<ProcessState[]> {
+    const res = await this.sendOrThrow({
+      type: "describe",
+      data: { target: String(target) },
+    });
+    return res.data;
+  }
+
+  // ────────────────────────── logs ───────────────────────────────────────
+
+  /**
+   * Retrieve recent log lines.
+   */
+  async logs(
+    target: string | number = "all",
+    lines: number = 20
+  ): Promise<Array<{ name: string; id: number; out: string; err: string }>> {
+    const res = await this.sendOrThrow({
+      type: "logs",
+      data: { target: String(target), lines },
+    });
+    this.emit("log:data", res.data);
+    return res.data;
+  }
+
+  /**
+   * Flush (truncate) log files for one or all processes.
+   */
+  async flush(target?: string | number): Promise<void> {
+    await this.sendOrThrow({
+      type: "flush",
+      data: target !== undefined ? { target: String(target) } : undefined,
+    });
+  }
+
+  // ──────────────────────── monitoring ───────────────────────────────────
+
+  /**
+   * Take a single metrics snapshot.
+   */
+  async metrics(): Promise<MetricSnapshot> {
+    const res = await this.sendOrThrow({ type: "metrics" });
+    this.emit("metrics", res.data);
+    return res.data;
+  }
+
+  /**
+   * Get historical metric snapshots.
+   * @param seconds Look-back window (default 300 = 5 min).
+   */
+  async metricsHistory(seconds: number = 300): Promise<MetricSnapshot[]> {
+    const res = await this.sendOrThrow({
+      type: "metricsHistory",
+      data: { seconds },
+    });
+    return res.data;
+  }
+
+  /**
+   * Get Prometheus-formatted metrics string.
+   */
+  async prometheus(): Promise<string> {
+    const res = await this.sendOrThrow({ type: "prometheus" });
+    return res.data;
+  }
+
+  /**
+   * Start polling metrics at a fixed interval and emitting `"metrics"` events.
+   *
+   * ```ts
+   * bm2.on("metrics", (snapshot) => console.log(snapshot));
+   * bm2.startPolling(2000);
+   * ```
+   */
+  startPolling(intervalMs: number = 2000): void {
+    this.stopPolling();
+    this._pollTimer = setInterval(async () => {
+      try {
+        await this.metrics();
+      } catch (err) {
+        this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      }
+    }, intervalMs);
+  }
+
+  /** Stop the metrics polling loop started by `startPolling()`. */
+  stopPolling(): void {
+    if (this._pollTimer) {
+      clearInterval(this._pollTimer);
+      this._pollTimer = null;
+    }
+  }
+
+  // ────────────────────── persistence ───────────────────────────────────
+
+  /**
+   * Persist the current process list to disk so it can be restored later.
+   */
+  async save(): Promise<void> {
+    await this.sendOrThrow({ type: "save" });
+  }
+
+  /**
+   * Restore previously saved processes.
+   */
+  async resurrect(): Promise<ProcessState[]> {
+    const res = await this.sendOrThrow({ type: "resurrect" });
+    return res.data;
+  }
+
+  // ────────────────────── dashboard ─────────────────────────────────────
+
+  /**
+   * Start the web dashboard.
+   */
+  async dashboard(
+    port: number = DASHBOARD_PORT,
+    metricsPort: number = METRICS_PORT
+  ): Promise<{ port: number; metricsPort: number }> {
+    const res = await this.sendOrThrow({
+      type: "dashboard",
+      data: { port, metricsPort },
+    });
+    return res.data;
+  }
+
+  /**
+   * Stop the web dashboard.
+   */
+  async dashboardStop(): Promise<void> {
+    await this.sendOrThrow({ type: "dashboardStop" });
+  }
+
+  // ────────────────────── modules ───────────────────────────────────────
+
+  /**
+   * Install a BM2 module.
+   */
+  async moduleInstall(nameOrPath: string): Promise<{ path: string }> {
+    const res = await this.sendOrThrow({
+      type: "moduleInstall",
+      data: { module: nameOrPath },
+    });
+    return res.data;
+  }
+
+  /**
+   * Uninstall a BM2 module.
+   */
+  async moduleUninstall(name: string): Promise<void> {
+    await this.sendOrThrow({
+      type: "moduleUninstall",
+      data: { module: name },
+    });
+  }
+
+  /**
+   * List installed modules.
+   */
+  async moduleList(): Promise<Array<{ name: string; version: string }>> {
+    const res = await this.sendOrThrow({ type: "moduleList" });
+    return res.data;
+  }
+
+  // ────────────────────── daemon lifecycle ──────────────────────────────
+
+  /**
+   * Ping the daemon. Returns daemon PID and uptime.
+   */
+  async ping(): Promise<{ pid: number; uptime: number }> {
+    const res = await this.sendOrThrow({ type: "ping" });
+    return res.data;
+  }
+
+  /**
+   * Kill the daemon and all managed processes.
+   */
+  async kill(): Promise<void> {
+    try {
+      await this.send({ type: "kill" });
+    } catch {
+      // Expected — daemon exits before responding
+    }
+
+    // Clean up leftover files
+    try { if (existsSync(DAEMON_SOCKET)) unlinkSync(DAEMON_SOCKET); } catch {}
+    try { if (existsSync(DAEMON_PID_FILE)) unlinkSync(DAEMON_PID_FILE); } catch {}
+
+    this._connected = false;
+    this._daemonPid = null;
+    this.stopPolling();
+    this.emit("daemon:killed");
+  }
+
+  /**
+   * Reload the daemon server itself.
+   */
+  async daemonReload(): Promise<string> {
+    const res = await this.sendOrThrow({ type: "daemonReload" });
+    return res.data;
+  }
+
+  // ────────────────────── internal transport ────────────────────────────
+
+  /**
+   * Low-level: send an arbitrary message to the daemon and return the
+   * raw response. Useful for custom or future command types.
+   */
+  async send(message: DaemonMessage): Promise<DaemonResponse> {
+    
+    if (!message.id) {
+      message.id = generateId();
+    }
+
+    const body = JSON.stringify(message);
+
+    // Bun supports fetching over Unix sockets with the `unix` option
+    const response = await fetch(`http://localhost/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      unix: DAEMON_SOCKET,
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Daemon HTTP ${response.status}: ${text}`);
+    }
+
+    return (await response.json()) as DaemonResponse;
+  }
+
+  // ────────────────────── private helpers ───────────────────────────────
+
+  /** Send and throw a friendly error if `success` is false. */
+  private async sendOrThrow(message: DaemonMessage): Promise<DaemonResponse> {
+    const res = await this.send(message);
+    if (!res.success) {
+      throw new BM2Error(
+        res.error || `Command "${message.type}" failed`,
+        message.type,
+        res
+      );
+    }
+    return res;
+  }
+
+  /** Check whether the daemon is running and reachable. */
+  private async isDaemonAlive(): Promise<boolean> {
+    // Quick PID-file check first
+    if (existsSync(DAEMON_PID_FILE)) {
+      try {
+        const pid = parseInt(readFileSync(DAEMON_PID_FILE, "utf-8").trim());
+        process.kill(pid, 0); // throws if process doesn't exist
+      } catch {
+        // Stale PID file
+        return false;
+      }
+    } else {
+      return false;
+    }
+
+    // Verify the socket is responsive
+    if (!existsSync(DAEMON_SOCKET)) return false;
+
+    try {
+      const res = await this.send({ type: "ping" });
+      return res.success;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Launch the daemon as a detached background process.
+   * Waits up to 5 seconds for it to become responsive.
+   */
+  private async launchDaemon(): Promise<void> {
+    const daemonScript = join(import.meta.dir, "daemon.ts");
+    const bunPath = Bun.which("bun") || "bun";
+
+    // Open log files for daemon stdout/stderr
+    const outLog = Bun.file(DAEMON_OUT_LOG_FILE);
+    const errLog = Bun.file(DAEMON_ERR_LOG_FILE);
+
+    const proc = Bun.spawn([bunPath, "run", daemonScript], {
+      stdio: ["ignore", "ignore", "ignore"],
+      env: { ...process.env as Record<string, string> },
+    });
+
+    // Detach — we don't want to keep a handle
+    proc.unref();
+
+    // Poll until daemon is responsive (up to 5 s)
+    const deadline = Date.now() + 5000;
+    let alive = false;
+
+    while (Date.now() < deadline) {
+      await Bun.sleep(200);
+      try {
+        if (existsSync(DAEMON_SOCKET)) {
+          const res = await this.send({ type: "ping" });
+          if (res.success) {
+            alive = true;
+            this._daemonPid = res.data?.pid ?? proc.pid;
+            break;
+          }
+        }
+      } catch {
+        // Not ready yet — keep waiting
+      }
+    }
+
+    if (!alive) {
+      throw new Error(
+        "Timed out waiting for BM2 daemon to start. " +
+        `Check ${DAEMON_ERR_LOG_FILE} for details.`
+      );
+    }
+
+    this.emit("daemon:launched", this._daemonPid!);
+  }
+}
+
+// ────────────────────────── error class ─────────────────────────────────
+
+export class BM2Error extends Error {
+  /** The daemon command type that failed. */
+  public readonly command: string;
+  /** The full daemon response. */
+  public readonly response: DaemonResponse;
+
+  constructor(message: string, command: string, response: DaemonResponse) {
+    super(message);
+    this.name = "BM2Error";
+    this.command = command;
+    this.response = response;
+  }
+}
+
+// ────────────────────────── default export ──────────────────────────────
+
+export default BM2;

package/src/index.ts

@@ -39,7 +39,6 @@ import type {
   EcosystemConfig,
   ProcessState,
 } from "./types";
-import Table from "cli-table3";
 import { statusColor } from "./colors";
 import { liveWatchProcess, printProcessTable } from "./process-table";
 

package/src/process-table.ts

@@ -84,6 +84,7 @@ function minimalBorders() {
 // ---------- Table Printer ----------
 
 export function printProcessTable(processes: ProcessState[]) {
+  
   console.log("");
   console.log(color("BM2 — Bun Process Manager", "bold"));
   console.log(color("─────────────────────────────────────────────", "dim"));
@@ -133,7 +134,7 @@ export function printProcessTable(processes: ProcessState[]) {
 }
 
 
-export function liveWatchProcess(processes: ProcessState[], interval = 1000) {
+export function liveWatchProcess(processes: ProcessState[], interval = 5_000) {
   let sortBy: "cpu" | "mem" | "uptime" | "default" = "default";
 
   // Clear console helper

package/src/startup-manager.ts

@@ -34,39 +34,41 @@
    }
  
    private generateSystemd(bunPath: string, bm2Path: string, daemonPath: string): string {
+     
      const unit = `[Unit]
- Description=BM2 Process Manager
- Documentation=https://github.com/bm2
- After=network.target
- 
- [Service]
- Type=forking
- User=${process.env.USER || "root"}
- LimitNOFILE=infinity
- LimitNPROC=infinity
- LimitCORE=infinity
- Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:${join(bunPath, "..")}
- Environment=BM2_HOME=${join(process.env.HOME || "/root", ".bm2")}
- PIDFile=${join(process.env.HOME || "/root", ".bm2", "daemon.pid")}
- Restart=on-failure
- 
- ExecStart=${bunPath} run ${daemonPath}
- ExecReload=${bunPath} run ${bm2Path} reload all
- ExecStop=${bunPath} run ${bm2Path} kill
- 
- [Install]
- WantedBy=multi-user.target`;
- 
+Description=BM2 Process Manager
+Documentation=https://github.com/bm2
+After=network.target
+
+[Service]
+Type=simple
+User=${process.env.USER || "root"}
+LimitNOFILE=infinity
+LimitNPROC=infinity
+LimitCORE=infinity
+Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:${join(bunPath, "..")}
+Environment=BM2_HOME=${join(process.env.HOME || "/root", ".bm2")}
+Restart=on-failure
+
+ExecStart=${bunPath} run ${daemonPath}
+ExecStartPost=${bunPath} run ${bm2Path} resurrect
+ExecReload=${bunPath} run ${bm2Path} reload all
+ExecStop=${bunPath} run ${bm2Path} kill
+
+[Install]
+WantedBy=multi-user.target
+`;
+   
      const servicePath = "/etc/systemd/system/bm2.service";
-     return `# BM2 Systemd Service
- # Save to: ${servicePath}
- # Then run:
- #   sudo systemctl daemon-reload
- #   sudo systemctl enable bm2
- #   sudo systemctl start bm2
- 
- ${unit}`;
-   }
+return `# BM2 Systemd Service
+# Save to: ${servicePath}
+# Then run:
+#   sudo systemctl daemon-reload
+#   sudo systemctl enable bm2
+#   sudo systemctl start bm2
+
+${unit}`;
+}
  
    private generateLaunchd(bunPath: string, bm2Path: string, daemonPath: string): string {
      const plist = `<?xml version="1.0" encoding="UTF-8"?>
@@ -115,11 +117,11 @@
      if (os === "linux") {
        const servicePath = "/etc/systemd/system/bm2.service";
        // Extract just the unit content
-       const unitContent = content.split("\n\n").slice(1).join("\n\n");
-       await Bun.write(servicePath, unitContent);
+       //const unitContent = content.split("\n\n").slice(1).join("\n\n");
+       await Bun.write(servicePath, content);
  
-       Bun.spawn(["sudo", "systemctl", "daemon-reload"], { stdout: "inherit" });
-       Bun.spawn(["sudo", "systemctl", "enable", "bm2"], { stdout: "inherit" });
+       Bun.spawn(["sudo", "systemctl", "daemon-reload"], { stdout: "inherit" }).exited;
+       Bun.spawn(["sudo", "systemctl", "enable", "bm2"], { stdout: "inherit" }).exited;
  
        return `Service installed at ${servicePath}\nRun: sudo systemctl start bm2`;
      } else if (os === "darwin") {

package/src/hello.js

@@ -1,7 +0,0 @@
-
-let counter = 0;
-
-setInterval(() => {
-  console.log(`Hello World ${counter++}`)
-
-})