tspm/readme.md

# @git.zone/tspm 🚀

**TypeScript Process Manager** - A robust, no-fuss process manager designed specifically for TypeScript and Node.js applications. Built for developers who need reliable process management without the complexity.

## 🎯 What TSPM Does

TSPM is your production-ready process manager that handles the hard parts of running Node.js applications:

- **Automatic Memory Management** - Set memory limits and let TSPM handle the rest
- **Smart Auto-Restart** - Crashed processes come back automatically (when you want them to)
- **File Watching** - Auto-restart on file changes during development
- **Process Groups** - Track parent and child processes together
- **Daemon Architecture** - Survives terminal sessions with a persistent background daemon
- **Beautiful CLI** - Clean, informative terminal output with real-time status
- **Structured Logging** - Capture and manage stdout/stderr with intelligent buffering
- **Zero Config** - Works out of the box, customize when you need to

## 📦 Installation

```bash
# Install globally
npm install -g @git.zone/tspm

# Or with pnpm (recommended)
pnpm add -g @git.zone/tspm

# Or use in your project
npm install --save-dev @git.zone/tspm
```

## 🚀 Quick Start

```bash
# Start the daemon (happens automatically on first use)
tspm daemon start

# Start a process
tspm start server.js --name my-server

# Start with memory limit
tspm start app.js --memory 512MB --name my-app

# Start with file watching (great for development)
tspm start dev.js --watch --name dev-server

# List all processes
tspm list

# Check process details
tspm describe my-server

# View logs
tspm logs my-server --lines 100

# Stop a process
tspm stop my-server

# Restart a process
tspm restart my-server
```

## 📋 Command Reference

### Process Management

#### `tspm start <script> [options]`

Start a new process with automatic monitoring and management.

**Options:**

- `--name <name>` - Custom name for the process (default: script name)
- `--memory <size>` - Memory limit (e.g., "512MB", "2GB", default: 512MB)
- `--cwd <path>` - Working directory (default: current directory)
- `--watch` - Enable file watching for auto-restart
- `--watch-paths <paths>` - Comma-separated paths to watch (with --watch)
- `--autorestart` - Auto-restart on crash (default: true)

**Examples:**

```bash
# Simple start
tspm start server.js

# Production setup with 2GB memory
tspm start app.js --name production-api --memory 2GB

# Development with watching
tspm start dev-server.js --watch --watch-paths "src,config" --name dev

# Custom working directory
tspm start ../other-project/index.js --cwd ../other-project --name other
```

#### `tspm stop <id>`

Gracefully stop a running process (SIGTERM → SIGKILL after timeout).

```bash
tspm stop my-server
```

#### `tspm restart <id>`

Stop and restart a process with the same configuration.

```bash
tspm restart my-server
```

#### `tspm delete <id>`

Stop and remove a process from TSPM management.

```bash
tspm delete old-server
```

### Monitoring & Information

#### `tspm list`

Display all managed processes in a beautiful table.

```bash
tspm list

# Output:
┌─────────┬─────────────┬───────────┬───────────┬──────────┐
│ ID      │ Name        │ Status    │ Memory    │ Restarts │
├─────────┼─────────────┼───────────┼───────────┼──────────┤
│ my-app  │ my-app      │ online    │ 245.3 MB  │ 0        │
│ worker  │ worker      │ online    │ 128.7 MB  │ 2        │
└─────────┴─────────────┴───────────┴───────────┴──────────┘
```

#### `tspm describe <id>`

Get detailed information about a specific process.

```bash
tspm describe my-server

# Output:
Process Details: my-server
────────────────────────────────────────
Status:      online
PID:         45123
Memory:      245.3 MB
CPU:         2.3%
Uptime:      3600s
Restarts:    0

Configuration:
Command:     server.js
Directory:   /home/user/project
Memory Limit: 2 GB
Auto-restart: true
Watch:       enabled
Watch Paths: src, config
```

