@lowdep/portwatch 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rushabh Shah
+
+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,123 @@
+# portwatch
+
+![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen) ![Node](https://img.shields.io/badge/node-%3E%3D14-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
+
+
+Live terminal dashboard for monitoring your local development services.
+
+Checks TCP ports and HTTP/HTTPS URLs on a configurable interval, shows latency, status, and when each service last changed state. Zero dependencies — uses only Node.js built-ins.
+
+---
+
+## Install
+
+```bash
+npm install -g portwatch
+```
+
+Or without installing:
+
+```bash
+npx portwatch
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Create a config in your project
+portwatch init
+
+# 2. Edit .portwatch.json with your services
+# 3. Start the dashboard
+portwatch
+```
+
+---
+
+## Example Output
+
+```
+portwatch  (every 5s · Ctrl+C to exit · config: .portwatch.json)
+
+  Service           Target                  Status     Latency  Changed
+  ─────────────────────────────────────────────────────────────────────────
+  Frontend          localhost:3000          ✓ UP         12ms  2m ago
+  Backend API       localhost:4000          ✓ UP          8ms  5m ago
+  PostgreSQL        localhost:5432          ✓ UP          2ms  10m ago
+  Redis             localhost:6379          ✗ DOWN          —  1m ago
+  Stripe Webhook    http://localhost:8080   ✓ UP         45ms  30s ago
+
+  Last refresh: 14:32:05
+```
+
+---
+
+## Config File (`.portwatch.json`)
+
+```json
+{
+  "interval": 5,
+  "services": [
+    { "name": "Frontend",     "target": "localhost:3000" },
+    { "name": "Backend API",  "target": "localhost:4000" },
+    { "name": "PostgreSQL",   "target": "localhost:5432" },
+    { "name": "Redis",        "target": "localhost:6379" },
+    { "name": "Health check", "target": "http://localhost:4000/health" }
+  ]
+}
+```
+
+### Target formats
+
+| Format | What it checks |
+|---|---|
+| `localhost:3000` | TCP connection to port |
+| `:5432` | TCP on localhost |
+| `3000` | TCP on localhost |
+| `http://localhost:4000` | HTTP GET, checks status < 500 |
+| `https://api.mysite.com/health` | HTTPS GET |
+
+---
+
+## Usage
+
+```bash
+portwatch                     # Uses .portwatch.json in current dir
+portwatch init                # Create starter .portwatch.json
+portwatch ./myconfig.json     # Use a specific config file
+```
+
+---
+
+## Status Indicators
+
+| Symbol | Meaning |
+|---|---|
+| `✓ UP` | Connected and responding |
+| `⚡ SLOW` | Responding but latency > 1000ms |
+| `✗ DOWN` | Connection refused or timed out |
+| `checking…` | Initial check in progress |
+
+---
+
+## License
+
+MIT
+
+---
+
+## Keywords
+
+`port monitor` · `service health` · `dev dashboard` · `localhost monitor` · `tcp check` · `uptime monitor` · `watch ports` · `health dashboard` · `zero dependencies` · `cli`
+
+---
+
+<div align="center">
+
+**Built to solve, shared to help — Rushabh Shah 🛠️✨**
+
+<sub>One of 40+ zero-dependency developer CLI tools — no <code>node_modules</code>, ever.</sub>
+
+</div>

package/bin/portwatch.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+'use strict';
+
+const net   = require('net');
+const http  = require('http');
+const https = require('https');
+const fs    = require('fs');
+const path  = require('path');
+const os    = require('os');
+
+const VERSION   = '1.0.0';
+const CFG_FILE  = '.portwatch.json';
+
+// ─── ANSI ─────────────────────────────────────────────────────────────────────
+const isTTY  = process.stdout.isTTY;
+const c      = (code, t) => isTTY ? `\x1b[${code}m${t}\x1b[0m` : t;
+const bold   = t => c('1',  t);
+const dim    = t => c('2',  t);
+const red    = t => c('31', t);
+const green  = t => c('32', t);
+const yellow = t => c('33', t);
+const cyan   = t => c('36', t);
+const up     = '\x1b[F'; // cursor up one line
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function timeAgo(ts) {
+  if (!ts) return dim('—');
+  const secs = Math.floor((Date.now() - ts) / 1000);
+  if (secs < 5)   return dim('just now');
+  if (secs < 60)  return dim(`${secs}s ago`);
+  if (secs < 3600) return dim(`${Math.floor(secs / 60)}m ago`);
+  return dim(`${Math.floor(secs / 3600)}h ago`);
+}
+
+function parseTarget(raw) {
+  // Accepts: "localhost:3000", "http://localhost:3000", ":5432", "3000"
+  if (typeof raw !== 'string' || !raw.trim()) return null;
+  raw = raw.trim();
+  if (/^https?:\/\//.test(raw)) {
+    const u = new URL(raw);
+    return { type: 'http', url: raw, host: u.hostname, port: parseInt(u.port) || (u.protocol === 'https:' ? 443 : 80) };
+  }
+  const m = raw.match(/^:?(\d+)$/) || raw.match(/^([^:]+):(\d+)$/);
+  if (!m) return null;
+  const host = m[2] ? m[1] : 'localhost';
+  const port = parseInt(m[2] || m[1]);
+  return { type: 'tcp', host, port };
+}
+
+// ─── Checkers ─────────────────────────────────────────────────────────────────
+function checkTCP(host, port, timeoutMs = 3000) {
+  return new Promise(resolve => {
+    const start  = Date.now();
+    const socket = net.createConnection({ host, port });
+    socket.setTimeout(timeoutMs);
+    socket.on('connect', () => {
+      socket.destroy();
+      resolve({ up: true, latency: Date.now() - start });
+    });
+    socket.on('error',   () => { socket.destroy(); resolve({ up: false, latency: null }); });
+    socket.on('timeout', () => { socket.destroy(); resolve({ up: false, latency: null }); });
+  });
+}
+
+function checkHTTP(url, timeoutMs = 5000) {
+  return new Promise(resolve => {
+    const start = Date.now();
+    const lib   = url.startsWith('https') ? https : http;
+    const req   = lib.get(url, { timeout: timeoutMs }, res => {
+      res.resume();
+      const latency = Date.now() - start;
+      resolve({ up: res.statusCode < 500, latency, status: res.statusCode });
+    });
+    req.on('error',   () => resolve({ up: false, latency: null }));
+    req.on('timeout', () => { req.destroy(); resolve({ up: false, latency: null }); });
+  });
+}
+
+async function checkService(svc) {
+  const target = svc._parsed;
+  let result;
+  if (target.type === 'http') {
+    result = await checkHTTP(target.url);
+  } else {
+    result = await checkTCP(target.host, target.port);
+  }
+  return result;
+}
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+function defaultConfig() {
+  return {
+    interval: 5,
+    services: [
+      { name: 'Frontend',     target: 'localhost:3000' },
+      { name: 'Backend API',  target: 'localhost:4000' },
+      { name: 'PostgreSQL',   target: 'localhost:5432' },
+      { name: 'Redis',        target: 'localhost:6379' },
+    ],
+  };
+}
+
+function loadConfig(cfgPath) {
+  try {
+    return JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ─── Renderer ─────────────────────────────────────────────────────────────────
+let prevLines = 0;
+
+function clearPrev() {
+  if (!isTTY || prevLines === 0) return;
+  process.stdout.write(up.repeat(prevLines) + '\x1b[J');
+}
+
+function render(services, interval, cfgFile) {
+  const now = new Date().toLocaleTimeString();
+  const lines = [];
+
+  const nameW   = Math.max(...services.map(s => s.name.length), 12);
+  const targetW = Math.max(...services.map(s => s.target.length), 12);
+
+  lines.push(`${bold('portwatch')}  ${dim(`(every ${interval}s · Ctrl+C to exit · config: ${cfgFile})`)}`);
+  lines.push('');
+  lines.push(
+    `  ${'Service'.padEnd(nameW)}  ${'Target'.padEnd(targetW)}  ${'Status'.padEnd(10)}  ${'Latency'.padStart(8)}  ${'Changed'}`,
+  );
+  lines.push(dim('  ' + '─'.repeat(nameW + targetW + 40)));
+
+  for (const svc of services) {
+    const statusStr = svc.status === undefined
+      ? dim('checking…')
+      : svc.status
+        ? (svc.latency > 1000 ? yellow('⚡ SLOW') : green('✓ UP  '))
+        : red('✗ DOWN');
+
+    const latencyStr = svc.latency != null
+      ? (svc.latency > 1000 ? yellow(`${svc.latency}ms`) : dim(`${svc.latency}ms`))
+      : dim('  —');
+
+    lines.push(
+      `  ${svc.name.padEnd(nameW)}  ${dim(svc.target.padEnd(targetW))}  ${statusStr.padEnd(10)}  ${latencyStr.padStart(8)}  ${timeAgo(svc.changedAt)}`,
+    );
+  }
+
+  lines.push('');
+  lines.push(dim(`  Last refresh: ${now}`));
+
+  clearPrev();
+  process.stdout.write(lines.join('\n') + '\n');
+  prevLines = lines.length;
+}
+
+// ─── Main loop ────────────────────────────────────────────────────────────────
+async function runLoop(services, interval, cfgFile) {
+  // Initial render
+  render(services, interval, cfgFile);
+
+  async function tick() {
+    await Promise.all(services.map(async svc => {
+      const result = await checkService(svc);
+      const wasUp  = svc.status;
+      svc.status   = result.up;
+      svc.latency  = result.latency;
+      if (wasUp !== result.up) svc.changedAt = Date.now();
+    }));
+    render(services, interval, cfgFile);
+  }
+
+  // First real check immediately
+  await tick();
+
+  // Then repeat
+  const timer = setInterval(tick, interval * 1000);
+
+  process.on('SIGINT',  () => { clearInterval(timer); console.log('\n'); process.exit(0); });
+  process.on('SIGTERM', () => { clearInterval(timer); console.log('\n'); process.exit(0); });
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+const args       = process.argv.slice(2);
+const flags      = new Set(args.filter(a => a.startsWith('-')));
+const positional = args.filter(a => !a.startsWith('-'));
+
+if (flags.has('--version') || flags.has('-v')) {
+  console.log(`portwatch v${VERSION}`); process.exit(0);
+}
+
+if (flags.has('--help') || flags.has('-h')) {
+  console.log(`
+${bold('portwatch')} — Live terminal dashboard for dev service monitoring
+
+${bold('USAGE')}
+  portwatch [config-file]
+  portwatch init           Create a .portwatch.json in the current directory
+
+${bold('OPTIONS')}
+  --version    Show version
+  --help       Show this help
+
+${bold('CONFIG')}  (${CFG_FILE})
+  ${JSON.stringify(defaultConfig(), null, 2).split('\n').join('\n  ')}
+
+${bold('TARGETS')}
+  "localhost:3000"          TCP port check
+  ":5432"                   TCP on localhost
+  "http://localhost:4000"   HTTP check (validates < 500 status)
+  "https://api.mysite.com"  HTTPS check
+
+${bold('EXAMPLES')}
+  portwatch                 Look for .portwatch.json in current dir
+  portwatch init            Create a starter .portwatch.json
+  portwatch ./myconfig.json Use a specific config file
+`);
+  process.exit(0);
+}
+
+// init sub-command
+if (positional[0] === 'init') {
+  const dest = path.join(process.cwd(), CFG_FILE);
+  if (fs.existsSync(dest)) {
+    console.log(yellow(`\n.portwatch.json already exists: ${dest}\n`));
+  } else {
+    fs.writeFileSync(dest, JSON.stringify(defaultConfig(), null, 2));
+    console.log(green(`\n✓ Created ${dest}\n`));
+    console.log(dim('  Edit it to add your services, then run: portwatch\n'));
+  }
+  process.exit(0);
+}
+
+// Find config
+const cfgPath = positional[0]
+  ? path.resolve(positional[0])
+  : path.join(process.cwd(), CFG_FILE);
+
+let cfg = loadConfig(cfgPath);
+if (!cfg) {
+  console.log(yellow(`\nNo config found. Using defaults.`));
+  console.log(dim(`  Run \`portwatch init\` to create ${CFG_FILE} in this directory.\n`));
+  cfg = defaultConfig();
+}
+
+const interval = cfg.interval || 5;
+
+// Prepare service objects
+const services = (cfg.services || []).map(svc => {
+  // Accept `target`, `url`, or `host`+`port` field forms
+  const targetStr = svc.target
+    || svc.url
+    || (svc.host && svc.port ? `${svc.host}:${svc.port}` : (svc.port ? `localhost:${svc.port}` : null));
+  const parsed = parseTarget(targetStr);
+  if (!parsed) {
+    console.error(red(`Invalid/missing target for service "${svc.name || '(unnamed)'}" — skipping`));
+    return null;
+  }
+  return {
+    name:       svc.name || targetStr,
+    target:     targetStr,
+    _parsed:    parsed,
+    status:     undefined,
+    latency:    null,
+    changedAt:  null,
+  };
+}).filter(Boolean);
+
+if (!services.length) {
+  console.error(red('\nNo valid services configured.\n'));
+  process.exit(1);
+}
+
+runLoop(services, interval, path.relative(process.cwd(), cfgPath) || CFG_FILE).catch(e => {
+  console.error(red(`\nError: ${e.message}\n`));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@lowdep/portwatch",
+  "version": "1.0.0",
+  "description": "Live terminal dashboard monitoring local dev services — TCP ports and HTTP URLs, zero dependencies",
+  "bin": {
+    "portwatch": "bin/portwatch.js"
+  },
+  "keywords": [
+    "port",
+    "monitor",
+    "dashboard",
+    "developer-tools",
+    "cli",
+    "tcp",
+    "http",
+    "health-check",
+    "devops",
+    "port monitor",
+    "service health",
+    "dev dashboard",
+    "localhost monitor",
+    "tcp check",
+    "uptime monitor",
+    "watch ports",
+    "health dashboard",
+    "zero dependencies"
+  ],
+  "author": "Rushabh Shah",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "bin/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rushabh5000/portwatch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Rushabh5000/portwatch/issues"
+  },
+  "homepage": "https://github.com/Rushabh5000/portwatch#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}