portdash 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Varsha Konda
+
+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,38 @@
+# portdash
+
+Scan localhost ports and show a dashboard of running dev servers (zero dependencies).
+
+## Install / Run
+
+```bash
+npx portdash --open
+
+# or
+npm install -g portdash
+portdash --open
+```
+
+Node.js 18+.
+
+## Usage
+
+```bash
+portdash                # dashboard at http://127.0.0.1:4789
+portdash --once         # print and exit
+portdash --once --json  # JSON output
+portdash 3000,5173,8080
+portdash 3000-5000
+```
+
+All options: `portdash --help`.
+
+## Development
+
+```bash
+npm test
+node src/portdash.mjs
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "portdash",
+  "version": "0.1.0",
+  "description": "Localhost dev server dashboard",
+  "type": "module",
+  "bin": {
+    "portdash": "src/portdash.mjs"
+  },
+  "files": [
+    "src/portdash.mjs"
+  ],
+  "scripts": {
+    "start": "node src/portdash.mjs",
+    "test": "node --test test/portdash.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "dev",
+    "localhost",
+    "ports",
+    "dashboard",
+    "cli",
+    "vite",
+    "nextjs",
+    "storybook",
+    "development"
+  ],
+  "author": "Varsha Konda",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/portdash.mjs

@@ -0,0 +1,635 @@
+#!/usr/bin/env node
+
+import { createServer, request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { Socket } from 'node:net';
+import { exec } from 'node:child_process';
+import { parseArgs as parseCli } from 'node:util';
+
+const DEFAULT_BIND_HOST = '127.0.0.1';
+const DEFAULT_DASHBOARD_PORT = 4789;
+const DEFAULT_TIMEOUT_MS = 700;
+const DEFAULT_CONCURRENCY = 128;
+const DEFAULT_RANGE = '3000-9999';
+const SCAN_HOST = '127.0.0.1';
+
+// ============================================================================
+// CLI Argument Parsing
+// ============================================================================
+
+function showHelp() {
+  console.log(`portdash - localhost dev server dashboard
+
+Usage:
+  portdash [targets] [options]
+
+Targets (optional):
+  3000 5173            Scan specific ports
+  3000,5173,8080       Scan specific ports
+  3000-5000            Scan a range (default: ${DEFAULT_RANGE})
+
+Options:
+  --open, -o           Open browser after starting
+  --once, -1           Print results and exit
+  --json, -j           JSON output (implies --once)
+  --bind <host>        Dashboard bind host (default: ${DEFAULT_BIND_HOST})
+  --port <port>        Dashboard port (default: ${DEFAULT_DASHBOARD_PORT})
+  --ports <list>       Comma-separated ports to scan (e.g., "3000,5173,6006")
+  --range <a-b>        Port range to scan (default: ${DEFAULT_RANGE})
+  --timeout <ms>       Per-port probe timeout (default: ${DEFAULT_TIMEOUT_MS})
+  --concurrency <n>    Max concurrent probes (default: ${DEFAULT_CONCURRENCY})
+  --no-title           Skip title fetching (faster)
+  --no-https           Disable HTTPS fallback probing
+  --help, -h           Show this help
+
+Examples:
+  portdash --open
+  portdash 3000-5000 --open
+  portdash 3000 5173 8080 --once
+  portdash 3000,5173 --json
+`);
+}
+
+function parseIntOption(name, value, { min, max }) {
+  const str = String(value);
+  if (!/^\d+$/.test(str)) {
+    throw new Error(`Invalid ${name}: ${value}`);
+  }
+  const num = Number.parseInt(str, 10);
+  if (num < min || num > max) {
+    throw new Error(`Invalid ${name}: ${value} (expected ${min}-${max})`);
+  }
+  return num;
+}
+
+function parseTargets({ ports, range, positionals }) {
+  const portParts = [];
+  let rangeValue = range ?? null;
+
+  if (ports) portParts.push(ports);
+
+  for (const rawToken of positionals) {
+    const token = rawToken.trim();
+    if (!token) continue;
+
+    const pieces = token.split(',').map(s => s.trim()).filter(Boolean);
+    for (const piece of pieces) {
+      if (/^\d+$/.test(piece)) {
+        portParts.push(piece);
+        continue;
+      }
+
+      if (/^\d+-\d+$/.test(piece)) {
+        if (rangeValue && rangeValue !== piece) {
+          throw new Error(`Only one range can be provided (got "${rangeValue}" and "${piece}")`);
+        }
+        rangeValue = piece;
+        continue;
+      }
+
+      throw new Error(`Invalid target: "${rawToken}"`);
+    }
+  }
+
+  return {
+    ports: portParts.length > 0 ? portParts.join(',') : null,
+    range: rangeValue,
+  };
+}
+
+function parseCliArgs(argv) {
+  const { values, positionals } = parseCli({
+    args: argv.slice(2),
+    allowPositionals: true,
+    strict: true,
+    options: {
+      help: { type: 'boolean', short: 'h' },
+      open: { type: 'boolean', short: 'o', default: false },
+      once: { type: 'boolean', short: '1', default: false },
+      json: { type: 'boolean', short: 'j', default: false },
+      bind: { type: 'string', default: DEFAULT_BIND_HOST },
+      host: { type: 'string' }, // legacy alias for --bind
+      port: { type: 'string', default: String(DEFAULT_DASHBOARD_PORT) },
+      ports: { type: 'string' },
+      range: { type: 'string' },
+      timeout: { type: 'string', default: String(DEFAULT_TIMEOUT_MS) },
+      concurrency: { type: 'string', default: String(DEFAULT_CONCURRENCY) },
+      'no-title': { type: 'boolean', default: false },
+      https: { type: 'boolean', default: true }, // legacy: allow --https
+      'no-https': { type: 'boolean', default: false },
+    },
+  });
+
+  let help = values.help;
+  let open = values.open;
+  let once = values.once;
+  let json = values.json;
+
+  const targetPositionals = [];
+  for (const raw of positionals) {
+    if (raw === 'help') help = true;
+    else if (raw === 'open') open = true;
+    else if (raw === 'once') once = true;
+    else if (raw === 'json') { json = true; once = true; }
+    else targetPositionals.push(raw);
+  }
+
+  const bindHost = values.host ?? values.bind ?? DEFAULT_BIND_HOST;
+  const port = parseIntOption('port', values.port, { min: 1, max: 65535 });
+  const timeout = parseIntOption('timeout', values.timeout, { min: 1, max: 60_000 });
+  const concurrency = parseIntOption('concurrency', values.concurrency, { min: 1, max: 65_536 });
+
+  const targets = parseTargets({ ports: values.ports, range: values.range, positionals: targetPositionals });
+
+  return {
+    help,
+    bindHost,
+    port,
+    ports: targets.ports,
+    range: targets.range,
+    timeout,
+    concurrency,
+    open: open && !(once || json),
+    once: once || json,
+    json,
+    noTitle: values['no-title'],
+    https: values['no-https'] ? false : values.https,
+  };
+}
+
+// ============================================================================
+// Port Parsing
+// ============================================================================
+
+export function expandPorts({ ports, range }) {
+  const result = new Set();
+
+  if (ports) {
+    for (const part of ports.split(',').map(s => s.trim()).filter(Boolean)) {
+      const p = parseInt(part, 10);
+      if (p > 0 && p < 65536) result.add(p);
+    }
+  }
+
+  if (range) {
+    const match = range.match(/^(\d+)-(\d+)$/);
+    if (match) {
+      const start = parseInt(match[1], 10);
+      const end = parseInt(match[2], 10);
+      for (let p = start; p <= end && p < 65536; p++) {
+        if (p > 0) result.add(p);
+      }
+    }
+  }
+
+  if (result.size === 0) {
+    for (let p = 3000; p <= 9999; p++) result.add(p);
+  }
+
+  return Array.from(result).sort((a, b) => a - b);
+}
+
+// ============================================================================
+// Concurrency Limiter
+// ============================================================================
+
+async function limitConcurrency(tasks, limit) {
+  const results = [];
+  const executing = new Set();
+
+  for (const task of tasks) {
+    const promise = task().then(result => {
+      executing.delete(promise);
+      return result;
+    });
+    executing.add(promise);
+    results.push(promise);
+
+    if (executing.size >= limit) {
+      await Promise.race(executing);
+    }
+  }
+
+  return Promise.all(results);
+}
+
+// ============================================================================
+// TCP Probe
+// ============================================================================
+
+function tcpProbe(host, port, timeout) {
+  return new Promise(resolve => {
+    const socket = new Socket();
+    let resolved = false;
+
+    const done = (result) => {
+      if (!resolved) {
+        resolved = true;
+        socket.destroy();
+        resolve(result);
+      }
+    };
+
+    socket.setTimeout(timeout);
+    socket.on('connect', () => done(true));
+    socket.on('timeout', () => done(false));
+    socket.on('error', () => done(false));
+    socket.connect(port, host);
+  });
+}
+
+// ============================================================================
+// HTTP/HTTPS Fetch
+// ============================================================================
+
+function fetchUrl(url, timeout, maxBytes = 65536) {
+  return new Promise(resolve => {
+    const isHttps = url.startsWith('https://');
+    const req = (isHttps ? httpsRequest : httpRequest)(url, {
+      timeout,
+      rejectUnauthorized: false,
+      headers: { 'User-Agent': 'portdash/1.0', 'Accept': 'text/html,*/*' },
+    }, res => {
+      const headers = res.headers;
+      const status = res.statusCode;
+      let body = '';
+
+      res.setEncoding('utf8');
+      res.on('data', chunk => {
+        body += chunk;
+        if (body.length > maxBytes) res.destroy();
+      });
+      res.on('end', () => resolve({ status, headers, body, url }));
+      res.on('error', () => resolve(null));
+    });
+
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+    req.on('error', () => resolve(null));
+    req.end();
+  });
+}
+
+// ============================================================================
+// Title Extraction
+// ============================================================================
+
+export function extractTitle(html) {
+  if (!html) return null;
+  const match = html.match(/<title[^>]*>([^<]*)<\/title>/i);
+  if (!match) return null;
+
+  let title = match[1]
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  return title.length > 80 ? title.slice(0, 77) + '...' : title;
+}
+
+// ============================================================================
+// Port Probe
+// ============================================================================
+
+async function probePort(host, port, opts) {
+  const tcpOpen = await tcpProbe(host, port, opts.timeout);
+  if (!tcpOpen) {
+    const tcpOpen6 = await tcpProbe('::1', port, opts.timeout);
+    if (!tcpOpen6) return null;
+    host = '::1';
+  }
+
+  let result = { port, host, status: null, url: null, title: null };
+
+  // Try HTTP first
+  let httpUrl = `http://${host === '::1' ? '[::1]' : host}:${port}/`;
+  let res = await fetchUrl(httpUrl, opts.timeout);
+
+  // If HTTP failed, try HTTPS
+  if (!res && opts.https) {
+    const httpsUrl = `https://${host === '::1' ? '[::1]' : host}:${port}/`;
+    res = await fetchUrl(httpsUrl, opts.timeout);
+  }
+
+  if (!res) {
+    result.status = 'tcp-only';
+    result.url = httpUrl;
+    return result;
+  }
+
+  // Handle redirects (up to 2)
+  let redirects = 0;
+  while (res.status >= 300 && res.status < 400 && res.headers.location && redirects < 2) {
+    const loc = res.headers.location;
+    if (!loc.includes('localhost') && !loc.includes('127.0.0.1') && !loc.includes('[::1]')) break;
+    res = await fetchUrl(loc.startsWith('http') ? loc : new URL(loc, res.url).href, opts.timeout);
+    if (!res) break;
+    redirects++;
+  }
+
+  if (!res) return result;
+
+  result.status = res.status;
+  result.url = res.url;
+
+  if (!opts.noTitle) {
+    const contentType = res.headers['content-type'] || '';
+    if (contentType.includes('text/html')) {
+      result.title = extractTitle(res.body);
+    }
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Scanner
+// ============================================================================
+
+async function scanPorts(host, ports, opts) {
+  const startTime = Date.now();
+  const tasks = ports.map(port => () => probePort(host, port, opts));
+  const results = await limitConcurrency(tasks, opts.concurrency);
+  const duration = Date.now() - startTime;
+
+  return {
+    timestamp: new Date().toISOString(),
+    duration,
+    services: results.filter(Boolean).sort((a, b) => a.port - b.port),
+  };
+}
+
+// ============================================================================
+// Console Output
+// ============================================================================
+
+function printTable(scan) {
+  const { services, duration } = scan;
+
+  if (services.length === 0) {
+    console.log('No dev servers found.');
+    return;
+  }
+
+  console.log(`Found ${services.length} server(s) in ${duration}ms:\n`);
+  console.log('PORT   TITLE');
+  console.log('─'.repeat(50));
+
+  for (const s of services) {
+    const port = String(s.port).padEnd(6);
+    const title = (s.title || '—').slice(0, 42);
+    console.log(`${port} ${title}`);
+  }
+}
+
+// ============================================================================
+// Dashboard HTML
+// ============================================================================
+
+function renderDashboard() {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>portdash</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    :root { --bg: #0a0a0a; --surface: #141414; --border: #262626; --text: #fafafa; --muted: #737373; --accent: #3b82f6; }
+    body { font-family: system-ui, sans-serif; background: var(--bg); color: var(--text); padding: 2rem; min-height: 100vh; }
+    .container { max-width: 900px; margin: 0 auto; }
+    h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
+    .meta { color: var(--muted); font-size: 0.875rem; margin-bottom: 1rem; }
+    .controls { display: flex; gap: 1rem; margin-bottom: 1rem; align-items: center; }
+    input[type="text"] { background: var(--surface); border: 1px solid var(--border); color: var(--text); padding: 0.5rem 1rem; border-radius: 0.375rem; width: 250px; }
+    input:focus { outline: none; border-color: var(--accent); }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { text-align: left; padding: 0.75rem 1rem; border-bottom: 1px solid var(--border); }
+    th { color: var(--muted); font-weight: 500; font-size: 0.75rem; text-transform: uppercase; }
+    tr:hover { background: var(--surface); }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .port { font-family: monospace; }
+    .empty { text-align: center; padding: 3rem; color: var(--muted); }
+    .status { display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: #22c55e; margin-right: 0.5rem; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>portdash</h1>
+    <div class="meta">
+      <span id="scanInfo">Scanning...</span>
+    </div>
+    <div class="controls">
+      <input type="text" id="filter" placeholder="Filter by port or title...">
+    </div>
+    <table>
+      <thead><tr><th>Port</th><th>Title</th></tr></thead>
+      <tbody id="tbody"></tbody>
+    </table>
+    <div id="empty" class="empty" style="display:none;">No dev servers found</div>
+  </div>
+  <script>
+    let allServices = [];
+    const tbody = document.getElementById('tbody');
+    const empty = document.getElementById('empty');
+    const scanInfo = document.getElementById('scanInfo');
+    const filter = document.getElementById('filter');
+
+    function render() {
+      const q = filter.value.toLowerCase();
+      const filtered = allServices.filter(s =>
+        String(s.port).includes(q) ||
+        (s.title || '').toLowerCase().includes(q)
+      );
+
+      if (filtered.length === 0) {
+        tbody.innerHTML = '';
+        empty.style.display = 'block';
+        return;
+      }
+
+      empty.style.display = 'none';
+      tbody.innerHTML = filtered.map(s => \`
+        <tr>
+          <td class="port"><span class="status"></span>\${s.port}</td>
+          <td><a href="\${s.url}" target="_blank">\${s.title || '—'}</a></td>
+        </tr>
+      \`).join('');
+    }
+
+    async function refresh() {
+      try {
+        const res = await fetch('/api/scan?fresh=1');
+        const data = await res.json();
+        allServices = data.services || [];
+        scanInfo.textContent = \`\${allServices.length} server(s) found in \${data.duration}ms • Last scan: \${new Date(data.timestamp).toLocaleTimeString()}\`;
+        render();
+      } catch (e) {
+        scanInfo.textContent = 'Scan failed';
+      }
+    }
+
+    filter.addEventListener('input', render);
+    refresh();
+    setInterval(refresh, 5000);
+  </script>
+</body>
+</html>`;
+}
+
+// ============================================================================
+// Server
+// ============================================================================
+
+function formatHostForUrl(host) {
+  if (host.includes(':') && !(host.startsWith('[') && host.endsWith(']'))) return `[${host}]`;
+  return host;
+}
+
+async function listenWithFallback(server, host, startPort) {
+  let port = startPort;
+  for (let attempt = 0; attempt < 20; attempt++) {
+    try {
+      await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => {
+          server.removeListener('error', reject);
+          resolve();
+        });
+      });
+      return port;
+    } catch (e) {
+      if (e.code === 'EADDRINUSE') {
+        port++;
+        continue;
+      }
+      throw e;
+    }
+  }
+
+  throw new Error(`Could not find available port (tried ${startPort}-${port})`);
+}
+
+async function startServer(host, port, ports, opts) {
+  let cachedScan = null;
+  let cacheTime = 0;
+
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+
+    if (url.pathname === '/healthz') {
+      res.writeHead(200, { 'Content-Type': 'text/plain' });
+      res.end('ok');
+      return;
+    }
+
+    if (url.pathname === '/api/scan') {
+      const fresh = url.searchParams.get('fresh') === '1';
+      const now = Date.now();
+
+      if (fresh || !cachedScan || now - cacheTime > 3000) {
+        cachedScan = await scanPorts(SCAN_HOST, ports, opts);
+        cacheTime = now;
+      }
+
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(cachedScan));
+      return;
+    }
+
+    if (url.pathname === '/' || url.pathname === '/index.html') {
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(renderDashboard());
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not Found');
+  });
+
+  let actualPort;
+  try {
+    actualPort = await listenWithFallback(server, host, port);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+
+  const urlHost = host === '0.0.0.0' ? '127.0.0.1' : host === '::' ? '::1' : host;
+  const dashboardUrl = `http://${formatHostForUrl(urlHost)}:${actualPort}/`;
+  console.log(`portdash running at ${dashboardUrl}`);
+  console.log(`Scanning ${ports.length} ports on localhost`);
+
+  return { server, url: dashboardUrl };
+}
+
+// ============================================================================
+// Browser Open
+// ============================================================================
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open' :
+              process.platform === 'win32' ? 'start' : 'xdg-open';
+  exec(`${cmd} ${url}`);
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  let args;
+  try {
+    args = parseCliArgs(process.argv);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    showHelp();
+    process.exit(1);
+  }
+
+  if (args.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const ports = expandPorts({ ports: args.ports, range: args.range });
+  const scanOpts = {
+    timeout: args.timeout,
+    concurrency: args.concurrency,
+    noTitle: args.noTitle,
+    https: args.https,
+  };
+
+  if (args.once) {
+    const scan = await scanPorts(SCAN_HOST, ports, scanOpts);
+    if (args.json) {
+      console.log(JSON.stringify(scan, null, 2));
+    } else {
+      printTable(scan);
+    }
+    process.exit(0);
+  }
+
+  const { url } = await startServer(args.bindHost, args.port, ports, scanOpts);
+
+  if (args.open) {
+    openBrowser(url);
+  }
+}
+
+// Only run main when executed directly (not when imported for testing)
+const isMain = import.meta.url === `file://${process.argv[1]}` ||
+               process.argv[1]?.endsWith('portdash.mjs') ||
+               process.argv[1]?.endsWith('portdash');
+
+if (isMain) {
+  main().catch(err => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
+}