Files

Juergen Kunz e73f4acd63 BREAKING CHANGE(daemon): Refactor daemon and service management: remove IPC auto-spawn, add TspmServiceManager, tighten IPC/client/CLI behavior and tests

2025-08-28 15:52:29 +00:00

9.8 KiB

Raw Permalink Blame History

@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

# 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

# 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:

# 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).

tspm stop my-server

`tspm restart <id>`

Stop and restart a process with the same configuration.

tspm restart my-server

`tspm delete <id>`

Stop and remove a process from TSPM management.

tspm delete old-server

Monitoring & Information

`tspm list`

Display all managed processes in a beautiful table.

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.

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)

tspm logs my-server --lines 100

Batch Operations

`tspm start-all`

Start all saved processes at once.

tspm start-all

`tspm stop-all`

Stop all running processes.

tspm stop-all

`tspm restart-all`

Restart all running processes.

tspm restart-all

Daemon Management

`tspm daemon start`

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

tspm daemon start

`tspm daemon stop`

Stop the TSPM daemon and all managed processes.

tspm daemon stop

`tspm daemon status`

Check daemon health and statistics.

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:

ProcessWrapper - Low-level process management with stream handling
ProcessMonitor - Adds monitoring, memory limits, and auto-restart logic
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:

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

# 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:

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 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.

9.8 KiB Raw Permalink Blame History