🚀 Smart Terminal Handler (sth)

A zero-config, cross-platform CLI and Node.js toolkit designed to supercharge your daily terminal workflows.

Features • Installation • CLI Usage • API

💡 Why smart-terminal-handler?

Developers constantly struggle with tedious, platform-dependent shell commands. smart-terminal-handler maps human-friendly commands to OS-specific terminal routines automatically under the hood for Windows, macOS, and Linux. No more memorizing lsof -i, netstat -ano, or ipconfig /flushdns!

✨ Features

• 🔌 Smart Port Killer: Identify and terminate zombie processes occupying development ports (e.g., 3000). Maps automatically to platform-native commands (lsof/kill on macOS/Linux, netstat/taskkill on Windows).
• 🧭 Interactive CLI Wizard: Run sth without arguments to access an interactive, prompt-based menu for a fully guided experience.
• 📡 IP Address Lookup: Instantly view local IPv4 network interface addresses and resolve your public IP in a clean terminal layout.
• 🔄 DNS Cache Flusher: Flush DNS caching configurations reliably across Windows, macOS, and Linux systems.
• 💣 Dependency Nuker: Wipe out node_modules and lockfiles recursively using high-performance native commands, followed by an automated clean dependency reinstall (npm, yarn, or pnpm).
• 📊 System Resource Dashboard: Get a quick overview of CPU, memory, OS version, Node.js version, and system uptime formatted in a beautiful terminal table.
• 📡 Network Diagnostics: Scan common ports, resolve multiple DNS records in detail, and run a download speed and latency test.
• 🔍 Git Workspace Auditor: Scan a directory for Git projects to see branch name, uncommitted status, ahead/behind commits relative to upstream, and remote URLs in a consolidated overview.

📦 Installation

You can run the utility instantly using npx without installing it permanently:

npx smart-terminal-handler <command>

Or install it globally to register the sth command alias:

npm install -g smart-terminal-handler

⌨️ CLI Usage

If you run the CLI without arguments, sth will launch an interactive guided wizard:

sth

Supported Commands

1. Terminate Port (kill)

Terminate processes listening on a target TCP port.

# Terminate processes on port 3000
sth kill 3000

# Open an interactive selector showing all active listening ports
sth kill

2. Clean Dependencies (nuke)

Recursively delete node_modules and lockfiles in the current directory and run a clean reinstall.

# Clean directory and reinstall (prompts for confirmation)
sth nuke

# Skip confirmation prompt
sth nuke -y
# or
sth nuke --yes

# Clean without re-running dependency install
sth nuke --no-reinstall

# Clean but preserve lockfiles
sth nuke --no-lock

3. View IP Configuration (ip)

Display your local network configuration and resolve your current public IP.

sth ip

4. Flush System DNS (dns)

Flush the host machine's DNS caching layer.

sth dns

5. System Resource Dashboard (sys)

View real-time statistics regarding your CPU architecture, memory utilization, Node version, and system uptime.

sth sys

6. Network Diagnostics (net)

Execute connection and network diagnostic helper commands:

# Scan common development ports on localhost
sth net scan

# Scan common ports on a custom host
sth net scan 192.168.1.100

# Resolve various DNS record types (A, AAAA, MX, CNAME, etc.) for a domain
sth net lookup google.com

# Run a live ping and download speed test
sth net speed

7. Git Workspace Auditor (git)

Audit Git status across one or multiple repositories:

# Audit the current repository
sth git

# Audit all Git repositories in the specified parent folder
sth git d:\Packages

💻 Programmatic API

You can import smart-terminal-handler as a dependency in your own projects to build automation scripts, custom dev tasks, or pipelines.

npm install smart-terminal-handler

Usage Examples

const { 
  killPort, 
  getActivePorts, 
  getLocalIPs, 
  getPublicIP, 
  flushDNS, 
  getSysInfo,
  scanPorts,
  resolveDNS,
  runSpeedTest,
  auditGitWorkspace
} = require('smart-terminal-handler');

// 1. Terminate a port programmatically
killPort(3000)
  .then((killedProcesses) => {
    killedProcesses.forEach(proc => {
      console.log(`Killed PID ${proc.pid} (${proc.command})`);
    });
  })
  .catch((err) => console.error('Failed to kill port:', err.message));

// 2. Fetch IP addresses
const localIPs = getLocalIPs();
localIPs.forEach(iface => {
  console.log(`Interface ${iface.interface}: ${iface.address}`);
});

getPublicIP().then(ip => console.log(`Public IP: ${ip}`));

// 3. Flush system DNS
flushDNS().then(result => {
  console.log(`Flushed DNS successfully using command: ${result.cmd}`);
});

// 4. Get System Info
const sysInfo = getSysInfo();
console.log(`Platform: ${sysInfo.platform}, Arch: ${sysInfo.arch}`);

// 5. Scan open ports programmatically
scanPorts('127.0.0.1').then(ports => {
  console.log('Open ports:', ports);
});

// 6. Query multiple DNS records
resolveDNS('google.com').then(records => {
  console.log('DNS records:', records);
});

// 7. Measure speed and latency
runSpeedTest().then(test => {
  console.log(`Latency: ${test.latencyMs}ms, Download speed: ${test.speedMbps} Mbps`);
});

// 8. Audit a directory containing Git repositories
auditGitWorkspace('./packages').then(repos => {
  console.log(repos);
});

📜 License

This project is licensed under the ISC License. Feel free to use and distribute it!