@tidyports/guard 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @tidyports/guard
+
+`EADDRINUSE` tells you a port is taken. It never tells you by what.
+
+Put this in front of your dev command and the error answers the actual question:
+
+```
+$ tidyports-guard npm run dev
+
+Error: listen EADDRINUSE: address already in use :::3000
+
+[tidyports] :3000 is held by Claude Code, in Ghostty [PID 12345] in acme-web (feature/auth)
+To take a different port:  PORT=$(tidy-ports alloc web)
+To stop it:                tidy-ports kill --match 3000
+```
+
+That last part matters most when an agent is reading it. An agent that hits a port
+conflict and can't tell it from a bug will often "fix" working code to get around the
+port — usually by editing your app's configuration. Naming the owner is what makes the
+conflict legible as a conflict.
+
+## Use it
+
+```bash
+npx @tidyports/guard npm run dev
+```
+
+Or wire it into the script you already run:
+
+```json
+{
+  "scripts": {
+    "dev": "tidyports-guard vite"
+  }
+}
+```
+
+It needs the [TidyPorts](https://tidyports.app) CLI on your `PATH` to name the owner.
+Without it you get a one-line note instead, and nothing else changes.
+
+## What it does to your dev loop
+
+Nothing, by design. It is a wrapper around a command you already run, so it is worth
+being precise about what it does not touch:
+
+- **stdout stays a TTY.** Only stderr is intercepted, and every chunk is written through
+  before it's even inspected — so your dev server keeps its colour and its interactive
+  keys.
+- **Exit codes and signals are reproduced exactly**, including the terminating signal, so
+  a shell, a CI step or an agent reading the status sees what it would have seen anyway.
+- **Ctrl-C still works.** `SIGINT`, `SIGTERM` and `SIGHUP` are forwarded to the child.
+- **Nothing is added on success.** The message appears only when a bind actually failed,
+  once, and never again for the same run.
+
+## What it understands
+
+The message is different in every ecosystem, so it matches the wording rather than the
+language:
+
+| | |
+|---|---|
+| Node | `listen EADDRINUSE: address already in use :::3000` |
+| Vite | `Port 5173 is in use` |
+| Flask / Python | `Address already in use` + `Port 5000 is in use` |
+| Rails / Puma | `bind(2) for "127.0.0.1" port 3000` |
+| Go | `listen tcp :8080: bind: address already in use` |
+| Docker | `Bind for 0.0.0.0:5432 failed: port is already allocated` |
+
+Lines that merely mention a port are deliberately ignored. A false positive would send
+you after the wrong process, which is worse than staying quiet.
+
+## Tests
+
+```bash
+npm test
+```
+
+Covers the patterns above — including the ones that must not match — and the wrapper's
+behaviour: exit codes, stderr passthrough, and a real bind failure.
+
+## Licence
+
+MIT

package/detect.js

@@ -0,0 +1,32 @@
+// Pulling a port number out of "the port is taken", in whichever dialect the
+// thing that failed happens to speak.
+//
+// Separate from guard.js so the table in test.mjs asserts against the patterns
+// that actually ship. A regex nobody tests is a regex that quietly stops
+// matching the day a framework rewords its error.
+
+/* Ordered most specific first, so a line carrying both an address and a port
+   cannot match the looser trailing patterns before the exact one. */
+export const PATTERNS = [
+  /EADDRINUSE[^\n]*?:(\d{2,5})\b/i, // node: ...address already in use :::3000
+  /bind\(2\) for [^\n]*?port (\d{2,5})/i, // puma / rails
+  /listen tcp [^\n]*?:(\d{2,5}):[^\n]*?address already in use/i, // go
+  /Bind for [^\n]*?:(\d{2,5}) failed: port is already allocated/i, // docker
+  /\bport (\d{2,5})\b[^\n]*?(?:is )?(?:already )?in use/i, // vite, flask
+  /address already in use[^\n]*?:(\d{2,5})\b/i, // generic, address last
+];
+
+// portFrom TEXT — the port as a string, or null when this isn't a bind failure.
+// Returning null generously is the point: adding nothing is always safe, and
+// guessing a port from an unrelated line would send someone after the wrong
+// process.
+export function portFrom(text) {
+  for (const re of PATTERNS) {
+    const m = text.match(re);
+    if (m) {
+      const port = Number(m[1]);
+      if (port > 0 && port < 65536) return String(port);
+    }
+  }
+  return null;
+}

package/guard.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// tidyports-guard — run your dev command through this, and when it can't bind,
+// the error says who is holding the port instead of just naming it.
+//
+//   tidyports-guard npm run dev
+//
+// Why a wrapper and not a plugin: "address already in use" is not a JavaScript
+// problem. Vite, Next, Rails, Flask, Puma and Go all report it differently and a
+// framework plugin would only ever cover one of them. Watching the child's
+// stderr for the message is ugly in the abstract and works everywhere in
+// practice, which is the right trade for a thing you only notice when it fires.
+//
+// Rules it holds to, because a wrapper around your dev loop has to be boring:
+//   - stdout stays inherited, so the child still sees a TTY and keeps its colour
+//     and its interactive keys. Only stderr is intercepted, and every chunk is
+//     written straight through before it is even looked at.
+//   - the child's exit code and terminating signal are reproduced exactly.
+//   - signals are forwarded, so ctrl-c still stops your dev server.
+//   - nothing is ever added on success, and it gives up quietly if the CLI is
+//     not installed.
+
+import { spawn, spawnSync } from "node:child_process";
+import { portFrom } from "./detect.js";
+
+const argv = process.argv.slice(2);
+
+if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+  process.stderr.write(
+    "usage: tidyports-guard <command> [args...]\n" +
+      "\n" +
+      "Runs the command and, if it fails to bind a port, names what is holding it.\n" +
+      "  tidyports-guard npm run dev\n" +
+      "  tidyports-guard flask run\n",
+  );
+  process.exit(argv.length === 0 ? 1 : 0);
+}
+
+/* TP_PORCELAIN is the CLI's own "no prompt, machine-readable" flag. Without it
+   `who` would offer an interactive choice — correct when a person runs it, wrong
+   here, where it would sit waiting for an answer underneath a dev server that
+   has already died. */
+function whoHolds(port) {
+  const res = spawnSync("tidy-ports", ["who", port], {
+    encoding: "utf8",
+    env: { ...process.env, TP_PORCELAIN: "1" },
+    timeout: 5000,
+  });
+  if (res.error || res.status === null) return null; // not installed, or hung
+  const out = (res.stdout || "").trim();
+  return out || null;
+}
+
+let reported = false;
+
+/* stderr arrives in whatever chunks the pipe hands over, and there is no promise
+   a line survives whole — a message split mid-sentence used to be missed
+   silently, which is the worst kind of miss, because short errors usually do
+   arrive intact and it looks like it works. So matching runs against a rolling
+   tail rather than a single chunk.
+
+   Bounded, because a dev server can log for hours: only the last few KB are
+   kept, which is far more than any one bind error, and the buffer is released
+   the moment there is nothing left to look for. The patterns never cross a
+   newline, so rejoining chunks cannot invent a match that wasn't there. */
+const TAIL_MAX = 8192;
+let tail = "";
+
+function explain(chunk) {
+  if (reported) return;
+  tail = (tail + chunk).slice(-TAIL_MAX);
+  const port = portFrom(tail);
+  if (!port) return;
+  reported = true;
+  tail = "";
+
+  const answer = whoHolds(port);
+  if (!answer) {
+    // No CLI, so there is nothing useful to add. Say so once, briefly, rather
+    // than leaving the reader wondering what this wrapper is even for.
+    process.stderr.write(
+      `\n[tidyports] :${port} is taken. Install TidyPorts to see what is holding it: https://tidyports.app\n`,
+    );
+    return;
+  }
+  process.stderr.write(`\n[tidyports] ${answer}\n`);
+}
+
+const child = spawn(argv[0], argv.slice(1), {
+  stdio: ["inherit", "inherit", "pipe"],
+  shell: false,
+});
+
+child.stderr.on("data", (buf) => {
+  process.stderr.write(buf); // through first, always, unaltered
+  explain(buf.toString());
+});
+
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => {
+    if (!child.killed) child.kill(sig);
+  });
+}
+
+child.on("error", (err) => {
+  const why = err.code === "ENOENT" ? `command not found: ${argv[0]}` : err.message;
+  process.stderr.write(`tidyports-guard: ${why}\n`);
+  process.exit(127);
+});
+
+child.on("close", (code, signal) => {
+  // Reproduce how the child ended, so this is invisible to anything upstream:
+  // a shell, a CI step, or an agent reading the exit status.
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@tidyports/guard",
+  "version": "0.1.0",
+  "description": "When a dev server can't bind, say who is holding the port instead of just EADDRINUSE.",
+  "type": "module",
+  "bin": {
+    "tidyports-guard": "guard.js"
+  },
+  "files": [
+    "guard.js",
+    "detect.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dan-fetch-studio/tidyports-integrations.git",
+    "directory": "guard"
+  },
+  "homepage": "https://tidyports.app",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "eaddrinuse",
+    "port",
+    "address-already-in-use",
+    "dev-server",
+    "localhost",
+    "ports"
+  ],
+  "scripts": {
+    "test": "node test.mjs"
+  }
+}