Skip to content

About

No description, website, or topics provided.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

PROZESSOR

A terminal-first process manager for running and maintaining multiple Node services from one place.

Node.js 18+ Lightweight Plain JS

Prozessor Demo

Note: Don't forget to replace this placeholder with a GIF or screenshot of your tool in action! (Place it in the assets folder)

What is this?

Prozessor is a lightweight terminal process manager. Instead of juggling multiple terminal tabs, it lets you manage all your project repositories from a single Live TUI Dashboard.

It handles cloning, branch tracking, log streaming, and process monitoring automatically.

Key Features

  • 🔄 Automated Git Ops: Auto-clones your project repos and periodically checks for branch updates.
  • 📊 Live TUI Dashboard: Monitor all your services in one terminal window with multiplexed log streaming.
  • 🛡️ Resilient: Whole-tree process shutdown, automatic port reclamation (pre-start, on EADDRINUSE, and across sessions), crash retries, and cooldown periods keep your services healthy and ports clean.
  • 🪶 Lightweight: Plain Node.js (ESM), zero build steps, and no heavy dependencies.

Getting Started

Follow these steps to set up and run it on your machine.

1. Requirements

Ensure you have the following installed on your system:

  • Node.js: v18+
  • Git: Required for cloning and managing repositories.

2. Clone the Repository

Clone PROZESSOR to your local machine and install its dependencies:

git clone https://github.com/SiddDevZ/prozessor-cli.git
cd prozessor-cli
npm install

3. Configure Your Projects

You need to tell it which projects to manage. We provide a safe template to start with. Run the following command to create your local config file:

cp projects.example.json projects.json

Open projects.json in your editor and define your repositories.

4. Setup Environment Variables (Optional)

If your managed projects require .env files, you can store them securely in the envs/ directory.

  1. Create your env files (e.g., envs/.env.myproject).
  2. Link them in your projects.json by setting the envSrc property for that project.

5. Run PROZESSOR

Start the process manager to bring up the dashboard and spawn your services:

npm start

projects.json Properties

Each project entry in your projects.json supports the following:

Property Description Default
name Display key and local folder name (created under projects/) -
repoUrl Git remote URL to clone from -
branch Branch to track and auto-update -
envSrc Env filename inside the envs/ folder (Optional) -
subdir Project subdirectory where the Node service lives backend
entrypoint Node entry file to run server.js
command Shell command to run instead of node <entrypoint>, e.g. npm run dev. Spawned in its own process group, so shutdown still reaps the whole tree (Optional) -
installCmd Install command run before start and after every update. Override it when the project needs its devDependencies (Optional) npm install --production --silent
resetOnUpdate On update, hard-reset to the tracked branch instead of stashing local changes. Use it for projects that rewrite their own tracked files at runtime. Gitignored paths (node_modules/, caches, browser profiles) are preserved (Optional) false
port Port the service listens on. When set, Prozessor reclaims this port before (re)starting so a stale process can never block a fresh start (Optional) auto-detected
enabled Whether it should manage this project true

Global Application Settings:

  • pollInterval: How often to check for git updates.
  • logBufferSize: Number of log lines to keep in memory.
  • maxCrashRetries: How many times to restart a crashing process.
  • autoUpdateCli: Automatically fetch and update the CLI
  • crashCooldownMins: Cooldown duration after exceeding max retries.

Hot reload

PROZESSOR watches projects.json while it runs (a directory watcher plus a 2 s mtime check as a fallback), so you can edit it in place or replace it with write-temp-then-rename. When the file changes, it is diffed against the running config by project name:

  • New project (or enabled flipped to true): cloned, env copied, installCmd run, then started.
  • Removed project: its whole process tree is stopped, it drops out of the dashboard and stops being polled. The cloned folder under projects/ is kept.
  • enabled: false: stopped and no longer polled, but still listed.
  • Any other field changed (branch, command, port, envSrc, ...): re-prepared with the new config, then restarted.
  • Unchanged projects are not touched.

