# @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 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 ```bash # 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 ```bash # 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 [options]` Add a new process configuration without starting it. This is the recommended way to register processes. **Options:** - `--name ` - Custom name for the process (required) - `--memory ` - Memory limit (e.g., "512MB", "2GB", default: 512MB) - `--cwd ` - Working directory (default: current directory) - `--watch` - Enable file watching for auto-restart - `--watch-paths ` - Comma-separated paths to watch - `--autorestart` - Auto-restart on crash (default: true) - `-i, --interactive` - Enter interactive edit mode after adding **Examples:** ```bash # 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 ` Start a previously added process by its ID or name. ```bash tspm start name:my-server tspm start id:1 # Or a bare numeric id: tspm start 1 ``` #### `tspm stop ` Gracefully stop a running process (SIGTERM → SIGKILL after timeout). ```bash tspm stop name:my-server ``` #### `tspm restart ` Stop and restart a process with the same configuration. ```bash tspm restart name:my-server ``` #### `tspm delete ` / `tspm remove ` Stop and remove a process from TSPM management. Also deletes persisted logs. ```bash tspm delete name:old-server tspm remove name:old-server # Alias for delete (daemon handles delete) ``` #### `tspm edit ` Interactively edit a process configuration. ```bash 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. ```bash 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 ` Get detailed information about a specific process. ```bash 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 [options]` View and stream process logs (stdout, stderr, and system messages). **Options:** - `--lines ` Number of lines to show (default: 50) - `--since ` 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`) ```bash # 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. ```bash tspm start-all # ✓ Started 3 processes: # - my-app # - worker # - api-server ``` #### `tspm stop-all` Stop all running processes. ```bash tspm stop-all # ✓ Stopped 3 processes ``` #### `tspm restart-all` Restart all running processes. ```bash tspm restart-all # ✓ Restarted 3 processes ``` #### `tspm reset` **⚠️ Dangerous:** Stop all processes and clear all configurations. ```bash 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). ```bash tspm daemon start # ✓ TSPM daemon started successfully ``` #### `tspm daemon stop` Stop the daemon and all managed processes. ```bash tspm daemon stop # ✓ TSPM daemon stopped successfully ``` #### `tspm daemon restart` Restart the daemon (preserves running processes). ```bash tspm daemon restart # ✓ TSPM daemon restarted successfully ``` #### `tspm daemon status` Check daemon health and statistics. ```bash 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: ```bash 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. ```bash 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. ```bash 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: ```typescript 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: 1. Send SIGTERM for graceful shutdown 2. Wait for process to clean up (5 seconds) 3. Send SIGKILL if still running 4. 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 ```bash # 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: ```bash # 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 ` ## 🎯 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 ` to discover IDs by name or ID fragments. ### `tspm search ` Search processes by name or ID substring and print matching IDs (and names when available): ```bash tspm search api # Matches for "api": # - id:3 name:api-server ``` - **"Memory limit exceeded"**: Increase limit with `tspm edit ` ## 🤝 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: ```bash 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](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.