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 is TSPM?

TSPM (TypeScript Process Manager) is your production-ready process manager that handles the hard parts of running Node.js applications. It's like PM2, but built from the ground up for the modern TypeScript ecosystem with better memory management, intelligent logging, and a cleaner architecture.

✨ Key Features

🧠 Smart Memory Management - Tracks memory including child processes, enforces limits, and auto-restarts when exceeded
💾 Persistent Log Storage - Keeps 10MB of logs in memory, persists to disk on restart/stop/error
🔄 Intelligent Auto-Restart - Automatically restarts crashed processes with configurable policies
👀 File Watching - Auto-restart on file changes for seamless development
🌳 Process Group Tracking - Monitors parent and all child processes as a unit
🏗️ Daemon Architecture - Survives terminal sessions with Unix socket IPC
📊 Beautiful CLI - Clean, informative output with real-time status updates
📝 Structured Logging - Captures stdout/stderr with timestamps and metadata
⚡ Zero Config - Works out of the box, customize when needed
🔌 System Service - Run as systemd service for production deployments

📦 Installation

# Install globally (recommended)
npm install -g @git.zone/tspm

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

# Or as a dev dependency
npm install --save-dev @git.zone/tspm

🚀 Quick Start

# Add a process (creates config without starting)
tspm add "node server.js" --name my-server --memory 1GB

# Start the process (by name or id)
tspm start name:my-server
# or
tspm start id:1

# Or add and start in one go
tspm add "node app.js" --name my-app
tspm start name:my-app

# List all processes
tspm list

# View logs
tspm logs name:my-app

# Stop a process
tspm stop name:my-app

📋 Commands

Process Management

`tspm add <command> [options]`

Add a new process configuration without starting it. This is the recommended way to register processes.

Options:

--name <name> - Custom name for the process (required)
--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
--autorestart - Auto-restart on crash (default: true)
-i, --interactive - Enter interactive edit mode after adding

Examples:

# Add a simple Node.js app
tspm add "node server.js" --name api-server

# Add with 2GB memory limit
tspm add "node app.js" --name production-api --memory 2GB

# Add TypeScript app with watching
tspm add "tsx watch src/index.ts" --name dev-server --watch --watch-paths "src,config"

# Add without auto-restart
tspm add "node worker.js" --name one-time-job --autorestart false

# Add and immediately edit interactively
tspm add "node server.js" --name api -i

`tspm start <id|id:N|name:LABEL>`

Start a previously added process by its ID or name.

tspm start name:my-server
tspm start id:1  # Or a bare numeric id: tspm start 1

`tspm stop <id|id:N|name:LABEL>`

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

tspm stop name:my-server

`tspm restart <id|id:N|name:LABEL>`

Stop and restart a process with the same configuration.

tspm restart name:my-server

`tspm delete <id|id:N|name:LABEL>` / `tspm remove <id|id:N|name:LABEL>`

Stop and remove a process from TSPM management. Also deletes persisted logs.

tspm delete name:old-server
tspm remove name:old-server  # Alias for delete (daemon handles delete)

`tspm edit <id>`

Interactively edit a process configuration.

tspm edit my-server
# Opens interactive prompts to modify name, command, memory, etc.

Monitoring & Information

`tspm list`

Display all managed processes in a beautiful table.

tspm list

# Output:
┌─────────┬─────────────┬───────────┬───────────┬──────────┬──────────┐
│ ID      │ Name        │ Status    │ PID       │ Memory   │ Restarts │
├─────────┼─────────────┼───────────┼───────────┼──────────┼──────────┤
│ 1       │ my-app      │ online    │ 45123     │ 245.3 MB │ 0        │
│ 2       │ worker      │ online    │ 45456     │ 128.7 MB │ 2        │
│ 3       │ api-server  │ stopped   │ -         │ 0 B      │ 5        │
└─────────┴─────────────┴───────────┴───────────┴──────────┴──────────┘

`tspm describe <id|id:N|name:LABEL>`

Get detailed information about a specific process.

tspm describe name:my-server

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

Configuration:
────────────────────────────────────────
Command:     node server.js
Directory:   /home/user/project
Memory Limit: 2 GB
Auto-restart: true
Watch:       disabled

`tspm logs <id|id:N|name:LABEL> [options]`

View and stream process logs (stdout, stderr, and system messages).

Options:

--lines <n> Number of lines to show (default: 50)
--since <dur> Only show logs since duration (e.g., 10m, 2h, 1d; units: ms|s|m|h|d)
--stderr-only Only show stderr logs
--stdout-only Only show stdout logs
--ndjson Output each log as JSON line (timestamp in ms)
--follow Stream logs in real-time (like tail -f)

