⚡ DevStack TUI

A lightweight, zero-overhead Terminal User Interface (TUI) dashboard built in Node.js for managing local microservices orchestration. Keep track of live resource metrics, capture standard output logs dynamically, and toggle service loops—all from a single, beautiful dashboard inside your terminal.

✨ Features

• 📂 Config-Driven Architecture — Drop a devstack.json file into any folder and spin up your stack instantly.
• 📜 Live Aggregated Log Streams — View filtered standard output (stdout) and error streams (stderr) for each service in real-time.
• 📊 Real-Time Performance Monitoring — Track CPU load and system memory allocation with a live diagnostics dashboard.
• ⌨️ Intuitive Keyboard Controls — Navigate and manage services with simple single-key commands.
• 🔒 Environment Injection (Pro Feature) — Safely inject .env configuration variables directly into running sub-processes.
• 🪟 Cross-Platform — Works on Windows, macOS, and Linux with Node.js.

📋 Prerequisites

• Node.js v14.0.0 or higher
• npm v6.0.0 or higher
• Windows, macOS, or Linux terminal environment

🚀 Quick Start

1. Install Globally

npm install -g devstack-tui

Or install locally in your project:

npm install devstack-tui

2. Create Configuration File

Create a devstack.json file in your project root:

{
  "services": [
    {
      "name": "Node Express API",
      "command": "node -e \"setInterval(() => console.log(`[API] ${new Date().toISOString()} GET /v1/users - 200 OK`), 2000)\""
    },
    {
      "name": "Background Worker",
      "command": "node -e \"setInterval(() => console.log('[Worker] Processing queue item...'), 3500)\""
    },
    {
      "name": "Local Network Ping",
      "command": "ping 8.8.8.8"
    }
  ]
}

3. Start the Dashboard

Navigate to your project directory and run:

devstack-tui

🛠️ Configuration

Configuration Schema (devstack.json)