Settings apply live too: pollInterval resets the git poll timer, logBufferSize resizes the buffers, and maxCrashRetries / crashCooldownMins are read on each crash. autoUpdateCli only takes effect on the next start.

A file that is empty, half written, not valid JSON, missing a projects array, or has a project without a name (or a duplicate name) is ignored with one warning in the PROZESSOR log, and nothing that is running changes. Fix the file and the next save is picked up. Changing repoUrl of an already cloned project re-points the existing checkout: the new URL's branch is fetched and the checkout is hard reset onto it (local changes in that folder are discarded, histories may be unrelated), then origin is updated and the project restarts. The same happens when a project is added or enabled and its kept folder points at a different repo. This only happens on a reload, never at startup. Edits made while PROZESSOR is still starting up are applied as soon as the initial start finishes. PROZESSOR's own saves (from the menu) are written atomically too.

Logs and status

Every log line PROZESSOR shows for a project is also appended to logs/<name>.log (plain text, ANSI codes stripped, one line per entry as <ISO time> OUT|ERR <text>). Each file rotates to logs/<name>.log.1 at about 2 MB, so a project never uses more than ~4 MB. PROZESSOR's own messages go to logs/PROZESSOR.log. Characters other than letters, digits, ., _ and - in a name become _ in the file name.

.prozessor-status.json in the root is rewritten atomically (temp file + rename) whenever a project's state changes, and re-checked every 5 s:

{
  "updatedAt": "2026-10-12T10:00:00.000Z",
  "pid": 4242,
  "projects": {
    "my-project": {
      "enabled": true,
      "status": "running",
      "pid": 4301,
      "port": 3000,
      "restarts": 2,
      "lastStart": "2026-10-12T09:58:41.120Z",
      "lastExit": { "code": 1, "signal": null, "at": "2026-10-12T09:58:38.002Z" },
      "commit": "a1b2c3d"
    }
  }
}
  • pid (top level): the PROZESSOR process that wrote the file. If it is no longer alive, the file is stale.
  • status: starting (cloning / installing before the first spawn), running, restarting (update or config change in progress), crashed (waiting 3 s to retry), cooldown (too many crashes, paused for crashCooldownMins), or stopped.
  • pid: the project's process (group leader) while running, else null.
  • port: configured or detected port, else null.
  • restarts: spawns since PROZESSOR started, minus the first one (crash retries, updates and config restarts all count).
  • lastStart / lastExit: ISO times, null until it has happened. lastExit.code / lastExit.signal are what the process exited with.
  • commit: short sha checked out when the process was last spawned, null if unknown.

Only projects in the current projects.json are listed. Both logs/ and .prozessor-status.json are gitignored.

Dashboard Controls

Navigate your services effortlessly using these built-in keyboard shortcuts:

Key Action
m Open the management menu
f Cycle through project log filters
0 Clear active log filter
1-9 Quick-filter to a specific project by index
↑ / ↓ / PgUp / PgDn Scroll through the log history
q / Ctrl+C Quit and gracefully shut down all services

Project Structure

prozessor/
├── lib/
│   ├── config.js
│   ├── hot-reload.js
│   ├── status-file.js
│   ├── git-ops.js
│   ├── process-manager.js
│   ├── port-utils.js
│   ├── state-store.js
│   ├── log-store.js
│   ├── theme.js
│   ├── ui.js
│   └── flair.js
├── envs/
│   └── .env.example
├── projects/                 # Managed repositories are cloned here
├── main.js                   # Application Entrypoint
├── projects.json             # Your local configuration
├── .prozessor-state.json     # Runtime state for cross-session cleanup (gitignored)
├── .prozessor-status.json    # Live per-project status for other tools (gitignored)
├── logs/                     # Persisted per-project logs (gitignored)
├── package.json
└── .gitignore

Security Best Practices

For a clean and secure public release, ensure you:

  • Never commit real .env files to github.
  • Never commit your populated projects.json.
  • Never commit the cloned repositories under the projects/ directory.

(These paths are already ignored in .gitignore by default).

License

(Add your preferred license before publishing)

About

No description, website, or topics provided.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages