@locusai/locus-pm2

Unified PM2 process management for Locus platform packages. Wraps PM2 operations (start, stop, restart, delete, status, logs) into a reusable TypeScript API with intelligent binary discovery, so any platform adapter can manage long-running processes without dealing with PM2 internals.

Installation

npm install @locusai/locus-pm2

Quick Start

import { pm2Start, pm2Status, pm2Stop } from "@locusai/locus-pm2";

const config = {
  processName: "my-service",
  scriptPath: "/absolute/path/to/server.js",
};

// Start (or restart if already running)
pm2Start(config);

// Check status
const status = pm2Status(config);
console.log(status?.status); // "online"

// Stop
pm2Stop(config);

API Reference

pm2Start(config: Pm2Config): string

Starts a process with PM2. If a process with the same name already exists, it restarts it instead.

pm2Start({ processName: "locus-telegram", scriptPath: "/path/to/bot.js" });
// → "Started locus-telegram"  or  "Restarted locus-telegram"

pm2Stop(config: Pm2Config): string

Stops a running PM2 process.

pm2Stop({ processName: "locus-telegram", scriptPath: "" });
// → "Stopped locus-telegram"

pm2Restart(config: Pm2Config): string

Restarts a running PM2 process.

pm2Restart({ processName: "locus-telegram", scriptPath: "" });
// → "Restarted locus-telegram"

pm2Delete(config: Pm2Config): string

Stops and removes a process from PM2 entirely.

pm2Delete({ processName: "locus-telegram", scriptPath: "" });
// → "Deleted locus-telegram"

pm2Status(config: Pm2Config): Pm2Status | null

Returns the current status of a PM2 process, or null if the process is not found.

const status = pm2Status({ processName: "locus-telegram", scriptPath: "" });
// → { name: "locus-telegram", status: "online", pid: 12345, uptime: 3600000, memory: 52428800, restarts: 0 }

pm2Logs(config: Pm2Config, lines?: number): string

Retrieves recent log output for a PM2 process.

pm2Logs(config);       // last 50 lines (default)
pm2Logs(config, 100);  // last 100 lines

Returns "No logs available." if the process has no logs or the command fails.

resolvePackageScript(importMetaUrl: string, binName: string): string

Resolves the absolute path to a package binary. Given an import.meta.url from the calling module, returns <packageRoot>/bin/<binName>.js.

import { resolvePackageScript } from "@locusai/locus-pm2";

// From packages/telegram/src/pm2.ts
const scriptPath = resolvePackageScript(import.meta.url, "bot");
// → /path/to/packages/telegram/bin/bot.js

Configuration

Pm2Config

Configuration object passed to all PM2 operations.

| Property | Type | Required | Description | |----------|------|----------|-------------| | processName | string | Yes | PM2 process name (e.g. "locus-telegram") | | scriptPath | string | Yes | Absolute path to the script to run | | scriptArgs | string[] | No | Extra arguments passed after -- to the script |

Pm2Status

Status object returned by pm2Status().

| Property | Type | Description | |----------|------|-------------| | name | string | Process name | | status | string | Current status ("online", "stopped", "errored", etc.) | | pid | number \| null | Process ID, or null if not running | | uptime | number \| null | Uptime in milliseconds, or null if not running | | memory | number \| null | Memory usage in bytes, or null if not running | | restarts | number | Number of restarts |

Usage in Platform Packages

Platform adapters (Telegram, Discord, etc.) use this package to manage their long-running processes. Here's how a typical adapter integrates:

// packages/telegram/src/pm2.ts
import type { Pm2Config } from "@locusai/locus-pm2";
import {
  pm2Start,
  pm2Stop,
  pm2Status,
  pm2Logs,
  pm2Delete,
  resolvePackageScript,
} from "@locusai/locus-pm2";

function getConfig(): Pm2Config {
  return {
    processName: "locus-telegram",
    scriptPath: resolvePackageScript(import.meta.url, "bot"),
    scriptArgs: ["bot"],
  };
}

// Start the Telegram bot as a background daemon
export function startBot() {
  return pm2Start(getConfig());
}

// Check if the bot is running
export function botStatus() {
  return pm2Status(getConfig());
}

// View recent logs
export function botLogs(lines?: number) {
  return pm2Logs(getConfig(), lines);
}

// Stop the bot
export function stopBot() {
  return pm2Stop(getConfig());
}

// Remove the bot process entirely
export function deleteBot() {
  return pm2Delete(getConfig());
}

The CLI then exposes these as subcommands (e.g., locus pkg telegram start, locus pkg telegram status).

PM2 Binary Discovery

The package automatically finds the PM2 binary using a four-step fallback:

1. Walk up from cwd looking for node_modules/.bin/pm2
2. Walk up from the running script looking for node_modules/.bin/pm2
3. Check system PATH via which pm2
4. Fall back to npx pm2

No manual configuration is needed.

Related Packages

| Package | Description | |---------|-------------| | @locusai/locus-gateway | Channel-agnostic message gateway that platform adapters connect to | | @locusai/locus-telegram | Telegram adapter — primary consumer of this package | | @locusai/sdk | SDK for building community packages |

License

MIT