@hackmd/spm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HackMD Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# SPM — Simpler Process Manager
+
+A minimal process manager implementing a lean subset of [pm2](https://pm2.keymetrics.io/) features, with some extensions, designed for better development script setup. Lightweight, zero daemon, and ecosystem config compatible.
+
+## Features
+
+- **Start / Stop / Restart** — Manage multiple services from a single config
+- **Multi-instance** — Run multiple instances with port/env auto-increment
+- **Log management** — Tail, filter, flush, and rotate logs
+- **JSON output** — `jlist` for machine-readable status (CI/scripting)
+- **Log rotation** — Size-based rotation and retention with optional background watcher
+
+## Installation
+
+```bash
+npm install -g @hackmd/spm
+```
+
+Or with Bun:
+
+```bash
+bun add -g @hackmd/spm
+```
+
+## Quick Start
+
+1. Create an ecosystem config file (e.g. `ecosystem.config.js`) in your project:
+
+```javascript
+export default {
+  apps: [
+    {
+      name: 'api',
+      script: 'node',
+      args: 'server.js',
+      instances: 2,
+      env: { PORT: '3000' },
+      increment_vars: ['PORT'],
+    },
+    {
+      name: 'worker',
+      script: 'node',
+      args: 'worker.js',
+    },
+  ],
+}
+```
+
+2. Run SPM:
+
+```bash
+spm start          # Start all services
+spm start api      # Start specific service
+spm list           # List services and PIDs
+spm stop           # Stop all
+spm restart api    # Restart specific service
+spm logs api -t    # Tail logs
+```
+
+## Configuration
+
+| Option | Description |
+|--------|-------------|
+| `name` | Service identifier |
+| `script` | Command to run (e.g. `node`, `bun`, `python`) |
+| `args` | Arguments passed to the script |
+| `instances` | Number of instances (default: 1) |
+| `env` | Environment variables |
+| `increment_vars` | Env vars to increment per instance (e.g. `PORT`) |
+
+Config file is resolved from `./ecosystem.custom.config.js` by default. Override with `--config`:
+
+```bash
+spm --config ./my-ecosystem.config.js start
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `spm start [service]` | Start all or a specific service |
+| `spm stop [service]` | Stop processes (alias: `kill`) |
+| `spm restart [service]` | Restart processes |
+| `spm list` | List services and running PIDs |
+| `spm jlist` | JSON output of service status |
+| `spm logs [service]` | View logs (`-t` tail, `-n` lines, `-f` filter) |
+| `spm flush [service]` | Clear log files |
+| `spm rotate start` | Start log rotation watcher |
+| `spm rotate stop` | Stop rotation watcher |
+
+## Log Rotation
+
+Logs are stored in `~/.spm2/logs/`. Rotation:
+
+- Rotates when a log exceeds 10MB
+- Removes logs older than 3 days
+- Run `spm rotate start` for a background watcher
+
+## Shell Integration
+
+Completions require [jq](https://jqlang.github.io/jq/). App selector also requires [fzf](https://github.com/junegunn/fzf).
+
+### Bash
+
+**Completions** — Source the script (requires [bash-completion](https://github.com/scop/bash-completion); on macOS: `brew install bash-completion@2`):
+
+```bash
+# After npm install -g @hackmd/spm:
+source $(npm root -g)/@hackmd/spm/completions/bash/spm.bash
+# Or add to ~/.bashrc:
+# source /path/to/spm/completions/bash/spm.bash
+```
+
+**App selector** — Source the script:
+
+```bash
+source $(npm root -g)/@hackmd/spm/completions/bash/spm_app_selector.sh
+# Then:
+spm_app_selector start
+spm_app_selector --appName=api restart
+```
+
+### Zsh
+
+**Completions** — Add the completion dir to `fpath` and ensure compinit runs:
+
+```bash
+# After npm install -g @hackmd/spm:
+fpath=($(npm root -g)/@hackmd/spm/completions/zsh $fpath)
+compinit
+# Or copy to a dir in $fpath:
+mkdir -p ~/.zsh/completions
+cp $(npm root -g)/@hackmd/spm/completions/zsh/_spm ~/.zsh/completions/
+# Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)
+```
+
+**App selector** — Source the script:
+
+```bash
+source $(npm root -g)/@hackmd/spm/completions/zsh/spm_app_selector.zsh
+spm_app_selector start
+```
+
+### Fish
+
+**Completions** — Copy to your Fish config:
+
+```bash
+mkdir -p ~/.config/fish/completions
+cp $(npm root -g)/@hackmd/spm/completions/fish/spm.fish ~/.config/fish/completions/
+```
+
+**App selector** — Copy the function:
+
+```bash
+mkdir -p ~/.config/fish/functions
+cp $(npm root -g)/@hackmd/spm/completions/fish/functions/spm_app_selector.fish ~/.config/fish/functions/
+```
+
+Usage:
+
+```fish
+spm_app_selector start
+spm_app_selector --appName=api restart
+spm_app_selector --config=ecosystem.config.js logs
+```
+
+## License
+
+MIT

package/completions/bash/spm.bash

@@ -0,0 +1,93 @@
+# Bash completion for spm
+# Usage: source this file or copy to /etc/bash_completion.d/spm
+# Requires: bash-completion (Linux) or bash-completion2 (macOS: brew install bash-completion@2)
+
+_spm_services() {
+  spm jlist 2>/dev/null | jq -r '.[].name'
+}
+
+_spm() {
+  local cur prev words cword
+  if declare -f _init_completion &>/dev/null; then
+    _init_completion -s || return
+  else
+    words=("${COMP_WORDS[@]}")
+    cword=$COMP_CWORD
+    cur="${words[cword]}"
+    prev="${words[cword-1]}"
+  fi
+
+  local subcommands="start stop kill logs list jlist restart flush rotate"
+  local rotate_subcommands="start watch stop"
+
+  case $prev in
+    -c|--config)
+      if declare -f _filedir &>/dev/null; then
+        _filedir
+      else
+        COMPREPLY=($(compgen -f -X '!*.@(js|mjs|cjs)' -- "$cur"))
+      fi
+      return
+      ;;
+    -s|--signal)
+      COMPREPLY=($(compgen -W "SIGTERM SIGINT SIGKILL" -- "$cur"))
+      return
+      ;;
+    -n|--lines)
+      return
+      ;;
+    -f|--filter)
+      return
+      ;;
+    --cleanup-interval)
+      return
+      ;;
+    spm)
+      COMPREPLY=($(compgen -W "$subcommands -c --config -v --verbose -h --help" -- "$cur"))
+      return
+      ;;
+    rotate)
+      COMPREPLY=($(compgen -W "$rotate_subcommands" -- "$cur"))
+      return
+      ;;
+  esac
+
+  # Check if we're completing after a subcommand that takes a service name
+  for ((i = 1; i < cword; i++)); do
+    case ${words[i]} in
+      start|stop|kill|restart|logs|flush)
+        COMPREPLY=($(compgen -W "$(_spm_services)" -- "$cur"))
+        return
+        ;;
+      rotate)
+        if [[ $i -eq $((cword - 1)) ]]; then
+          COMPREPLY=($(compgen -W "$rotate_subcommands" -- "$cur"))
+        fi
+        return
+        ;;
+    esac
+  done
+
+  # Check for logs options
+  if [[ " ${words[@]} " =~ " logs " ]]; then
+    case $cur in
+      -*) COMPREPLY=($(compgen -W "-t --tail -n --lines -f --filter -h --help" -- "$cur")) ;;
+      *)  COMPREPLY=($(compgen -W "$(_spm_services)" -- "$cur")) ;;
+    esac
+    return
+  fi
+
+  # Check for stop/kill options
+  if [[ " ${words[@]} " =~ " stop " ]] || [[ " ${words[@]} " =~ " kill " ]]; then
+    case $cur in
+      -*) COMPREPLY=($(compgen -W "-s --signal -h --help" -- "$cur")) ;;
+      *)  COMPREPLY=($(compgen -W "$(_spm_services)" -- "$cur")) ;;
+    esac
+    return
+  fi
+
+  # Default: complete subcommands or global options
+  COMPREPLY=($(compgen -W "$subcommands -c --config -v --verbose -h --help" -- "$cur"))
+}
+
+complete -F _spm spm

package/completions/bash/spm_app_selector.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Interactive service picker for spm. Requires fzf and jq.
+# Usage: source this file, then run spm_app_selector start|restart|logs|stop|flush
+
+spm_app_selector() {
+  local command=""
+  local config=""
+  local app_name=""
+
+  while [[ $# -gt 0 ]]; do
+    case $1 in
+      --config=*)
+        config="${1#*=}"
+        shift
+        ;;
+      --appName=*)
+        app_name="${1#*=}"
+        shift
+        ;;
+      -h|--help)
+        echo "Usage: spm_app_selector [OPTIONS] COMMAND"
+        echo ""
+        echo "Options:"
+        echo "  --appName=APP_NAME    Specify the application name directly."
+        echo "  --config=CONFIG_FILE  Specify the ecosystem configuration file."
+        echo "  -h, --help            Display this help message."
+        echo ""
+        echo "Examples:"
+        echo "  spm_app_selector start"
+        echo "  spm_app_selector --appName=api restart"
+        echo "  spm_app_selector --config=ecosystem.config.js logs"
+        return 0
+        ;;
+      start|stop|kill|restart|logs|flush)
+        command="$1"
+        shift
+        break
+        ;;
+      *)
+        echo "Unknown option or command: $1"
+        return 1
+        ;;
+    esac
+  done
+
+  if [[ -z "$command" ]]; then
+    echo "Usage: spm_app_selector [OPTIONS] COMMAND"
+    echo "COMMAND must be one of: start stop kill restart logs flush"
+    return 1
+  fi
+
+  if [[ -z "$config" ]]; then
+    if [[ -f ecosystem.config.js ]]; then
+      config="ecosystem.config.js"
+    elif [[ -f ecosystem.config.cjs ]]; then
+      config="ecosystem.config.cjs"
+    elif [[ -f ecosystem.custom.config.js ]]; then
+      config="ecosystem.custom.config.js"
+    fi
+  fi
+
+  if [[ -z "$config" ]]; then
+    echo "No ecosystem configuration file found."
+    return 1
+  fi
+
+  if [[ -z "$app_name" ]]; then
+    app_name=$(spm ${config:+--config "$config"} jlist 2>/dev/null | jq -r '.[].name' | fzf)
+  fi
+
+  if [[ -n "$app_name" ]]; then
+    if [[ -n "$config" ]]; then
+      spm --config "$config" "$command" "$app_name"
+    else
+      spm "$command" "$app_name"
+    fi
+  else
+    echo "No application selected."
+    return 1
+  fi
+}

package/completions/fish/functions/spm_app_selector.fish

@@ -0,0 +1,61 @@
+function spm_app_selector
+    argparse 'h/help' 'appName=' 'config=' -- $argv
+    or return
+
+    if set -q _flag_help
+        echo "Usage: spm_app_selector [OPTIONS] -- [COMMAND]"
+        echo ""
+        echo "Options:"
+        echo "  --appName=APP_NAME    Specify the application name directly."
+        echo "  --config=CONFIG_FILE  Specify the ecosystem configuration file (ecosystem.config.js or ecosystem.custom.config.js)."
+        echo "  -h, --help            Display this help message and exit."
+        echo ""
+        echo "Examples:"
+        echo "  spm_app_selector start"
+        echo "  spm_app_selector --appName=api restart"
+        echo "  spm_app_selector --config=ecosystem.config.js logs"
+        return
+    end
+
+    if not set -q _flag_config
+        if test -f ecosystem.config.js
+            set _flag_config ecosystem.config.js
+        else if test -f ecosystem.config.cjs
+            set _flag_config ecosystem.config.cjs
+        else if test -f ecosystem.custom.config.js
+            set _flag_config ecosystem.custom.config.js
+        end
+    end
+
+    if not set -q _flag_config
+        echo "No ecosystem configuration file found."
+        return
+    end
+
+    set -l command $argv[1]
+    if test -z "$command"
+        echo "Usage: spm_app_selector [OPTIONS] COMMAND"
+        echo "COMMAND must be one of: start stop kill restart logs flush"
+        return 1
+    end
+
+    if set -q _flag_appName
+        set APP_NAME $_flag_appName
+    else
+        set spm_args
+        if set -q _flag_config
+            set -a spm_args --config $_flag_config
+        end
+        set APP_NAME (spm $spm_args jlist 2>/dev/null | jq -r '.[].name' | fzf)
+    end
+
+    if test -n "$APP_NAME"
+        set spm_args
+        if set -q _flag_config
+            set -a spm_args --config $_flag_config
+        end
+        spm $spm_args $command $APP_NAME
+    else
+        echo "No application selected."
+    end
+end

package/completions/fish/spm.fish

@@ -0,0 +1,44 @@
+# Disable file completions globally for spm
+complete -c spm -f
+
+# Helper function to check if spm has not received a subcommand
+function __fish_spm_no_subcommand --description "Check if spm has not received a subcommand"
+  for i in (commandline -opc)
+    if contains -- $i start stop kill logs list jlist restart flush rotate
+      return 1
+    end
+  end
+  return 0
+end
+
+# Dynamic service names completion using spm jlist
+function __fish_spm_process_names --description "Fetch list of spm services"
+  spm jlist 2>/dev/null | jq -r '.[].name'
+end
+
+# Root-level subcommands with descriptions
+complete -c spm -n '__fish_spm_no_subcommand' -a "start" -d "Start service instance(s)"
+complete -c spm -n '__fish_spm_no_subcommand' -a "stop" -d "Stop service instance(s)"
+complete -c spm -n '__fish_spm_no_subcommand' -a "kill" -d "Alias for 'stop'"
+complete -c spm -n '__fish_spm_no_subcommand' -a "logs" -d "Display logs for service instance(s)"
+complete -c spm -n '__fish_spm_no_subcommand' -a "list" -d "List services with running PIDs"
+complete -c spm -n '__fish_spm_no_subcommand' -a "jlist" -d "List services in JSON format"
+complete -c spm -n '__fish_spm_no_subcommand' -a "restart" -d "Restart service instance(s)"
+complete -c spm -n '__fish_spm_no_subcommand' -a "flush" -d "Clear log file contents"
+complete -c spm -n '__fish_spm_no_subcommand' -a "rotate" -d "Manage log rotation"
+
+# Dynamic service name completion for commands that take a service argument
+for cmd in start stop restart logs flush kill
+  complete -c spm -n "__fish_seen_subcommand_from $cmd" -a "(__fish_spm_process_names)" -d "Service names"
+end
+
+# Subcommand-specific completions for the logs command
+complete -c spm -n '__fish_seen_subcommand_from logs' -a '--tail' -d "Tail log files in real time"
+complete -c spm -n '__fish_seen_subcommand_from logs' -a '-n --lines' -d "Number of lines to show"
+complete -c spm -n '__fish_seen_subcommand_from logs' -a '-f --filter' -d "Filter logs by pattern"
+complete -c spm -n '__fish_seen_subcommand_from logs' -a '-h --help' -d "Show help"
+
+# Completions for the rotate subcommand group
+complete -c spm -n '__fish_seen_subcommand_from rotate' -a "start" -d "Perform log rotation and spawn rotate-watch process"
+complete -c spm -n '__fish_seen_subcommand_from rotate' -a "watch" -d "Continuously watch and rotate logs"
+complete -c spm -n '__fish_seen_subcommand_from rotate' -a "stop" -d "Stop the rotate-watch process"

package/completions/zsh/_spm

@@ -0,0 +1,57 @@
+#compdef spm
+# Zsh completion for spm
+
+_spm_services() {
+  spm jlist 2>/dev/null | jq -r '.[].name'
+}
+
+_spm() {
+  local -a subcommands rotate_subcommands
+  subcommands=(start:Start\ service\ instance\(s\) stop:Stop\ service\ instance\(s\) kill:Alias\ for\ stop logs:Display\ logs list:List\ services\ with\ running\ PIDs jlist:List\ services\ in\ JSON\ format restart:Restart\ service\ instance\(s\) flush:Clear\ log\ file\ contents rotate:Manage\ log\ rotation)
+  rotate_subcommands=(start:Perform\ log\ rotation\ and\ spawn\ rotate-watch\ process watch:Continuously\ watch\ and\ rotate\ logs stop:Stop\ the\ rotate-watch\ process)
+
+  local context state line
+  typeset -A opt_args
+
+  _arguments -C \
+    '(-c --config)'{-c,--config}'[Specify ecosystem config file]:config file:_files' \
+    '(-v --verbose)'{-v,--verbose}'[Enable verbose output]' \
+    '(-h --help)'{-h,--help}'[Show help]' \
+    '1:subcommand:->subcommand' \
+    '*::args:->args'
+
+  case $state in
+    subcommand)
+      _describe 'subcommand' subcommands
+      ;;
+    args)
+      case $words[2] in
+        start|restart|flush)
+          _values 'service' $(_spm_services)
+          ;;
+        logs)
+          _arguments \
+            '(-t --tail)'{-t,--tail}'[Tail log files in real time]' \
+            '(-n --lines)'{-n,--lines}'[Number of lines to show]:lines' \
+            '(-f --filter)'{-f,--filter}'[Filter logs by pattern]:pattern' \
+            '(-h --help)'{-h,--help}'[Show help]' \
+            '::service:($(_spm_services))'
+          ;;
+        stop|kill)
+          _arguments \
+            '(-s --signal)'{-s,--signal}'[Signal to send]:signal:(SIGTERM SIGINT SIGKILL)' \
+            '(-h --help)'{-h,--help}'[Show help]' \
+            '::service:($(_spm_services))'
+          ;;
+        rotate)
+          _describe 'rotate subcommand' rotate_subcommands
+          ;;
+        *)
+          _normal
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_spm "$@"

package/completions/zsh/spm_app_selector.zsh

@@ -0,0 +1,80 @@
+# Interactive service picker for spm. Requires fzf and jq.
+# Usage: source this file, then run spm_app_selector start|restart|logs|stop|flush
+
+spm_app_selector() {
+  local command=""
+  local config=""
+  local app_name=""
+
+  while [[ $# -gt 0 ]]; do
+    case $1 in
+      --config=*)
+        config="${1#*=}"
+        shift
+        ;;
+      --appName=*)
+        app_name="${1#*=}"
+        shift
+        ;;
+      -h|--help)
+        echo "Usage: spm_app_selector [OPTIONS] COMMAND"
+        echo ""
+        echo "Options:"
+        echo "  --appName=APP_NAME    Specify the application name directly."
+        echo "  --config=CONFIG_FILE  Specify the ecosystem configuration file."
+        echo "  -h, --help            Display this help message."
+        echo ""
+        echo "Examples:"
+        echo "  spm_app_selector start"
+        echo "  spm_app_selector --appName=api restart"
+        echo "  spm_app_selector --config=ecosystem.config.js logs"
+        return 0
+        ;;
+      start|stop|kill|restart|logs|flush)
+        command="$1"
+        shift
+        break
+        ;;
+      *)
+        echo "Unknown option or command: $1"
+        return 1
+        ;;
+    esac
+  done
+
+  if [[ -z "$command" ]]; then
+    echo "Usage: spm_app_selector [OPTIONS] COMMAND"
+    echo "COMMAND must be one of: start stop kill restart logs flush"
+    return 1
+  fi
+
+  if [[ -z "$config" ]]; then
+    if [[ -f ecosystem.config.js ]]; then
+      config="ecosystem.config.js"
+    elif [[ -f ecosystem.config.cjs ]]; then
+      config="ecosystem.config.cjs"
+    elif [[ -f ecosystem.custom.config.js ]]; then
+      config="ecosystem.custom.config.js"
+    fi
+  fi
+
+  if [[ -z "$config" ]]; then
+    echo "No ecosystem configuration file found."
+    return 1
+  fi
+
+  if [[ -z "$app_name" ]]; then
+    app_name=$(spm ${config:+--config "$config"} jlist 2>/dev/null | jq -r '.[].name' | fzf)
+  fi
+
+  if [[ -n "$app_name" ]]; then
+    if [[ -n "$config" ]]; then
+      spm --config "$config" "$command" "$app_name"
+    else
+      spm "$command" "$app_name"
+    fi
+  else
+    echo "No application selected."
+    return 1
+  fi
+}