portdiag 0.0.0-stage → 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Thanks for considering a contribution. Portdiag is intentionally small: it diagnoses one TCP/IPv4 endpoint and never changes networking settings or stops processes. Please keep changes within that scope.
+
+## Before opening an issue
+
+Search existing issues first. For a bug, include the portdiag and Node.js versions, operating system, exact command, expected result, and actual result. Remove private addresses or other sensitive information from logs before posting.
+
+## Before opening a pull request
+
+Discuss larger behavior changes in an issue first. Keep pull requests focused, explain the user-visible reason for the change, and add or update tests for behavior changes.
+
+### Branch names
+
+Use a short type and kebab-case summary. CI rejects pull requests with an unstructured branch name. Fork contributors may prefix the type with their username:
+
+- `feat/json-output`
+- `fix/windows-listener-detection`
+- `docs/contributing-guide`
+- `test/cli-output`
+- `AnggaaIs/fix/windows-listener-detection`
+
+### Commit messages
+
+Every commit and pull request title must follow Conventional Commits. The check runs in CI and blocks merging when a message does not match.
+
+```text
+type(scope): lowercase summary
+```
+
+Allowed types are `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, and `revert`. Scope is optional. Keep the full first line to 72 characters or fewer. Use `!` before the colon for a breaking change.
+
+Good examples:
+
+```text
+feat(cli): add json output
+fix(windows): detect active listeners
+docs: clarify supported platforms
+```
+
+Messages such as `update stuff`, `fix: Fix bug`, or `misc changes` fail CI. Squash merge is the only merge method, and the PR title becomes the resulting commit message, so keep both commits and PR title in this format.
+
+Run these checks from the project directory:
+
+```sh
+npm test
+npm pack --dry-run
+```
+
+The Conventional Commit check can also be run by CI on pull requests. To check a title locally, use the same format and length rules above.
+
+There are no runtime dependencies. Please don't add one for work the Node.js standard library can handle, and don't publish a package release from a pull request.
+
+## Scope
+
+The project currently supports TCP over IPv4 on Windows, macOS, and Linux. It is read-only apart from the temporary TCP bind probe. Process termination, UDP, IPv6, scanning, and configuration systems are out of scope.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 portdiag contributors
+
+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

@@ -1,3 +1,104 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# portdiag: TCP Port Diagnostics for Node.js
+
+[![Tests](https://github.com/AnggaaIs/portdiag/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/AnggaaIs/portdiag/actions/workflows/test.yml)
+
+Ever started a Node.js dev server and got an `EADDRINUSE` or “port already in use” error? `portdiag` checks a specific local TCP/IPv4 port and tells you what it can find, without killing anything or changing your network settings. It works on Windows, macOS, and Linux.
+
+```console
+$ npx portdiag 3000
+portdiag
+● In use  127.0.0.1:3000
+
+Windows reports a listener on this endpoint.
+PID: 1234
+
+Next: Check the listening process before deciding whether to stop it.
+```
+
+## Try it
+
+Once published, run it without installing:
+
+```sh
+npx portdiag 3000
+npx portdiag 3000 --host 192.168.1.10
+npx portdiag 3000 --json
+```
+
+Or install it with `npm install --global portdiag` and use `portdiag` directly. The default address is `127.0.0.1`; `--host` takes an IPv4 address. Use `portdiag --help` for the full command list.
+
+The color in the terminal is just there to help status stand out. Piped output stays plain, and setting `NO_COLOR` disables color too.
+
+## What it checks
+
+Portdiag asks the operating system to bind a temporary TCP listener to the exact address and port you gave it, then closes that listener. On Windows, a successful bind by itself can be misleading: Windows may allow another socket to bind an endpoint that already has a listener. Portdiag checks `netstat` as well so it doesn’t report that endpoint as free. If `netstat` isn’t available, it says the result is unknown rather than guessing.
+
+When binding is denied on Windows, it also checks for an excluded TCP port range with `netsh`. A matching range may explain the problem, but it isn’t proof of the only cause. For an occupied port, portdiag may find a PID with `netstat` (Windows) or `lsof` (macOS/Linux). PID lookup is best effort; if the result is missing or ambiguous, it reports no PID.
+
+The result is only about the address checked. `127.0.0.1:3000` and `192.168.1.10:3000` are different endpoints. And “available” means the bind worked at that moment. Another process can still grab the port a moment later.
+
+### Reading the result
+
+- **Available:** the bind check succeeded for the address shown. Start your app soon; another process could still claim it first.
+- **In use:** a listener conflicts with that endpoint. A PID is shown only when the operating system identifies one reliably.
+- **Reserved:** Windows reports that the port falls in an excluded TCP range. That may explain the bind failure, but it is not proof of the only cause.
+- **Permission denied:** the operating system rejected the bind. Portdiag won’t assume that running as administrator is the right fix.
+- **Address unavailable:** the requested IPv4 address is not assigned to this machine.
+- **Unknown:** the available evidence wasn’t enough to identify the cause. Check the OS error shown in JSON output, if present.
+
+Portdiag supports Windows, macOS, and Linux, requires Node.js 22 or newer, and has no runtime dependencies. It checks TCP over IPv4 only; it does not inspect UDP or IPv6. It won’t stop processes, modify excluded ranges, scan other ports, ask for admin access, or send network requests.
+
+### Platform checks
+
+Portdiag checks for optional OS tools when it needs them; there’s no separate setup or `doctor` command.
+
+| Platform | Main check | If an OS tool is unavailable |
+| --- | --- | --- |
+| Windows | TCP bind probe, then `netstat` cross-check; `netsh` for excluded ranges | Without `netstat`, status is `unknown` if the bind succeeded but an existing listener couldn’t be ruled out. Without `netsh`, the bind diagnosis remains, but no excluded range is reported. |
+| macOS | TCP bind probe; `lsof` for a PID | The diagnosis still works; `pid` is `null`. |
+| Linux | TCP bind probe; `lsof` for a PID | The diagnosis still works; `pid` is `null`. |
+
+GitHub Actions is configured to run the test suite on Windows, macOS, and Linux. Actual results are available after the workflow runs for a pushed branch or pull request.
+
+## Use it from JavaScript
+
+```js
+import { diagnosePort } from 'portdiag';
+
+const result = await diagnosePort(3000);
+console.log(result.status, result.explanation);
+```
+
+`diagnosePort(port, options?)` accepts an integer port from `1` to `65535`. Set `options.host` to choose another IPv4 address. Invalid ports reject with `RangeError`; invalid addresses reject with `TypeError`.
+
+The returned object is JSON-serializable:
+
+```js
+{
+  port: 3000,
+  host: '127.0.0.1',
+  status: 'available', // available | in_use | reserved | permission_denied | address_unavailable | unknown
+  code: null,          // original OS bind error, or null
+  pid: null,           // best effort
+  range: null,         // { start, end } for a matching Windows range
+  explanation: '...',
+  suggestion: '...'
+}
+```
+
+The CLI exits with `0` when available, `1` when unavailable, `2` for invalid arguments, and `3` when it can’t complete the diagnosis.
+
+## Working on portdiag
+
+```sh
+npm test
+npm pack --dry-run
+```
+
+The test suite uses Node’s built-in test runner; GitHub Actions runs it on Windows, macOS, and Linux. Pull requests must use [Conventional Commits](CONTRIBUTING.md#commit-messages); CI checks every commit and the PR title. Bug and feature forms are in `.github/ISSUE_TEMPLATE/`. See [CONTRIBUTING.md](CONTRIBUTING.md) before sending a pull request and [SECURITY.md](SECURITY.md) to report a vulnerability privately. Before publishing, run both commands above, confirm the npm name is still available, and update the package version. Publish from an authenticated npm account with:
+
+```sh
+npm publish --access public
+```
+
+After that, `npx portdiag` will install and run the published CLI. The package is MIT licensed; see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security policy
+
+Please don't report security vulnerabilities in a public issue.
+
+Use GitHub's **Report a vulnerability** option in the repository's Security tab to send a private report to the maintainers. Include the affected version, steps to reproduce, and any relevant impact. Please don't include real secrets, credentials, or private network data in the report.
+
+If private vulnerability reporting is not enabled for the repository, contact the maintainers privately through the contact details on their GitHub profile. Please allow time for a response before sharing the issue publicly.
+
+Portdiag does not send telemetry or make network requests. It runs local operating-system inspection commands where available and briefly opens a TCP listener for the bind check.

package/bin/portdiag.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { diagnosePort } from '../src/index.js';
+
+const help = `Usage: portdiag <port> [--host <ipv4-address>] [--json]
+       portdiag --help
+       portdiag --version
+
+Checks whether a TCP/IPv4 endpoint can be bound. Default host: 127.0.0.1.`;
+
+function invalid(message) {
+  console.error(`Error: ${message}\n\n${help}`);
+  process.exitCode = 2;
+}
+
+const useColor = Boolean(process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== 'dumb');
+const paint = (text, code) => useColor ? `\u001B[${code}m${text}\u001B[0m` : text;
+
+function printResult(result) {
+  const display = {
+    available: ['✓ Available', '32'],
+    in_use: ['● In use', '31'],
+    reserved: ['● Reserved', '35'],
+    permission_denied: ['! Permission denied', '33'],
+    address_unavailable: ['! Address unavailable', '33'],
+    unknown: ['? Unknown', '90'],
+  }[result.status];
+
+  const endpoint = `${result.host}:${result.port}`;
+  const reason = {
+    available: 'The TCP bind check succeeded just now.',
+    in_use: result.code
+      ? 'The operating system reports this endpoint is already in use.'
+      : 'Windows reports a listener on this endpoint.',
+    reserved: 'A Windows excluded port range may explain the bind failure.',
+    permission_denied: 'The operating system denied the bind request.',
+    address_unavailable: 'This IPv4 address is not assigned to this machine.',
+    unknown: `Could not determine why the bind failed${result.code ? ` (${result.code})` : ''}.`,
+  }[result.status];
+
+  console.log(paint('portdiag', '1'));
+  console.log(`${paint(display[0], display[1])}  ${endpoint}`);
+  console.log(`\n${reason}`);
+  if (result.pid !== null) console.log(`PID: ${result.pid}`);
+  if (result.range) console.log(`Range: ${result.range.start}-${result.range.end}`);
+  console.log(`\nNext: ${result.suggestion}`);
+}
+
+const args = process.argv.slice(2);
+if (args.length === 1 && args[0] === '--help') {
+  console.log(help);
+} else if (args.length === 1 && args[0] === '--version') {
+  const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  console.log(pkg.version);
+} else {
+  let portText;
+  let host = '127.0.0.1';
+  let hostSeen = false;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--json') {
+      if (json) { invalid('duplicate --json flag'); break; }
+      json = true;
+    } else if (args[i] === '--host') {
+      if (hostSeen || !args[i + 1] || args[i + 1].startsWith('--')) { invalid('--host requires one IPv4 address'); break; }
+      hostSeen = true;
+      host = args[++i];
+    } else if (args[i].startsWith('--')) {
+      invalid(`unsupported flag: ${args[i]}`); break;
+    } else if (portText === undefined) {
+      portText = args[i];
+    } else {
+      invalid('provide exactly one port'); break;
+    }
+  }
+  if (!process.exitCode) {
+    if (portText === undefined || !/^\d+$/.test(portText)) invalid('port must be an integer from 1 through 65535');
+    else if (Number(portText) < 1 || Number(portText) > 65535) invalid('port must be an integer from 1 through 65535');
+    else {
+      try {
+        const result = await diagnosePort(Number(portText), { host });
+        if (json) console.log(JSON.stringify(result, null, 2));
+        else printResult(result);
+        process.exitCode = result.status === 'available' ? 0 : result.status === 'unknown' ? 3 : 1;
+      } catch (error) {
+        if (error instanceof TypeError || error instanceof RangeError) {
+          invalid(error.message);
+        } else {
+          console.error(`Diagnosis failed: ${error.message}`);
+          process.exitCode = 3;
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,46 @@
-{
-  "name": "portdiag",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "portdiag",
+  "version": "0.1.0",
+  "description": "Diagnose why a local TCP port cannot be bound",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnggaaIs/portdiag.git"
+  },
+  "homepage": "https://github.com/AnggaaIs/portdiag#readme",
+  "bugs": {
+    "url": "https://github.com/AnggaaIs/portdiag/issues"
+  },
+  "keywords": [
+    "port",
+    "tcp",
+    "diagnostic",
+    "port-diagnostics",
+    "port-checker",
+    "bind",
+    "windows",
+    "networking",
+    "developer-tools"
+  ],
+  "type": "module",
+  "bin": {
+    "portdiag": "bin/portdiag.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,107 @@
+import net from 'node:net';
+import { getExcludedRange } from './windows.js';
+import { findListeningPid, inspectWindowsListener } from './process.js';
+
+function validate(port, host) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new RangeError('port must be an integer from 1 through 65535');
+  }
+  if (typeof host !== 'string' || !net.isIPv4(host)) {
+    throw new TypeError('host must be a valid IPv4 address');
+  }
+}
+
+function probe(port, host) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', (error) => resolve({ error }));
+    server.listen({ port, host, exclusive: true }, () => {
+      server.close((error) => resolve({ error: error ?? null }));
+    });
+  });
+}
+
+/** @typedef {'available'|'in_use'|'reserved'|'permission_denied'|'address_unavailable'|'unknown'} PortStatus */
+
+/**
+ * @typedef {Object} PortDiagnosis
+ * @property {number} port The checked TCP port.
+ * @property {string} host The checked IPv4 address.
+ * @property {PortStatus} status Diagnosis status.
+ * @property {string|null} code Original operating-system bind error code, if binding failed.
+ * @property {number|null} pid Best-effort PID of a conflicting listener.
+ * @property {{start: number, end: number}|null} range Matching Windows excluded range, if found.
+ * @property {string} explanation Plain-language summary of the evidence.
+ * @property {string} suggestion A practical next step.
+ */
+
+/**
+ * Check whether a TCP/IPv4 endpoint can be bound right now.
+ *
+ * @param {number} port Integer from 1 through 65535.
+ * @param {{host?: string}} [options] Optional address; defaults to `127.0.0.1`.
+ * @returns {Promise<PortDiagnosis>} Serializable diagnosis result.
+ * @throws {RangeError} If `port` is outside the supported range or not an integer.
+ * @throws {TypeError} If `options.host` is not a valid IPv4 address.
+ */
+export async function diagnosePort(port, options = {}) {
+  const host = options.host ?? '127.0.0.1';
+  const platform = options.platform ?? process.platform;
+  validate(port, host);
+
+  const result = {
+    port, host, status: 'unknown', code: null, pid: null, range: null,
+    explanation: '', suggestion: '',
+  };
+  const outcome = await probe(port, host);
+  if (!outcome.error) {
+    if (platform === 'win32') {
+      const inspection = await inspectWindowsListener(port, host);
+      if (!inspection.inspected) {
+        result.explanation = `The bind probe succeeded for ${host}:${port}, but Windows listener inspection was unavailable, so existing use could not be ruled out.`;
+        result.suggestion = 'Retry when netstat is available to verify whether another process is listening.';
+        return result;
+      }
+      if (inspection.listener) {
+        result.status = 'in_use';
+        result.pid = inspection.listener.pid;
+        result.explanation = `Windows netstat reports a TCP listener that conflicts with ${host}:${port}.`;
+        result.suggestion = 'Check the listening process before deciding whether to stop it.';
+        return result;
+      }
+    }
+    result.status = 'available';
+    result.explanation = `TCP endpoint ${host}:${port} accepted a bind probe and was available at the time of checking.`;
+    result.suggestion = 'Start your app soon; another process could still claim the port.';
+    return result;
+  }
+
+  result.code = outcome.error.code ?? null;
+  if (result.code === 'EADDRINUSE') {
+    result.status = 'in_use';
+    result.explanation = `Another process or socket is already using ${host}:${port}.`;
+    result.suggestion = 'Check the listening process before deciding whether to stop it.';
+    result.pid = await findListeningPid(port, platform, undefined, host);
+  } else if (result.code === 'EACCES' || result.code === 'EPERM') {
+    result.status = 'permission_denied';
+    result.explanation = `The operating system denied binding to ${host}:${port}.`;
+    result.suggestion = 'Check local security policy and whether the port is reserved; do not change system settings without understanding the cause.';
+    if (platform === 'win32') {
+      result.range = await getExcludedRange(port);
+      if (result.range) {
+        result.status = 'reserved';
+        result.explanation = `Port ${port} falls in the Windows excluded TCP range ${result.range.start}-${result.range.end}; this may explain the bind denial.`;
+        result.suggestion = 'Choose a port outside this range.';
+      }
+    }
+  } else if (result.code === 'EADDRNOTAVAIL') {
+    result.status = 'address_unavailable';
+    result.explanation = `The local IPv4 address ${host} is not available on this machine.`;
+    result.suggestion = 'Choose an IPv4 address assigned to this machine.';
+  } else {
+    result.status = 'unknown';
+    result.explanation = `The bind probe failed${result.code ? ` with ${result.code}` : ''}; available evidence does not identify the cause.`;
+    result.suggestion = 'Check the operating-system error and retry the diagnosis.';
+  }
+  return result;
+}

package/src/process.js

@@ -0,0 +1,65 @@
+import { execFile } from 'node:child_process';
+import net from 'node:net';
+
+function run(file, args, execute = execFile) {
+  return new Promise((resolve) => {
+    try {
+      execute(file, args, {
+        shell: false, windowsHide: true, timeout: 3000, maxBuffer: 64 * 1024,
+      }, (error, stdout) => resolve(error ? null : stdout));
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+export function parseWindowsListener(output, port, host) {
+  const listeners = [];
+  for (const line of output.split(/\r?\n/)) {
+    const fields = line.trim().split(/\s+/);
+    if (fields.length < 5 || !/^TCP$/i.test(fields[0]) || !/^LISTENING$/i.test(fields[3])) continue;
+    const endpoint = fields[1].match(/^(.+):(\d+)$/);
+    if (!endpoint || Number(endpoint[2]) !== port) continue;
+    const address = endpoint[1];
+    if (!net.isIPv4(address)) continue;
+    const conflicts = host === '0.0.0.0'
+      ? true
+      : address === host || address === '0.0.0.0';
+    if (!conflicts) continue;
+    const value = Number(fields[4]);
+    listeners.push({ address, pid: Number.isSafeInteger(value) && value > 0 ? value : null });
+  }
+  if (listeners.length === 0) return null;
+  if (listeners.some(({ pid }) => pid === null)) return { pid: null };
+  const pids = new Set(listeners.map(({ pid }) => pid).filter((pid) => pid !== null));
+  return { pid: pids.size === 1 ? [...pids][0] : null };
+}
+
+export function parseLsofPid(output) {
+  const pids = new Set();
+  for (const value of output.trim().split(/\s+/)) {
+    if (!/^\d+$/.test(value)) continue;
+    const pid = Number(value);
+    if (Number.isSafeInteger(pid) && pid > 0) pids.add(pid);
+  }
+  return pids.size === 1 ? [...pids][0] : null;
+}
+
+export async function inspectWindowsListener(port, host, execute = execFile) {
+  const output = await run('netstat', ['-ano', '-p', 'tcp'], execute);
+  if (output === null) return { inspected: false, listener: null };
+  return { inspected: true, listener: parseWindowsListener(output, port, host) };
+}
+
+export async function findListeningPid(port, platform = process.platform, execute = execFile, host = '0.0.0.0') {
+  if (platform === 'win32') {
+    const { listener } = await inspectWindowsListener(port, host, execute);
+    return listener?.pid ?? null;
+  }
+  if (platform === 'linux' || platform === 'darwin') {
+    const output = await run('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'], execute);
+    if (output === null) return null;
+    return parseLsofPid(output);
+  }
+  return null;
+}

package/src/windows.js

@@ -0,0 +1,30 @@
+import { execFile } from 'node:child_process';
+
+export function parseExcludedRanges(output) {
+  const ranges = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.match(/^\s*(\d+)\s+(\d+)(?:\s+\*)?\s*$/);
+    if (!match) continue;
+    const start = Number(match[1]);
+    const count = Number(match[2]);
+    const end = start + count - 1;
+    if (start > 0 && count > 0 && end <= 65535) ranges.push({ start, end });
+  }
+  return ranges;
+}
+
+export function findExcludedRange(port, output) {
+  return parseExcludedRanges(output).find(({ start, end }) => port >= start && port <= end) ?? null;
+}
+
+export function getExcludedRange(port, execute = execFile) {
+  return new Promise((resolve) => {
+    try {
+      execute('netsh', ['interface', 'ipv4', 'show', 'excludedportrange', 'protocol=tcp'], {
+        shell: false, windowsHide: true, timeout: 3000, maxBuffer: 64 * 1024,
+      }, (error, stdout) => resolve(error ? null : findExcludedRange(port, stdout)));
+    } catch {
+      resolve(null);
+    }
+  });
+}