#### `tspm logs <id> [options]`

View process logs (stdout and stderr).

**Options:**

- `--lines <n>` - Number of lines to display (default: 50)

```bash
tspm logs my-server --lines 100
```

### Batch Operations

#### `tspm start-all`

Start all saved processes at once.

```bash
tspm start-all
```

#### `tspm stop-all`

Stop all running processes.

```bash
tspm stop-all
```

#### `tspm restart-all`

Restart all running processes.

```bash
tspm restart-all
```

### Daemon Management

#### `tspm daemon start`

Start the TSPM daemon (happens automatically on first command).

```bash
tspm daemon start
```

#### `tspm daemon stop`

Stop the TSPM daemon and all managed processes.

```bash
tspm daemon stop
```

#### `tspm daemon status`

Check daemon health and statistics.

```bash
tspm daemon status

# Output:
TSPM Daemon Status:
────────────────────────────────────────
Status:      running
PID:         12345
Uptime:      86400s
Processes:   5
Memory:      45.2 MB
CPU:         0.1%
```

## 🏗️ Architecture

TSPM uses a three-tier architecture for maximum reliability:

1. **ProcessWrapper** - Low-level process management with stream handling
2. **ProcessMonitor** - Adds monitoring, memory limits, and auto-restart logic
3. **Tspm Core** - High-level orchestration with configuration persistence

The daemon architecture ensures your processes keep running even after you close your terminal. All process communication happens through a robust IPC (Inter-Process Communication) system.

## 🎮 Programmatic Usage

TSPM can also be used as a library in your Node.js applications:

```typescript
import { Tspm } from '@git.zone/tspm';

const manager = new Tspm();

// Start a process
const processId = await manager.start({
  id: 'worker',
  name: 'Background Worker',
  command: 'node worker.js',
  projectDir: process.cwd(),
  memoryLimitBytes: 512 * 1024 * 1024, // 512MB
  autorestart: true,
  watch: false,
});

// Monitor process
const info = await manager.getProcessInfo(processId);
console.log(`Process ${info.id} is ${info.status}`);

// Stop process
await manager.stop(processId);
```

## 🔧 Advanced Features

### Memory Limit Enforcement

TSPM tracks memory usage including all child processes spawned by your application. When a process exceeds its memory limit, it's gracefully restarted.

### Process Group Tracking

Using `ps-tree`, TSPM monitors not just your main process but all child processes it spawns, ensuring complete cleanup on stop/restart.

### Intelligent Logging

Logs are buffered and managed efficiently, preventing memory issues from excessive output while ensuring you don't lose important information.

### Graceful Shutdown

Processes receive SIGTERM first, allowing them to clean up. After a timeout, SIGKILL ensures termination.

### Configuration Persistence

Process configurations are saved, allowing you to restart all processes after a system reboot with a single command.

## 🛠️ Development

```bash
# Clone the repository
git clone https://code.foss.global/git.zone/tspm.git

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the project
pnpm build

# Start development
pnpm start
```

## 🐛 Debugging

Enable debug mode for verbose logging:

```bash
export TSPM_DEBUG=true
tspm list
```

## 📊 Performance

TSPM is designed to be lightweight and efficient:

- Minimal CPU overhead (typically < 0.5%)
- Small memory footprint (~30-50MB for the daemon)
- Fast process startup and shutdown
- Efficient log buffering and rotation

## 🤝 Why TSPM?

Unlike general-purpose process managers, TSPM is built specifically for the TypeScript/Node.js ecosystem:

- **TypeScript First** - Written in TypeScript, for TypeScript projects
- **ESM Native** - Full support for ES modules
- **Developer Friendly** - Beautiful CLI output and helpful error messages
- **Production Ready** - Battle-tested memory management and error handling
- **No Configuration Required** - Sensible defaults that just work
- **Modern Architecture** - Async/await throughout, no callback hell

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.