devprobe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,127 @@
+# portprobe
+
+Instant port diagnostics for your local dev environment.
+
+## Why
+
+Every developer has hit it: you start a server and get `EADDRINUSE`, then spend minutes figuring out what's hogging the port. AI coding agents like Claude Code hit the same wall -- they burn tokens retrying commands and guessing what went wrong.
+
+portprobe scans common dev ports in parallel, shows what's listening, which process owns it, and whether it responds to HTTP. One command, zero guesswork.
+
+## Quick start
+
+Run without installing:
+
+```bash
+npx portprobe
+```
+
+Or install globally:
+
+```bash
+npm i -g portprobe
+```
+
+## Usage
+
+### Default scan
+
+Scans common dev ports (3000, 3001, 4200, 5000, 5173, 5432, 6379, 8000, 8080, 8443, 9000, 27017) and prints a table:
+
+```bash
+portprobe
+```
+
+### JSON output
+
+Machine-readable output for scripts and AI agents:
+
+```bash
+portprobe --json
+```
+
+### Single port check
+
+Check whether a specific port is in use:
+
+```bash
+portprobe 3000
+```
+
+### Range scan
+
+Scan a custom range of ports:
+
+```bash
+portprobe --range 3000-9000
+```
+
+### Custom timeout
+
+Set the TCP connection timeout in milliseconds (default: 1000):
+
+```bash
+portprobe --timeout 2000
+```
+
+## Flags
+
+| Flag | Description | Default |
+|---|---|---|
+| `[port]` | Check a single port | — |
+| `--json` | Output as JSON | `false` |
+| `--range <from-to>` | Scan a port range (e.g. `3000-9000`) | — |
+| `--timeout <ms>` | Connection timeout in ms | `1000` |
+| `--version` | Show version | — |
+| `--help` | Show help | — |
+
+## AI Agent integration
+
+portprobe is designed to work well with AI coding agents. Use `--json` to get structured output that an agent can parse directly:
+
+```bash
+portprobe --json
+```
+
+Returns an array of results:
+
+```json
+[
+  {
+    "port": 3000,
+    "status": "up",
+    "pid": 12345,
+    "process": "node",
+    "latency": 2,
+    "protocol": "http"
+  },
+  {
+    "port": 5432,
+    "status": "up",
+    "pid": 501,
+    "process": "postgres",
+    "latency": 1,
+    "protocol": null
+  },
+  {
+    "port": 8080,
+    "status": "free",
+    "pid": null,
+    "process": null,
+    "latency": null,
+    "protocol": null
+  }
+]
+```
+
+An agent can run `npx portprobe --json` before starting a dev server to pick an open port or diagnose a conflict without trial and error.
+
+## Platforms
+
+- **macOS** — full support (uses `lsof` for process resolution)
+- **Linux** — full support (uses `lsof` for process resolution)
+- **Windows** — best-effort (uses `netstat` for process resolution)
+
+## License
+
+MIT