| Property | Type | Required | Description | |----------|------|----------|-------------| | services | Array | ✓ | Array of service definitions | | services[].name | String | ✓ | Display name of the service | | services[].command | String | ✓ | Shell command to execute | | sync_remote_vault | String | ✗ | Premium feature: Remote vault URL (e.g., doppler://production/api) |

Example Configuration

{
  "services": [
    {
      "name": "API Server",
      "command": "npm run dev"
    },
    {
      "name": "Database",
      "command": "docker-compose up db"
    },
    {
      "name": "Cache Server",
      "command": "redis-server"
    }
  ]
}

⌨️ Keyboard Controls

Control your microservices directly from the dashboard using these keyboard shortcuts:

| Key | Action | |-----|--------| | ↑ / ↓ | Navigate up and down the service list | | S | Start the highlighted service | | K | Kill the highlighted service (SIGTERM) | | Q or Ctrl+C | Exit and shut down all running services |

🔒 Environment Configuration (Pro Feature)

The premium tier enables secure environment variable injection. Set up your environment configuration:

1. Create .env File

Copy .env.example to .env in your project root:

cp .env.example .env

2. Configure Environment Variables

Edit .env with your required variables:

# API Configuration
PORT=8080
AUTH_SERVICE_URL=http://localhost:5001
DATABASE_URL=postgresql://postgres:secret@localhost:5432/dev_db

# Security
JWT_SECRET=your_local_development_token_here
API_KEY=mock_key_for_testing

# Environment
NODE_ENV=development
DEBUG=devstack:*

3. Activate Pro Features

For remote vault sync, activate your license:

devstack-tui --auth <your_license_key>

Then uncomment the vault token in your .env file:

DEVSTACK_VAULT_TOKEN=dv_live_abcdef1234567890

📊 Dashboard Layout

The DevStack TUI dashboard is organized into three main sections:

┌─────────────────────────┬──────────────────────────────┐
│   ⚡ Processes Manager   │   📜 Live Standard Output    │
│   (Service List)        │   (Log Stream)               │
│                         │                              │
│  • Node Express API     │  [System] Loaded services... │
│  • Background Worker    │  [API] Server running...     │
│  • Local Network Ping   │  [Worker] Processing...      │
│                         │                              │
├─────────────────────────┴──────────────────────────────┤
│     📊 Diagnostics & Controls (CPU, Memory, Commands)   │
└────────────────────────────────────────────────────────┘

🐛 Troubleshooting

Issue: "devstack.json not found"

Solution: Ensure you have a devstack.json file in your project root directory where you're running the command.

# Verify file exists
ls devstack.json
# or on Windows
dir devstack.json

Issue: "Command not found" (when using global installation)

Solution: Reinstall or link the package:

npm install -g devstack-tui
# Or verify npm bin directory is in PATH
npm config get prefix

Issue: Services don't start or logs appear frozen

Solution: Ensure your service commands are valid and executable:

# Test the command directly in terminal
node -e "console.log('test')"

Issue: Permission denied on Linux/macOS

Solution: Make the script executable:

chmod +x /path/to/node_modules/.bin/devstack-tui

📦 Installation Methods

Global Installation (Recommended for CLI)

npm install -g devstack-tui

Then use from any directory:

devstack-tui

Local Installation (For Project-Specific Use)

npm install devstack-tui --save-dev

Then run via npm scripts in package.json:

{
  "scripts": {
    "dev-monitor": "devstack-tui"
  }
}

Run with:

npm run dev-monitor

🔧 Development

Setting Up Development Environment

# Clone the repository
git clone <repository-url>
cd dev-tui-dashboard

# Install dependencies
npm install

# Link locally for testing
npm link

# Test the CLI
devstack-tui

Project Structure

dev-tui-dashboard/
├── index.js              # Main CLI entry point
├── package.json          # Project metadata and dependencies
├── devstack.json         # Example configuration
├── .env.example          # Environment template
├── README.md             # This file
└── LICENSE               # License file

📝 Dependencies

• neo-blessed (^1.1.11) — Terminal UI framework
• systeminformation (^5.25.0) — System metrics and monitoring

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue for bugs and feature requests.

How to Contribute

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

💡 Tips & Best Practices

• Keep commands simple: Complex shell commands work best when tested independently first.
• Use meaningful names: Service names should clearly identify their purpose.
• Monitor resource usage: Watch the diagnostics panel to ensure services aren't consuming excessive resources.
• Version your config: Check devstack.json into version control so team members can replicate your setup.
• Test locally first: Always test service commands in your terminal before adding them to the dashboard.

📞 Support

For issues, questions, or feature requests, please visit the GitHub Issues page.

🎉 Getting Started Examples

Example 1: Node.js Microservices

{
  "services": [
    {
      "name": "API Server",
      "command": "node api.js"
    },
    {
      "name": "WebSocket Server",
      "command": "node websocket-server.js"
    },
    {
      "name": "Job Queue",
      "command": "node worker.js"
    }
  ]
}

Example 2: Docker Containers with npm

{
  "services": [
    {
      "name": "Frontend Dev Server",
      "command": "npm run dev"
    },
    {
      "name": "Backend API",
      "command": "docker-compose up api"
    },
    {
      "name": "PostgreSQL Database",
      "command": "docker-compose up db"
    }
  ]
}

Example 3: Python and Node.js Mix

{
  "services": [
    {
      "name": "Node Express Server",
      "command": "node server.js"
    },
    {
      "name": "Python Data Service",
      "command": "python app.py"
    },
    {
      "name": "Static File Server",
      "command": "npx http-server ./public"
    }
  ]
}

Made with ❤️ for developers who love their terminal. AUTH_SERVICE_URL=http://localhost:5001 DATABASE_URL=postgresql://postgres:secret@localhost:5432/dev_db

🔑 SYSTEM SECURITY CREDENTIALS

JWT_SECRET=your_super_secret_local_development_token_key_here THIRD_PARTY_API_KEY=mock_api_key_for_local_testing

📊 ENVIRONMENT SPECIFICATION

NODE_ENV=development DEBUG=devstack:* To tell your engine to validate and ingest these secrets, declare the sync_remote_vault routing link right inside your project configuration schema:JSON{ "sync_remote_vault": "doppler://production/api", "services": [ ... ] } Unlocking Your Global Activation LicenseIf your setup requests dynamic secret context injections, activate your commercial runtime workspace license tracking key to bypass the dashboard security hold:Bashdevstack-tui --auth PRO_SKU_YOUR_LICENSE_KEY_HERE Once verified, the tool caches authentication payloads inside your profile folder (%USERPROFILE%.devstack-tui), immediately enabling seamless, multi-variable child process secret routing pipelines.