# View last 50 lines
tspm logs name:my-server

# View last 100 lines
tspm logs name:my-server --lines 100

# Only stderr for the last 10 minutes (as NDJSON)
tspm logs name:my-server --since 10m --stderr-only --ndjson

# Follow logs in real time (prints recent lines, then streams backlog incrementally and live logs)
tspm logs name:my-server --follow

# Follow only stdout since 2h ago
tspm logs name:my-server --follow --since 2h --stdout-only

Notes:

Follow mode prints a small recent backlog, then streams older entries incrementally (to avoid large payloads) and continues with live logs.
Log sequences are restart-aware; TSPM detects run changes and keeps output consistent across restarts.

Batch Operations

`tspm start-all`

Start all saved processes at once.

tspm start-all
# ✓ Started 3 processes:
#   - my-app
#   - worker
#   - api-server

`tspm stop-all`

Stop all running processes.

tspm stop-all
# ✓ Stopped 3 processes

`tspm restart-all`

Restart all running processes.

tspm restart-all
# ✓ Restarted 3 processes

`tspm reset`

⚠️ Dangerous: Stop all processes and clear all configurations.

tspm reset
# Are you sure? (y/N)
# Stopped 3 processes.
# Cleared all configurations.

Daemon Management

The TSPM daemon runs in the background and manages all your processes. It starts automatically when needed.

`tspm daemon start`

Manually start the TSPM daemon (usually automatic).

tspm daemon start
# ✓ TSPM daemon started successfully

`tspm daemon stop`

Stop the daemon and all managed processes.

tspm daemon stop
# ✓ TSPM daemon stopped successfully

`tspm daemon restart`

Restart the daemon (preserves running processes).

tspm daemon restart
# ✓ TSPM daemon restarted successfully

`tspm daemon status`

Check daemon health and statistics.

tspm daemon status

# Output:
TSPM Daemon Status:
────────────────────────────────────────
Status:      running
PID:         12345
Uptime:      86400s
Processes:   5
Socket:      /home/user/.tspm/tspm.sock

Version check and service refresh

Check CLI vs daemon versions and refresh the systemd service if they differ:

tspm -v
# tspm CLI: 5.x.y
# Daemon: running v5.x.z (pid 1234)
# Version mismatch detected → optionally refresh the systemd service (equivalent to `tspm disable && tspm enable`).

This is helpful after upgrades where the system service still references an older CLI path.

System Service Management

Run TSPM as a system service (systemd) for production deployments.

`tspm enable`

Enable TSPM as a system service that starts on boot.

sudo tspm enable
# ✓ TSPM daemon enabled and started as system service
# The daemon will now start automatically on system boot

`tspm disable`

Disable the TSPM system service.

sudo tspm disable
# ✓ TSPM daemon service disabled
# The daemon will no longer start on system boot

🏗️ Architecture

TSPM uses a robust three-tier architecture:

┌─────────────────────────────────────────┐
│            CLI Interface                │
│         (tspm commands)                 │
└────────────────┬────────────────────────┘
                 │ Unix Socket IPC
┌────────────────▼────────────────────────┐
│          TSPM Daemon                    │
│     (Background Service)                │
│  ┌──────────────────────────────────┐  │
│  │     ProcessManager               │  │
│  │  - Configuration persistence     │  │
│  │  - Process lifecycle             │  │
│  │  - Desired state management      │  │
│  └────────────┬─────────────────────┘  │
│               │                         │
│  ┌────────────▼─────────────────────┐  │
│  │     ProcessMonitor                │  │
│  │  - Memory tracking & limits      │  │
│  │  - Auto-restart logic            │  │
│  │  - Log persistence (10MB)        │  │
│  │  - File watching                 │  │
│  └────────────┬─────────────────────┘  │
│               │                         │
│  ┌────────────▼─────────────────────┐  │
│  │     ProcessWrapper                │  │
│  │  - Process spawning              │  │
│  │  - Stream handling               │  │
│  │  - Signal management             │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘

Key Components

CLI - Lightweight client that communicates with daemon via IPC
Daemon - Persistent background service managing all processes
ProcessManager - High-level orchestration and configuration
ProcessMonitor - Adds monitoring, limits, and auto-restart
ProcessWrapper - Low-level process lifecycle and streams

🎮 Programmatic API

Use TSPM as a library in your Node.js applications:

import { TspmIpcClient } from '@git.zone/tspm/client';

const client = new TspmIpcClient();
await client.connect();