package/bin/portprobe.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,227 @@
+// src/index.ts
+import { program } from "commander";
+
+// src/scanner/tcp.ts
+import net from "net";
+function checkTcp(port, timeout) {
+  return new Promise((resolve) => {
+    const start = performance.now();
+    const socket = new net.Socket();
+    socket.setTimeout(timeout);
+    socket.on("connect", () => {
+      const latency = Math.round(performance.now() - start);
+      socket.destroy();
+      resolve({ status: "up", latency });
+    });
+    socket.on("timeout", () => {
+      socket.destroy();
+      resolve({ status: "timeout", latency: null });
+    });
+    socket.on("error", (err) => {
+      socket.destroy();
+      if (err.code === "ECONNREFUSED") {
+        resolve({ status: "free", latency: null });
+      } else {
+        resolve({ status: "free", latency: null });
+      }
+    });
+    socket.connect(port, "127.0.0.1");
+  });
+}
+
+// src/scanner/process.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+async function resolveProcess(port) {
+  try {
+    if (process.platform === "win32") {
+      return resolveWindows(port);
+    }
+    return resolveUnix(port);
+  } catch {
+    return { pid: null, name: null };
+  }
+}
+async function resolveUnix(port) {
+  try {
+    const { stdout } = await execFileAsync("lsof", [
+      "-i",
+      `:${port}`,
+      "-sTCP:LISTEN",
+      "-P",
+      "-n",
+      "-Fp"
+    ]);
+    const pidLine = stdout.split("\n").find((l) => l.startsWith("p"));
+    if (!pidLine) return { pid: null, name: null };
+    const pid = parseInt(pidLine.slice(1), 10);
+    const name = await getProcessName(pid);
+    return { pid, name };
+  } catch {
+    return { pid: null, name: null };
+  }
+}
+async function resolveWindows(port) {
+  try {
+    const { stdout } = await execFileAsync("netstat", ["-ano"]);
+    const line = stdout.split("\n").find(
+      (l) => l.includes(`:${port}`) && l.includes("LISTENING")
+    );
+    if (!line) return { pid: null, name: null };
+    const parts = line.trim().split(/\s+/);
+    const pid = parseInt(parts[parts.length - 1], 10);
+    const name = await getProcessName(pid);
+    return { pid, name };
+  } catch {
+    return { pid: null, name: null };
+  }
+}
+async function getProcessName(pid) {
+  try {
+    if (process.platform === "win32") {
+      const { stdout: stdout2 } = await execFileAsync("tasklist", [
+        "/FI",
+        `PID eq ${pid}`,
+        "/FO",
+        "CSV",
+        "/NH"
+      ]);
+      const match = stdout2.match(/"([^"]+)"/);
+      return match ? match[1] : null;
+    }
+    const { stdout } = await execFileAsync("ps", ["-p", String(pid), "-o", "comm="]);
+    return stdout.trim().split("/").pop() || null;
+  } catch {
+    return null;
+  }
+}
+
+// src/health/http.ts
+import http from "http";
+function checkHttp(port, timeout) {
+  return new Promise((resolve) => {
+    const start = performance.now();
+    const req = http.get(
+      { hostname: "127.0.0.1", port, timeout, path: "/" },
+      (res) => {
+        const latency = Math.round(performance.now() - start);
+        res.resume();
+        resolve({ protocol: `HTTP ${res.statusCode}`, latency });
+      }
+    );
+    req.on("timeout", () => {
+      req.destroy();
+      resolve({ protocol: null, latency: null });
+    });
+    req.on("error", () => {
+      resolve({ protocol: null, latency: null });
+    });
+  });
+}
+
+// src/constants.ts
+var DEFAULT_PORTS = [
+  3e3,
+  3001,
+  4200,
+  5e3,
+  5173,
+  5432,
+  6379,
+  8e3,
+  8080,
+  8443,
+  9e3,
+  27017
+];
+var DEFAULT_TIMEOUT = 1e3;
+
+// src/scanner/index.ts
+async function scanPorts(options) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  const ports = resolvePorts(options);
+  const results = await Promise.all(
+    ports.map((port) => scanSinglePort(port, timeout))
+  );
+  return results;
+}
+function resolvePorts(options) {
+  if (options.ports && options.ports.length > 0) return options.ports;
+  if (options.range) {
+    const ports = [];
+    for (let p = options.range.from; p <= options.range.to; p++) {
+      ports.push(p);
+    }
+    return ports;
+  }
+  return [];
+}
+async function scanSinglePort(port, timeout) {
+  const tcp = await checkTcp(port, timeout);
+  if (tcp.status !== "up") {
+    return {
+      port,
+      status: tcp.status,
+      pid: null,
+      process: null,
+      latency: null,
+      protocol: null
+    };
+  }
+  const [proc, httpResult] = await Promise.all([
+    resolveProcess(port),
+    checkHttp(port, timeout)
+  ]);
+  return {
+    port,
+    status: "up",
+    pid: proc.pid,
+    process: proc.name,
+    latency: httpResult.latency ?? tcp.latency,
+    protocol: httpResult.protocol ?? "TCP"
+  };
+}
+
+// src/output/table.ts
+function formatTable(results) {
+  const header = " PORT  | PID     | PROCESS          | STATUS  | LATENCY | PROTO";
+  const sep = "-------|---------|------------------|---------|---------|--------";
+  const rows = results.map((r) => {
+    const port = String(r.port).padEnd(5);
+    const pid = r.pid ? String(r.pid).padEnd(7) : "-".padEnd(7);
+    const proc = (r.process ?? "-").padEnd(16);
+    const status = r.status === "up" ? "UP".padEnd(7) : "FREE".padEnd(7);
+    const latency = r.latency !== null ? `${r.latency}ms`.padEnd(7) : "-".padEnd(7);
+    const proto = r.protocol ?? "-";
+    return ` ${port} | ${pid} | ${proc} | ${status} | ${latency} | ${proto}`;
+  });
+  return [header, sep, ...rows].join("\n");
+}
+
+// src/output/json.ts
+function formatJson(results) {
+  return JSON.stringify({ ports: results }, null, 2);
+}
+
+// src/index.ts
+program.name("portprobe").description("Instant diagnostics for your local dev environment").version("0.1.0").argument("[port]", "specific port to check", parseInt).option("--json", "output as JSON (for AI agents)").option("--range <from-to>", "scan port range (e.g. 3000-9000)").option("--timeout <ms>", "connection timeout in ms", parseInt).action(async (port, options) => {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  let ports;
+  let range;
+  if (port) {
+    ports = [port];
+  } else if (options.range) {
+    const [from, to] = options.range.split("-").map(Number);
+    range = { from, to };
+  } else {
+    ports = DEFAULT_PORTS;
+  }
+  const results = await scanPorts({ ports, range, timeout });
+  if (options.json) {
+    console.log(formatJson(results));
+  } else {
+    console.log(formatTable(results));
+  }
+});
+program.parse();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "devprobe",
+  "version": "0.1.0",
+  "description": "Instant diagnostics for your local dev environment",
+  "type": "module",
+  "bin": {
+    "devprobe": "bin/portprobe.js"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "port",
+    "scanner",
+    "devtools",
+    "cli",
+    "diagnostics"
+  ],
+  "author": "blare",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bogdanblare/port.probe.git"
+  },
+  "homepage": "https://github.com/bogdanblare/port.probe#readme",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}