npm package: @raphaellcs/process-manager
Description: Simple process manager for Node.js applications
Author: Dream Heart
Latest version: 1.0.0

# @raphaellcs/process-manager

A simple and lightweight process manager for Node.js applications.

## Features

- 🚀 **Start** processes with ease
- 🛑 **Stop** running processes
- 🔄 **Restart** processes
- 📋 **List** all managed processes
- 📝 **Log** management and viewing
- 👻 **Daemon mode** for background processes

## Installation

```bash
# Use with npx (no installation needed)
npx @raphaellcs/process-manager --help

# Or install globally
npm install -g @raphaellcs/process-manager
```

## Usage

### Start a Process

```bash
# Start a Node.js application
npx @raphaellcs/process-manager start "node app.js"

# Start with a custom name
npx @raphaellcs/process-manager start "node server.js" --name web-server

# Start in background (daemon mode)
npx @raphaellcs/process-manager start "npm start" --name api --daemon

# Specify custom log file
npx @raphaellcs/process-manager start "node app.js" --log custom.log
```

### Stop a Process

```bash
# Stop by PID
npx @raphaellcs/process-manager stop 12345

# Stop by name
npx @raphaellcs/process-manager stop web-server
```

### Restart a Process

```bash
# Restart by PID
npx @raphaellcs/process-manager restart 12345

# Restart by name
npx @raphaellcs/process-manager restart web-server
```

### List Processes

```bash
# List all managed processes
npx @raphaellcs/process-manager list
```

### View Logs

```bash
# Show last 20 lines of log
npx @raphaellcs/process-manager logs web-server

# Show last 50 lines
npx @raphaellcs/process-manager logs web-server --lines 50

# Follow log output (like tail -f)
npx @raphaellcs/process-manager logs web-server --follow
```

## Examples

### Example 1: Start a Web Server

```bash
$ npx @raphaellcs/process-manager start "node server.js" --name web-server --daemon
✓ Process started as daemon: web-server
PID: 12345
Log: web-server.log
To stop: process-manager stop 12345
```

### Example 2: List All Processes

```bash
$ npx @raphaellcs/process-manager list

📋 Managed Processes:

  ● Running web-server
    PID: 12345
    Command: node server.js
    Log: web-server.log
    Daemon: Yes

  ● Running api-server
    PID: 12346
    Command: npm start
    Log: api-server.log
    Daemon: Yes
```

### Example 3: Stop a Process

```bash
$ npx @raphaellcs/process-manager stop web-server
✓ Process stopped: 12345
```

### Example 4: Restart a Process

```bash
$ npx @raphaellcs/process-manager restart api-server
✓ Process restarted: api-server
New PID: 12347
```

### Example 5: View Logs

```bash
$ npx @raphaellcs/process-manager logs web-server --lines 10

Server started on port 3000
GET /api/users 200
GET /api/posts 200
GET /api/users 200
POST /api/users 201
...
```

### Example 6: Follow Logs

```bash
$ npx @raphaellcs/process-manager logs web-server --follow

Server started on port 3000
GET /api/users 200
GET /api/posts 200
...
(new log lines will appear in real-time)
```

## Options

### Start Command

- `-n, --name <name>` - Process name (default: process-<timestamp>)
- `-l, --log <file>` - Log file path (default: <name>.log)
- `-d, --daemon` - Run as daemon (background)

### Logs Command

- `-f, --follow` - Follow log output (tail -f)
- `-n, --lines <number>` - Number of lines to show (default: 20)

## Process Management

### Configuration File

Process information is stored in `.pm-config.json`:

```json
{
  "web-server": {
    "pid": 12345,
    "command": "node server.js",
    "logFile": "web-server.log",
    "daemon": true,
    "started": 1707715200000
  }
}
```

### Stopping Processes

Processes are stopped gracefully with `SIGTERM`. If you need to force kill:

```bash
kill -9 <PID>
```

### Auto-cleanup

When a process exits naturally, it's automatically removed from the configuration.

## Use Cases

- 🌐 **Web Servers**: Manage Node.js HTTP servers
- 🤖 **Bots**: Keep chatbots running
- 📊 **Workers**: Run background processing jobs
- 🔔 **Monitors**: Watch files and run tasks
- 🎯 **Dev Tools**: Start dev servers in background
- 📈 **Scrapers**: Run web scrapers in background

## Best Practices

### 1. Use Meaningful Names

```bash
# Good
npx @raphaellcs/process-manager start "npm start" --name api-server

# Not as helpful
npx @raphaellcs/process-manager start "npm start" --name proc-123
```

### 2. Use Daemon Mode for Long-running Processes

```bash
# Run as daemon for background execution
npx @raphaellcs/process-manager start "node bot.js" --name telegram-bot --daemon
```

### 3. Separate Logs for Each Process

```bash
# Use custom log files
npx @raphaellcs/process-manager start "node api.js" --name api --log logs/api.log
npx @raphaellcs/process-manager start "node worker.js" --name worker --log logs/worker.log
```

### 4. Monitor with Logs

```bash
# Start process
npx @raphaellcs/process-manager start "node app.js" --name app --daemon

# Follow logs in another terminal
npx @raphaellcs/process-manager logs app --follow
```

## Comparison with PM2

| Feature | @raphaellcs/process-manager | PM2 |
|---------|---------------------------|------|
| Simplicity | ✅ Very simple | ❌ More complex |
| Process Management | ✅ Start/Stop/Restart | ✅ Full-featured |
| Clustering | ❌ No | ✅ Yes |
| Log Management | ✅ Basic | ✅ Advanced |
| Monitoring | ❌ No | ✅ Yes |
| Zero Config | ✅ Yes | ❌ Requires setup |
| Use Case | Simple dev setups | Production apps |

**Use @raphaellcs/process-manager when:**
- You need simple process management
- You're working on development
- You don't need advanced features

**Use PM2 when:**
- You need production-ready features
- You need clustering
- You need advanced monitoring

## Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

## License

MIT

## Author

Dream Heart 🌙

## Links

- [npm](https://www.npmjs.com/package/@raphaellcs/process-manager)
- [GitHub](https://github.com/RaphaelLcs-financial/process-manager)