// Add and start a process
const { id } = await client.request('add', {
  command: 'node worker.js',
  name: 'background-worker',
  projectDir: process.cwd(),
  memoryLimit: 512 * 1024 * 1024, // 512MB in bytes
  autorestart: true,
  watch: false,
});

await client.request('start', { id });

// Get process info
const { processInfo } = await client.request('describe', { id });
console.log(`Worker status: ${processInfo.status}`);
console.log(`Memory usage: ${processInfo.memory} bytes`);

// Get logs
const { logs } = await client.request('logs', { id, limit: 100 });
logs.forEach(log => {
  console.log(`[${log.timestamp}] ${log.message}`);
});

// Clean up
await client.request('stop', { id });
await client.disconnect();

🔧 Advanced Features

Memory Management

TSPM tracks total memory usage including all child processes:

Uses ps-tree to discover child processes
Calculates combined memory usage
Gracefully restarts when limit exceeded
Prevents memory leaks in production

Log Persistence

Intelligent log management system:

Keeps 10MB of logs in memory per process
Automatically flushes to disk on stop/restart/error
Loads previous logs on process restart
Cleans up persisted logs after loading
Prevents disk space issues

Process Groups

Full process tree management:

Tracks parent and all child processes
Ensures complete cleanup on stop
Accurate memory tracking across process trees
No orphaned processes

Graceful Shutdown

Multi-stage shutdown process:

Send SIGTERM for graceful shutdown
Wait for process to clean up (5 seconds)
Send SIGKILL if still running
Clean up all child processes

File Watching

Development-friendly auto-restart:

Watch specific directories or files
Ignore node_modules by default
Debounced restart on changes
Configurable watch paths

📊 Performance

TSPM is designed for production efficiency:

CPU Usage: < 0.5% overhead per managed process
Memory: ~30-50MB for daemon, ~5-10MB per managed process
Startup Time: < 100ms to spawn new process
IPC Latency: < 1ms for command execution
Log Performance: Efficient ring buffer with automatic trimming

🛠️ Development

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

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the project
pnpm build

# Run in development
pnpm start

Project Structure

tspm/
├── ts/
│   ├── cli/          # CLI commands and interface
│   ├── client/       # IPC client for daemon communication
│   ├── daemon/       # Daemon server and process management
│   └── shared/       # Shared types and protocols
├── test/            # Test files
└── dist_ts/         # Compiled JavaScript

🐛 Debugging

Enable verbose logging for troubleshooting:

# Enable debug mode
export TSPM_DEBUG=true
tspm list

# Check daemon logs
tail -f /tmp/daemon-stderr.log

# Force daemon restart
tspm daemon restart

Common issues:

"Daemon not running": Run tspm daemon start or tspm enable
"Permission denied": Check socket permissions in ~/.tspm/
"Process won't start": Check logs with tspm logs <id|id:N|name:LABEL>

🎯 Targeting Processes (IDs and Names)

Most process commands accept the following target formats:

Numeric ID: tspm start 1
Explicit ID: tspm start id:1
Explicit name: tspm start name:api-server

Notes:

Names must be used with the name: prefix.
If multiple processes share the same name, the CLI will report the ambiguous matches. Use id:N to disambiguate.
Use tspm search <query> to discover IDs by name or ID fragments.

`tspm search <query>`

Search processes by name or ID substring and print matching IDs (and names when available):

tspm search api
# Matches for "api":
# - id:3    name:api-server

"Memory limit exceeded": Increase limit with tspm edit <id>

🤝 Why Choose TSPM?

TSPM vs PM2

Feature	TSPM	PM2
TypeScript Native	✅ Built in TS	❌ JavaScript
Memory Tracking	✅ Including children	⚠️ Main process only
Log Management	✅ Smart 10MB buffer	⚠️ Can grow unlimited
Architecture	✅ Clean 3-tier	❌ Monolithic
Dependencies	✅ Minimal	❌ Heavy
ESM Support	✅ Native	⚠️ Partial
Config Format	✅ Simple JSON	❌ Complex ecosystem

Perfect For

Restart Backoff and Failure Handling

TSPM automatically restarts crashed processes with an incremental backoff:

Debounce delay grows linearly from 1s up to 10s for consecutive retries.
After the 10th retry, the process is marked as failed (status: "errored") and auto-restarts stop.
The retry counter resets if no retry happens for 1 hour since the last attempt.

You can manually restart a failed process at any time:

tspm restart id:1

🚀 Production Node.js apps - Reliable process management
🔧 Microservices - Manage multiple services easily
👨‍💻 Development - File watching and auto-restart
🏭 Worker processes - Queue workers, cron jobs
📊 Resource-constrained environments - Memory limits prevent OOM

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.

readme.md

@git.zone/tspm 🚀