devprobe 0.1.0 → 0.2.0

package/README.md

@@ -1,126 +1,106 @@
-# portprobe
+# devprobe
 
-Instant port diagnostics for your local dev environment.
+**Instant diagnostics for your local dev environment.** One command — see every listening port, which process owns it, and whether it responds.
 
-## 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:
+[![npm](https://img.shields.io/npm/v/devprobe)](https://www.npmjs.com/package/devprobe)
+[![license](https://img.shields.io/npm/l/devprobe)](LICENSE)
 
-```bash
-npx portprobe
-```
-
-Or install globally:
+---
 
 ```bash
-npm i -g portprobe
+$ npx devprobe
+
+ PORT  | PID   | PROCESS          | STATUS | LATENCY | PROTO
+-------|-------|------------------|--------|---------|--------
+ 3000  | 12841 | node             | UP     | 2ms     | HTTP 200
+ 5432  | 1023  | postgres         | UP     | 1ms     | TCP
+ 5500  | 9912  | node             | UP     | 1ms     | HTTP 200
+ 6379  | 1087  | redis-server     | UP     | <1ms    | TCP
+ 8080  | 5523  | java             | UP     | 12ms    | HTTP 200
+ 24282 | 3301  | python           | UP     | 3ms     | HTTP 404
 ```
 
-## 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
-```
+No config. No port lists to maintain. It asks the OS directly what's listening.
 
-### Single port check
-
-Check whether a specific port is in use:
-
-```bash
-portprobe 3000
-```
+## Why
 
-### Range scan
+- `EADDRINUSE` — what's using port 3000? Now you know instantly
+- **AI agents** (Claude Code, Cursor, etc.) waste tokens running `lsof`, parsing output, retrying — `devprobe --json` gives them structured data in one call
+- **Zero guesswork** — shows ALL listening ports, not just a predefined list
 
-Scan a custom range of ports:
+## Install
 
 ```bash
-portprobe --range 3000-9000
+npx devprobe            # run without installing
+npm i -g devprobe       # or install globally
 ```
 
-### Custom timeout
-
-Set the TCP connection timeout in milliseconds (default: 1000):
+## Usage
 
 ```bash
-portprobe --timeout 2000
+devprobe                # show all listening ports
+devprobe 3000           # check specific port
+devprobe --range 3000-9000   # scan a range
+devprobe --json         # JSON output (for scripts & AI agents)
+devprobe --timeout 2000 # custom timeout in ms
 ```
 
-## Flags
+### 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`) | — |
+| `--range <from-to>` | Scan a port range | — |
 | `--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
-```
+## For AI Agents
 
-Returns an array of results:
+`devprobe --json` returns structured data that any AI coding agent can parse:
 
 ```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
-  }
-]
+{
+  "ports": [
+    {
+      "port": 3000,
+      "status": "up",
+      "pid": 12841,
+      "process": "node",
+      "latency": 2,
+      "protocol": "HTTP 200"
+    }
+  ]
+}
 ```
 
-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.
+Add to your project's `CLAUDE.md` or agent config:
+```
+Use `devprobe --json` to diagnose port conflicts instead of lsof/netstat.
+```
 
 ## 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)
+- **macOS** — full support (`lsof`)
+- **Linux** — full support (`lsof`)
+- **Windows** — best-effort (`netstat`)
+
+## Roadmap
+
+- [ ] `--watch` — realtime monitoring
+- [ ] `--wait <port>` — wait until port is available
+- [ ] `--diagnose` — problem analysis + recommendations
+- [ ] Auto-detect service type (PostgreSQL, Redis, MySQL, etc.)
+- [ ] Docker container awareness
+
+## Support the project
+
+If devprobe saved you time, consider:
+
+- Star this repo — it helps others find it
+- [Sponsor on GitHub](https://github.com/sponsors/bogdanblare) — support development directly
+- Share with your team — the more users, the better it gets
 
 ## License
 

package/dist/index.js

@@ -33,6 +33,65 @@ function checkTcp(port, timeout) {
 import { execFile } from "child_process";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
+async function discoverListeningPorts() {
+  try {
+    if (process.platform === "win32") {
+      return discoverWindows();
+    }
+    return discoverUnix();
+  } catch {
+    return [];
+  }
+}
+async function discoverUnix() {
+  const { stdout } = await execFileAsync("lsof", [
+    "-iTCP",
+    "-sTCP:LISTEN",
+    "-P",
+    "-n",
+    "-Fpn"
+  ]);
+  const results = [];
+  let currentPid = null;
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("p")) {
+      currentPid = parseInt(line.slice(1), 10);
+    } else if (line.startsWith("n") && currentPid !== null) {
+      const match = line.match(/:(\d+)$/);
+      if (match) {
+        const port = parseInt(match[1], 10);
+        const name = await getProcessName(currentPid);
+        results.push({ port, pid: currentPid, name });
+      }
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return results.filter((r) => {
+    if (seen.has(r.port)) return false;
+    seen.add(r.port);
+    return true;
+  });
+}
+async function discoverWindows() {
+  const { stdout } = await execFileAsync("netstat", ["-ano"]);
+  const results = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const line of stdout.split("\n")) {
+    if (!line.includes("LISTENING")) continue;
+    const parts = line.trim().split(/\s+/);
+    const addrPart = parts[1];
+    if (!addrPart) continue;
+    const match = addrPart.match(/:(\d+)$/);
+    if (!match) continue;
+    const port = parseInt(match[1], 10);
+    if (seen.has(port)) continue;
+    seen.add(port);
+    const pid = parseInt(parts[parts.length - 1], 10);
+    const name = await getProcessName(pid);
+    results.push({ port, pid, name });
+  }
+  return results;
+}
 async function resolveProcess(port) {
   try {
     if (process.platform === "win32") {
@@ -121,30 +180,30 @@ function checkHttp(port, timeout) {
 }
 
 // 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);
+  if (options.ports && options.ports.length > 0 || options.range) {
+    const ports = resolvePorts(options);
+    return Promise.all(ports.map((port) => scanSinglePort(port, timeout)));
+  }
+  const listening = await discoverListeningPorts();
   const results = await Promise.all(
-    ports.map((port) => scanSinglePort(port, timeout))
+    listening.map(async (entry) => {
+      const httpResult = await checkHttp(entry.port, timeout);
+      return {
+        port: entry.port,
+        status: "up",
+        pid: entry.pid,
+        process: entry.name,
+        latency: httpResult.latency,
+        protocol: httpResult.protocol ?? "TCP"
+      };
+    })
   );
-  return results;
+  return results.sort((a, b) => a.port - b.port);
 }
 function resolvePorts(options) {
   if (options.ports && options.ports.length > 0) return options.ports;
@@ -205,7 +264,7 @@ function formatJson(results) {
 }
 
 // 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) => {
+program.name("devprobe").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;
@@ -214,8 +273,6 @@ program.name("portprobe").description("Instant diagnostics for your local dev en
   } 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devprobe",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Instant diagnostics for your local dev environment",
   "type": "module",
   "bin": {
@@ -31,9 +31,9 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bogdanblare/port.probe.git"
+    "url": "git+https://github.com/bogdanblare/devprobe.git"
   },
-  "homepage": "https://github.com/bogdanblare/port.probe#readme",
+  "homepage": "https://github.com/bogdanblare/devprobe#readme",
   "dependencies": {
     "chalk": "^5.6.2",
     "commander": "^14.0.3"