# @git.zone/tspm no fuzz process manager. # readme.md for @git.zone/tspm **TypeScript Process Manager** — A robust, no-fuss process manager built for the modern TypeScript and Node.js ecosystem. Production-ready process management without the bloat. ## Issue Reporting and Security For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly. ## 🎯 What is TSPM? TSPM is your production-ready process manager that handles the hard parts of running Node.js applications. Think PM2, but built from scratch for the TypeScript-first ecosystem with better memory management, intelligent logging, a clean daemon architecture, and native ESM support. ### ✨ Key Features - 🧠 **Smart Memory Management** — Tracks memory across entire process trees (parent + children), enforces limits, and auto-restarts on OOM - 💾 **Persistent Log Storage** — 10MB in-memory ring buffer per process, auto-persists to disk on stop/restart/crash - 🔄 **Intelligent Auto-Restart** — Crashed processes restart with incremental backoff (1s → 10s), auto-stop after 10 consecutive failures - 👀 **File Watching** — Auto-restart on file changes for seamless development workflows - 🌳 **Process Tree Tracking** — Monitors parent and all child processes as a unit — no orphans, ever - 🏗️ **Daemon Architecture** — Persistent background service that survives terminal sessions via Unix socket IPC - 📊 **Beautiful CLI** — Clean, informative output with table views, real-time log streaming, and search - ⚡ **Zero Config** — Works out of the box; customize only when you need to - 🔌 **Systemd Integration** — Run as a system service for production deployments with `tspm enable` - 🔍 **Crash Log Reports** — Detailed crash reports with metadata, memory snapshots, and log history ## 📦 Installation ```bash # Global install (recommended) pnpm add -g @git.zone/tspm # Or with npm npm install -g @git.zone/tspm # Or as a project dependency pnpm add --save-dev @git.zone/tspm ``` ## 🚀 Quick Start ```bash # Start the daemon tspm daemon start # Add a process tspm add "node server.js" --name my-server --memory 1GB # Start it tspm start name:my-server # See what's running tspm list # View logs tspm logs name:my-server # Stop it tspm stop name:my-server ``` ## 📋 CLI Reference ### Targeting Processes Most commands accept flexible process targeting: | Format | Example | Description | |--------|---------|-------------| | Numeric ID | `tspm start 1` | Direct ID reference | | `id:N` | `tspm start id:1` | Explicit ID prefix | | `name:LABEL` | `tspm start name:api` | Target by name | Use `tspm search ` to find processes by name or ID substring. ### Process Management #### `tspm add [options]` Register a new process configuration (without starting it). | Option | Description | Default | |--------|-------------|---------| | `--name ` | Process name | command string | | `--memory ` | Memory limit (e.g. `512MB`, `2GB`) | `512MB` | | `--cwd ` | Working directory | current directory | | `--watch` | Enable file watching | `false` | | `--watch-paths ` | Comma-separated watch paths | — | | `--autorestart` | Auto-restart on crash | `true` | | `-i, --interactive` | Enter interactive edit after adding | — | ```bash # Simple Node.js app tspm add "node server.js" --name api-server # TypeScript with 2GB memory limit tspm add "tsx src/index.ts" --name production-api --memory 2GB # Dev mode with file watching tspm add "tsx watch src/index.ts" --name dev-server --watch --watch-paths "src,config" # One-shot worker (no auto-restart) tspm add "node worker.js" --name batch-job --autorestart false # Add + interactive edit tspm add "node server.js" --name api -i ``` #### `tspm start ` Start a registered process. ```bash tspm start name:my-server tspm start id:1 tspm start 1 # bare numeric id also works ``` #### `tspm stop ` Gracefully stop a process (SIGTERM → 5s grace → SIGKILL). ```bash tspm stop name:my-server ``` #### `tspm restart ` Stop and restart a process, preserving its configuration. ```bash tspm restart name:my-server ``` #### `tspm delete ` Stop, remove from management, and delete persisted logs. ```bash tspm delete name:old-server ``` #### `tspm edit ` Interactively modify a process configuration (name, command, memory, etc.). ```bash tspm edit name:my-server ``` #### `tspm search ` Search processes by name or ID substring. ```bash tspm search api # Matches for "api": # id:3 name:api-server ``` ### Monitoring #### `tspm list` Display all managed processes in a table. ``` ┌─────┬─────────────┬──────────┬───────┬──────────┬──────────┐ │ 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 ` Detailed information about a specific process. ```bash tspm describe name:my-server # 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. | Option | Description | Default | |--------|-------------|---------| | `--lines ` | Number of lines | `50` | | `--since ` | Time filter (`10m`, `2h`, `1d`) | — | | `--stderr-only` | Only stderr | — | | `--stdout-only` | Only stdout | — | | `--ndjson` | Output as newline-delimited JSON | — | | `--follow` | Real-time streaming (like `tail -f`) | — | ```bash # View last 50 lines tspm logs name:my-server # Last 100 lines of stderr only tspm logs name:my-server --lines 100 --stderr-only # Stream logs in real time tspm logs name:my-server --follow # NDJSON output since 10 minutes ago tspm logs name:my-server --since 10m --ndjson ``` ### Batch Operations ```bash tspm start-all # Start all saved processes tspm stop-all # Stop all running processes tspm restart-all # Restart all running processes tspm reset # ⚠️ Stop all + clear all configs (prompts for confirmation) ``` ### Daemon Management The daemon is a persistent background service that manages all processes. It starts automatically when needed. ```bash tspm daemon start # Start the daemon tspm daemon stop # Stop daemon + all managed processes tspm daemon restart # Restart daemon (preserves processes) tspm daemon status # Check daemon health + stats ``` ### System Service (systemd) ```bash sudo tspm enable # Install + enable as systemd service (auto-start on boot) sudo tspm disable # Remove systemd service ``` ### Version Check ```bash tspm -v # tspm CLI: 5.x.y # Daemon: running v5.x.z (pid 1234) # Version mismatch detected → optionally refresh the systemd service ``` ## 🏗️ Architecture TSPM uses a clean 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 │ │ │ └──────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────┐ │ │ │ CrashLogManager │ │ │ │ - Crash report generation │ │ │ │ - Log rotation (max 100) │ │ │ └──────────────────────────────────┘ │ └─────────────────────────────────────────┘ ``` ### Key Components | Component | Role | |-----------|------| | **CLI** | Lightweight client that sends commands to daemon via IPC | | **Daemon** | Persistent background service managing all processes | | **ProcessManager** | High-level orchestration, config persistence, state management | | **ProcessMonitor** | Memory limits, auto-restart with backoff, log persistence, file watching | | **ProcessWrapper** | Low-level process lifecycle, stream handling, signal management | | **CrashLogManager** | Detailed crash reports with metadata and log history | ## 🎮 Programmatic API TSPM exposes a typed IPC client for programmatic use: ```typescript import { TspmIpcClient } from '@git.zone/tspm/client'; const client = new TspmIpcClient(); await client.connect(); // Add a process configuration const { id } = await client.request('add', { config: { command: 'node worker.js', name: 'background-worker', projectDir: process.cwd(), memoryLimitBytes: 512 * 1024 * 1024, autorestart: true, }, }); // Start it await client.request('startById', { id }); // Get process info const { processInfo } = await client.request('describe', { id }); console.log(`Status: ${processInfo.status}, Memory: ${processInfo.memory} bytes`); // Get logs const { logs } = await client.request('getLogs', { id, limit: 100 }); logs.forEach(log => console.log(`[${log.timestamp}] [${log.type}] ${log.message}`)); // Stop and remove await client.request('stop', { id }); await client.request('delete', { id }); await client.disconnect(); ``` ### Module Exports | Export Path | Purpose | |-------------|---------| | `@git.zone/tspm` | Main entry point (re-exports client + daemon) | | `@git.zone/tspm/client` | IPC client (`TspmIpcClient`, `TspmServiceManager`) | | `@git.zone/tspm/daemon` | Daemon entry point (`startDaemon`) | | `@git.zone/tspm/protocol` | IPC type definitions | ## 🔧 Advanced Features ### Restart Backoff & Failure Handling TSPM handles crashed processes with intelligent backoff: - **Incremental delay**: Grows linearly from 1s up to 10s for consecutive restarts - **Failure threshold**: After 10 consecutive failures, the process is marked `errored` and auto-restart stops - **Auto-reset**: The retry counter resets if no failure occurs for 1 hour - **Manual recovery**: `tspm restart id:1` always works, even on errored processes ### Memory Management Full process tree memory tracking: - Discovers all child processes via `ps-tree` - Calculates combined memory usage across the entire tree - Gracefully restarts when limit is exceeded (SIGTERM → SIGKILL) - Prevents memory leaks from taking down production systems ### Log Persistence Smart in-memory log management: - 10MB ring buffer per process with automatic trimming - Flushes to disk on stop, restart, or crash - Reloads persisted logs when process restarts - Crash logs stored separately with full metadata (exit code, signal, memory, timestamps) ### Graceful Shutdown Multi-stage shutdown for reliability: 1. Send **SIGTERM** for graceful shutdown 2. Wait **5 seconds** for process cleanup 3. Send **SIGKILL** if still alive 4. Clean up **all child processes** in the tree ### File Watching Development-friendly auto-restart: - Watch specific directories or files - `node_modules` ignored by default - Debounced restart on file changes - Configurable via `--watch-paths` ## 🐛 Debugging ```bash # Check daemon status tspm daemon status # View process logs tspm logs name:my-app --lines 200 # Check daemon stderr tail -f /tmp/daemon-stderr.log # Force daemon restart tspm daemon restart ``` **Common issues:** | Problem | Solution | |---------|----------| | "Daemon not running" | `tspm daemon start` or `sudo tspm enable` | | "Permission denied" | Check socket permissions in `~/.tspm/` | | Process won't start | Check logs with `tspm logs ` | | Memory limit exceeded | Increase with `tspm edit ` | ## 🤝 Why TSPM? | Feature | TSPM | PM2 | |---------|------|-----| | TypeScript Native | ✅ Built in TypeScript | ❌ JavaScript | | Memory Tracking | ✅ Full process tree | ⚠️ Main process only | | Log Management | ✅ Smart 10MB buffer | ⚠️ Can grow unbounded | | Architecture | ✅ Clean 3-tier daemon | ❌ Monolithic | | Dependencies | ✅ Minimal | ❌ Heavy | | ESM Support | ✅ Native | ⚠️ Partial | | Crash Reports | ✅ Detailed with metadata | ❌ Basic | ### Perfect For - 🚀 **Production Node.js apps** — Reliable process management with memory guards - 🔧 **Microservices** — Manage multiple services from a single tool - 👨‍💻 **Development** — File watching and instant auto-restart - 🏭 **Workers & Jobs** — Queue workers, cron jobs, background tasks - 📊 **Resource-constrained environments** — Memory limits prevent OOM kills ## License and Legal Information This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./license) file. **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 or third parties, 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 or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar. ### Company Information Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany For any legal inquiries or 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. # changelog.md for @git.zone/tspm ## 2026-03-24 - 5.10.4 - fix(crash-logging) migrate filesystem persistence to smartfs and stabilize crash log tests - replace smartfile usage with smartfs in crash log and log persistence modules - update crash log tests to use tap assertions and current CLI command output - move project config from npmextra.json to .smartconfig.json and refresh build dependencies ## 2026-03-24 - 5.10.3 - fix(config) replace npmextra with smartconfig for daemon key-value storage and release settings - swap the configuration storage dependency from @push.rocks/npmextra to @push.rocks/smartconfig - update daemon config accessors to use the smartconfig KeyValueStore implementation - add @git.zone/cli release registry and access configuration to npmextra.json ## 2025-09-03 - 5.10.2 - fix(processmonitor) Bump smartdaemon and stop aggressive pidusage cache clearing in ProcessMonitor - Update dependency @push.rocks/smartdaemon from ^2.0.9 to ^2.1.0 in package.json. - Remove per-PID pidusage.clear calls in ts/daemon/processmonitor.ts (getProcessGroupStats) to avoid potential errors or unexpected behavior from manually clearing pidusage cache. ## 2025-09-03 - 5.10.1 - fix(processmonitor) Skip null pidusage entries when aggregating process-group memory/CPU to avoid errors - Add defensive check for null/undefined entries returned by pidusage before accessing memory/cpu fields - Log a debug message when an individual process stat is null (process may have exited) - Improve robustness of ProcessMonitor.getProcessGroupStats to prevent runtime exceptions during aggregation ## 2025-09-01 - 5.10.0 - feat(daemon) Add crash log manager with rotation and integrate crash logging; improve IPC & process listener cleanup - Introduce CrashLogManager to create formatted crash reports, persist them to disk and rotate old logs (max 100) - Persist recent process logs, include metadata (exit code, signal, restart attempts, memory) and human-readable sizes in crash reports - Integrate crash logging into ProcessMonitor: save crash logs on non-zero exits and errors, and persist/rotate logs - Improve ProcessMonitor and ProcessWrapper by tracking and removing event listeners to avoid memory leaks - Clear pidusage cache more aggressively to prevent stale entries - Enhance TspmIpcClient to store/remove lifecycle event handlers on disconnect to avoid dangling listeners - Add tests and utilities: test/test.crashlog.direct.ts, test/test.crashlog.manual.ts and test/test.crashlog.ts to validate crash log creation and rotation ## 2025-08-31 - 5.9.0 - feat(cli) Add interactive edit flow to CLI and improve UX - Add -i / --interactive flag to tspm add to open an interactive editor immediately after adding a process - Implement interactiveEditProcess helper (smartinteract-based) to provide interactive editing for process configs - Enable tspm edit to launch the interactive editor (replaces prior placeholder flow) - Improve user-facing message when no processes are configured in tspm list - Lower verbosity for missing saved configs on daemon startup (changed logger.info → logger.debug) ## 2025-08-31 - 5.8.0 - feat(core) Add core TypeScript TSPM implementation: CLI, daemon, client, process management and tests - Add CLI entrypoint and command set (start/stop/add/list/logs/daemon/service/stats/reset and batch ops) - Add daemon implementation with ProcessManager, ProcessMonitor, ProcessWrapper, LogPersistence and config storage - Add IPC client (tspmIpcClient) and TspmServiceManager for systemd integration using smartipc/smartdaemon - Introduce shared protocol types, process ID helpers and standardized error codes for stable IPC - Include tests and test assets for daemon, integration and IPC client scenarios - Add README and package metadata (package.json, npmextra.json, commitinfo) ## 2025-08-31 - 5.7.0 - feat(cli) Add 'stats' CLI command and daemon stats aggregation; fix process manager & wrapper state handling - Add new 'stats' CLI command to show daemon + process statistics (memory, CPU, uptime, logs in memory, paths, configs) and include it in the default help output - Implement daemon-side aggregation for logs-in-memory, per-process log counts/bytes, and expose tspmDir/socket/pidFile and config counts in daemon:status - Enhance startById handler to detect already-running monitors and return current status/pid instead of attempting to restart - Improve ProcessManager start/restart/stop behavior: if an existing monitor exists but is not running, restart it; ensure PID and status are updated consistently (clear PID on stop) - Fix ProcessWrapper lifecycle handling: clear internal process reference on exit, improve isRunning() and getPid() semantics to reflect actual runtime state - Update IPC types to include optional metadata fields (paths, configs, logsInMemory) in DaemonStatusResponse ## 2025-08-31 - 5.6.2 - fix(processmanager) Improve process lifecycle handling and cleanup in daemon, monitors and wrappers - StartAll: when a monitor exists but is not running, restart it instead of skipping — ensures saved processes are reliably brought online. - ProcessMonitor.stop: cancel any pending restart timers to prevent stray restarts after explicit stop. - ProcessWrapper: add killProcessTree helper and use it for graceful (SIGTERM) and force (SIGKILL) shutdowns to reliably signal child processes. - Daemon stopAll: yield briefly after stopping processes and inspect monitors (not only processInfo) to accurately report stopped vs failed processes. ## 2025-08-31 - 5.6.1 - fix(daemon) Ensure robust process shutdown and improve logs/subscriber diagnostics - Make ProcessWrapper.stop asynchronous and awaitable to avoid race conditions when stopping processes - Signal entire process groups on POSIX (kill by negative PID) and fall back to per-PID signalling; escalate to SIGKILL after a timeout - Await processWrapper.stop() from ProcessMonitor when enforcing memory limits or handling exits/errors to ensure child processes are cleaned up - Add logs:subscribers IPC endpoint and corresponding types to inspect current subscribers for a process log topic - Add optional CLI debug output in logs command (enabled via TSPM_DEBUG=true) to print subscriber counts and details - Support passing request.lines to getLogs handler in daemon to limit returned log entries ## 2025-08-30 - 5.6.0 - feat(processmonitor) Add CPU monitoring and display CPU in process list - CLI: show a CPU column in the `tspm list` output (adds formatting and placeholder name display) - Daemon: ProcessMonitor now collects CPU usage for the process group in addition to memory - Daemon: ProcessMonitor exposes getLastCpuUsage() and ProcessManager syncs CPU values into IProcessInfo - Non-breaking: UI and internal stats enriched to surface CPU metrics for processes ## 2025-08-30 - 5.5.0 - feat(logs) Improve logs streaming and backlog delivery; add CLI filters and ndjson output - CLI: add new logs options: --since, --stderr-only, --stdout-only and --ndjson; enhance streaming output and gap detection - CLI: fetch backlog conditionally (honoring --since) and print filtered results before live streaming - Client: add TspmIpcClient.requestLogsBacklogStream, onStream and onBacklogTopic helpers to receive backlog chunks and streams - Daemon: add logs:subscribe IPC handler to stream backlog entries to requesting client in small batches - Protocol: extend IPC types with LogsSubscribeRequest/Response and register 'logs:subscribe' method - Dependency: bump @push.rocks/smartipc to ^2.3.0 to support the streaming/IPC changes ## 2025-08-30 - 5.4.2 - fix(cli/process/logs) Reset log sequence on process restart to avoid false log gap warnings - Track process runId when streaming logs and initialize lastRunId from fetched logs - When a new runId is detected, reset lastSeq so that subsequent streamed logs are accepted (prevents spurious gap warnings) - Emit an informational message when a restart/runId change is detected to aid debugging of log streams ## 2025-08-30 - 5.4.1 - fix(processmonitor) Bump tsbuild devDependency and relax ps-tree callback typing in ProcessMonitor - Update devDependency @git.zone/tsbuild from ^2.6.7 to ^2.6.8 - Change psTree callback types in ts/daemon/processmonitor.ts to accept any error and ReadonlyArray for children to improve type compatibility ## 2025-08-30 - 5.4.0 - feat(daemon) Add CLI systemd service refresh on version mismatch and fix daemon memory leak; update dependencies - CLI: when client and daemon versions differ, prompt to refresh the systemd service and optionally disable/enable the service automatically - Daemon: clear pidusage state for PIDs on process exit/stop to prevent memory leaks in long-running monitors - Client: expose smartdaemon in client plugin exports and fix import path for tspm.servicemanager - Package: tighten dependency ranges (set specific versions) and add @types for pidusage and ps-tree - Misc: ensure IPC disconnects and PID/socket handling improvements were integrated alongside the above changes ## 2025-08-30 - 5.3.2 - fix(daemon) Improve daemon log delivery and process monitor memory accounting; gate debug output and update tests to numeric ProcessId - Deliver process logs only to subscribed clients instead of broadcasting to all connections (reduce unnecessary IPC traffic and noise) - Implement incremental log memory accounting in ProcessMonitor using an estimateLogSize helper and WeakMap to avoid repeated JSON.stringify and reduce CPU/memory overhead - Seed the incremental size map when loading persisted logs so memory accounting is accurate after restart - Trim logs incrementally by subtracting estimated sizes of removed entries (avoids O(n) recalculation) - Gate verbose console/debug output behind TSPM_DEBUG to prevent spamming in normal runs (applies to ProcessWrapper and ProcessMonitor) - Improve process wrapper stdout/stderr debug logging to be conditional on debug mode - Update tests to use numeric ProcessId via toProcessId(...) for consistency with typed IDs ## 2025-08-30 - 5.3.1 - fix(client(tspmIpcClient)) Use bare topic names for IPC client subscribe/unsubscribe to fix log subscription issues - Updated ts/client/tspm.ipcclient.ts to call ipcClient.subscribe/unsubscribe with the bare topic (e.g. 'logs.') instead of prefixed 'topic:<...>'. - Added comments clarifying that the IpcClient registers the 'topic:' prefix internally. - Fixes incorrect topic registration that could prevent log streaming handlers from receiving messages. ## 2025-08-30 - 5.3.0 - feat(cli/daemon/processmonitor) Add flexible target resolution and search command; improve restart/backoff and error handling - Add new cli command `search` to find processes by id or name fragment. - Allow flexible process targets in CLI commands (accepts numeric id, id:, or name: