slash-port 0.1.0 → 0.2.0

package/README.md

@@ -48,17 +48,41 @@ Requires Node 22 or newer. Works on Linux, macOS, and Windows.
 ```sh
 slash-port              # the interactive list
 slash-port 3000         # open on port 3000
+slash-port 3xxx         # every port from 3000 to 3999
+slash-port 3000:3005    # every port in that range
 slash-port --plain      # a plain table, for a pipe or a script
 slash-port --json       # the same data as JSON
 slash-port --udp        # include UDP as well as TCP
 ```
 
+### Naming ports
+
+`--port` and the interactive filter take the same three forms:
+
+| Form | Means |
+| --- | --- |
+| `3000` | One port |
+| `3xxx` | Every port from 3000 to 3999. `x` is any digit, in any position: `8x80` is 8080, 8180, and so on to 8980 |
+| `3000:3005` | Every port from 3000 to 3005, both ends included |
+
+A pattern is read as digits, not as a number, so `3xxx` is the four-digit ports
+beginning with 3 and does not include 300. Ports above 65535 do not exist, so a
+pattern that can only match them — `7xxxx` — is a usage error rather than an
+empty list.
+
 To kill something from a script, name it and confirm it:
 
 ```sh
 slash-port --kill --port 3000 --yes
 ```
 
+A pattern or a range can match several ports, and the same command matches more
+of them tomorrow than it does today, so killing with one takes `--all` as well:
+
+```sh
+slash-port --kill --port 3000:3005 --yes --all
+```
+
 There is no flag combination that kills something without naming it first.
 
 ### Keys
@@ -68,7 +92,7 @@ There is no flag combination that kills something without naming it first.
 | `↑` `↓` or `j` `k` | Move |
 | `PgUp` `PgDn` | Page |
 | `g` `G` | First, last |
-| `/` | Filter; `Enter` keeps it, `Esc` clears it |
+| `/` | Filter on anything in the row, or on ports with `3xxx` and `3000:3005`; `Enter` keeps it, `Esc` clears it |
 | `x` or `Enter` | Kill the selected port |
 | `r` | Rescan |
 | `u` | Show UDP as well as TCP |
@@ -81,13 +105,14 @@ cancels. The kill key is deliberately not next to a navigation key.
 
 | Option | Does |
 | --- | --- |
-| `-p`, `--port <number>` | Only this port |
+| `-p`, `--port <ports>` | Only these ports: `3000`, `3xxx`, or `3000:3005` |
 | `-u`, `--udp` | Include UDP sockets |
 | `--json` | Print JSON and exit |
 | `--plain` | Print a plain table and exit |
 | `--kill` | Kill the process on `--port`. Requires `--yes` |
 | `--force` | Escalate to SIGKILL instead of SIGTERM |
 | `-y`, `--yes` | Confirm a kill made from the command line |
+| `--all` | Kill every port a pattern or a range matches. Requires `--kill` |
 | `--grace <ms>` | Wait this long for a graceful exit (default 3000) |
 | `--no-color` | Disable colour. `NO_COLOR` is honoured too |
 | `-h`, `--help` | Show help |
@@ -101,9 +126,10 @@ cancels. The kill key is deliberately not next to a navigation key.
 | `1` | The requested action could not be completed |
 | `2` | Invalid usage |
 
-Asking about one port is a question with a yes-or-no answer, so
-`slash-port --port 3000 --plain` exits `1` when nothing is listening there.
-Listing every port exits `0` even when the list is empty.
+Asking about a port is a question with a yes-or-no answer, so
+`slash-port --port 3000 --plain` exits `1` when nothing is listening there, and
+so does `--port 3xxx` when nothing matches. Listing every port exits `0` even
+when the list is empty.
 
 ## Safety
 
@@ -112,6 +138,9 @@ are fixed rather than configurable:
 
 - **Nothing is killed without a confirmation that names it.** Not in the
   interactive list, and not with flags.
+- **A pattern or a range never kills on its own.** `--kill --port 3xxx --yes`
+  is refused without `--all`, because what a pattern matches depends on what
+  happens to be running when the command is run.
 - **Some processes are refused outright**, before any dialog is offered: the
   init process, `sshd` — killing it locks you out of a remote machine — macOS
   and Windows session processes, `slash-port` itself, and the shell that

package/dist/cli.js

@@ -3,6 +3,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { readFileSync } from 'node:fs';
 import { plainTable, toJson } from './format.js';
 import { killEntry } from './kill.js';
+import { describePortSelector, looksLikePort, matchesPort, parsePortSelector } from './ports.js';
 import { scan } from './scan/index.js';
 import { ScanError } from './types.js';
 /** 0 success · 1 the action could not be completed · 2 invalid usage. */
@@ -20,6 +21,7 @@ function parseArgs(argv) {
         kill: false,
         force: false,
         yes: false,
+        all: false,
         graceMs: 3000,
         color: true,
         help: false,
@@ -30,19 +32,23 @@ function parseArgs(argv) {
             throw new UsageError(`${flag} needs a value.`);
         return next;
     };
+    // A bad port is a usage error like any other, so it exits 2 with the same
+    // shape of message rather than as an unhandled failure.
+    const selector = (raw) => {
+        try {
+            return parsePortSelector(raw);
+        }
+        catch (error) {
+            throw new UsageError(error.message);
+        }
+    };
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         switch (argument) {
             case '-p':
-            case '--port': {
-                const raw = value(argument, argv[++index]);
-                const port = Number.parseInt(raw, 10);
-                if (!Number.isInteger(port) || port < 1 || port > 65535) {
-                    throw new UsageError(`${raw} is not a port number between 1 and 65535.`);
-                }
-                options.port = port;
+            case '--port':
+                options.port = selector(value(argument, argv[++index]));
                 break;
-            }
             case '-u':
             case '--udp':
                 options.udp = true;
@@ -63,6 +69,9 @@ function parseArgs(argv) {
             case '--yes':
                 options.yes = true;
                 break;
+            case '--all':
+                options.all = true;
+                break;
             case '--grace': {
                 const raw = value(argument, argv[++index]);
                 const ms = Number.parseInt(raw, 10);
@@ -84,12 +93,9 @@ function parseArgs(argv) {
                 options.version = true;
                 break;
             default:
-                if (/^\d+$/.test(argument) && options.port === null) {
+                if (looksLikePort(argument) && options.port === null) {
                     // `slash-port 3000` is what everyone tries first.
-                    const port = Number.parseInt(argument, 10);
-                    if (port < 1 || port > 65535)
-                        throw new UsageError(`${argument} is not a port number.`);
-                    options.port = port;
+                    options.port = selector(argument);
                     break;
                 }
                 throw new UsageError(`Unknown option: ${argument}`);
@@ -104,24 +110,37 @@ function parseArgs(argv) {
             throw new UsageError('--kill needs --port, so the target is named.');
         if (!options.yes)
             throw new UsageError('--kill needs --yes, so the kill is confirmed.');
+        // Whether a pattern happens to match one port today is not the point: the
+        // same command matches more tomorrow, so the plural is confirmed up front.
+        if (options.port.kind !== 'exact' && !options.all) {
+            throw new UsageError(`--kill needs --all to use ${options.port.text}, so killing every match is deliberate.`);
+        }
     }
     if (options.force && !options.kill)
         throw new UsageError('--force only means something with --kill.');
+    if (options.all && !options.kill)
+        throw new UsageError('--all only means something with --kill.');
     return options;
 }
 const HELP = `slash-port — see what is listening on your ports, and kill it safely.
 
 Usage
-  slash-port [port] [options]
+  slash-port [ports] [options]
+
+Ports
+  3000                 one port
+  3xxx                 every port from 3000 to 3999; x is any digit
+  3000:3005            every port in the range, both ends included
 
 Options
-  -p, --port <number>  Only this port
+  -p, --port <ports>   Only these ports, in any of the forms above
   -u, --udp            Include UDP sockets as well as TCP
       --json           Print JSON to stdout and exit
       --plain          Print a plain table and exit
       --kill           Kill the process on --port. Requires --yes
       --force          Escalate to SIGKILL instead of SIGTERM
   -y, --yes            Confirm a kill made from the command line
+      --all            Kill every port a pattern or a range matches
       --grace <ms>     Wait this long for a graceful exit (default 3000)
       --no-color       Disable colour
   -h, --help           Show this help
@@ -150,14 +169,17 @@ function readVersion() {
     }
 }
 function selectPort(entries, options) {
-    if (options.port === null)
+    const selector = options.port;
+    if (selector === null)
         return [...entries];
-    return entries.filter((entry) => entry.port === options.port && (options.udp || entry.protocol === 'tcp'));
+    return entries.filter((entry) => matchesPort(selector, entry.port) && (options.udp || entry.protocol === 'tcp'));
 }
 async function killFromCli(entries, options) {
+    // parseArgs refuses --kill without --port, so there is always a selector here.
+    const selector = options.port;
     const targets = selectPort(entries, options);
     if (targets.length === 0) {
-        process.stderr.write(`Nothing is listening on port ${options.port}.\n`);
+        process.stderr.write(`Nothing is listening on ${describePortSelector(selector)}.\n`);
         return EXIT_FAILED;
     }
     let failures = 0;
@@ -225,7 +247,7 @@ async function main(argv) {
         return options.port !== null && selected.length === 0 ? EXIT_FAILED : EXIT_OK;
     }
     const [{ render }, { App }] = await Promise.all([import('ink'), import('./ui/App.js')]);
-    const instance = render(_jsx(App, { initialEntries: entries, initialFilter: options.port === null ? '' : String(options.port), udp: options.udp }));
+    const instance = render(_jsx(App, { initialEntries: entries, initialFilter: options.port === null ? '' : options.port.text, udp: options.udp }));
     await instance.waitUntilExit();
     return EXIT_OK;
 }

package/dist/format.js

@@ -1,3 +1,4 @@
+import { matchesPort, tryPortSelector } from './ports.js';
 /** Shown wherever a value is genuinely absent, rather than an empty column. */
 export const ABSENT = '-';
 export function formatPort(entry) {
@@ -44,6 +45,11 @@ export function matchesFilter(entry, filter) {
     const needle = filter.trim().toLowerCase();
     if (!needle)
         return true;
+    // `3xxx` and `3000:3005` can mean nothing but ports, so they are matched as
+    // ports. A bare `3000` stays a substring, because it is also half a pid.
+    const selector = tryPortSelector(needle);
+    if (selector)
+        return matchesPort(selector, entry.port);
     return searchText(entry).includes(needle);
 }
 /**

package/dist/ports.js

@@ -0,0 +1,113 @@
+/**
+ * The three ways to name ports, shared by `--port` and the filter box: one
+ * port, a pattern where `x` stands for any digit, or an inclusive range.
+ */
+const MIN_PORT = 1;
+const MAX_PORT = 65535;
+/** A selector that could not be read. The message is written for the user. */
+export class PortSelectorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PortSelectorError';
+    }
+}
+function exact(port) {
+    return { kind: 'exact', text: String(port), from: port, to: port, pattern: null };
+}
+function portNumber(raw) {
+    const port = /^\d{1,5}$/.test(raw) ? Number.parseInt(raw, 10) : Number.NaN;
+    if (!(port >= MIN_PORT && port <= MAX_PORT)) {
+        throw new PortSelectorError(`${raw} is not a port number between 1 and 65535.`);
+    }
+    return port;
+}
+/**
+ * `3xxx` is every four-digit port beginning with 3, so a pattern is matched
+ * against the port's digits rather than its value: `xxx` is 100 to 999, not 0
+ * to 999. The bounds come from replacing every `x` with 0 and with 9 — a
+ * leading `x` with 1, because no port is written with a leading zero.
+ */
+function parsePattern(text) {
+    if (!/^[\dx]+$/.test(text)) {
+        throw new PortSelectorError(`${text} is not a port pattern. Write it as 3xxx, where x is any digit.`);
+    }
+    const from = Number.parseInt(text.replace(/^x/, '1').replace(/x/g, '0'), 10);
+    const to = Number.parseInt(text.replace(/x/g, '9'), 10);
+    if (from < MIN_PORT || from > MAX_PORT) {
+        throw new PortSelectorError(`No port between 1 and 65535 matches ${text}.`);
+    }
+    return { kind: 'pattern', text, from, to: Math.min(to, MAX_PORT), pattern: text };
+}
+function parseRange(text) {
+    const halves = text.split(':');
+    if (halves.length !== 2 || halves[0] === '' || halves[1] === '') {
+        throw new PortSelectorError(`${text} is not a port range. Write it as 3000:3005.`);
+    }
+    const from = portNumber(halves[0]);
+    const to = portNumber(halves[1]);
+    if (from > to) {
+        throw new PortSelectorError(`The range ${text} runs backwards. Write it as ${to}:${from}.`);
+    }
+    // A range of one port is that port, and is treated as one everywhere after.
+    if (from === to)
+        return exact(from);
+    return { kind: 'range', text: `${from}:${to}`, from, to, pattern: null };
+}
+/** Reads `3000`, `3xxx`, or `3000:3005`. Throws a `PortSelectorError` otherwise. */
+export function parsePortSelector(raw) {
+    const text = raw.trim().toLowerCase();
+    if (text.includes(':'))
+        return parseRange(text);
+    if (text.includes('x'))
+        return parsePattern(text);
+    if (!/^\d+$/.test(text)) {
+        throw new PortSelectorError(`${raw} is not a port, a pattern like 3xxx, or a range like 3000:3005.`);
+    }
+    return exact(portNumber(text));
+}
+export function matchesPort(selector, port) {
+    if (port < selector.from || port > selector.to)
+        return false;
+    if (selector.pattern === null)
+        return true;
+    const digits = String(port);
+    if (digits.length !== selector.pattern.length)
+        return false;
+    return [...selector.pattern].every((character, index) => character === 'x' || character === digits[index]);
+}
+/** How a selector is named in a message, e.g. "Nothing is listening on …". */
+export function describePortSelector(selector) {
+    switch (selector.kind) {
+        case 'exact':
+            return `port ${selector.from}`;
+        case 'pattern':
+            return `ports matching ${selector.text}`;
+        default:
+            return `ports ${selector.from} to ${selector.to}`;
+    }
+}
+/**
+ * Whether a bare argument was meant as a port, so `slash-port 3xxx` works like
+ * `slash-port 3000` and a typo in one is reported as a bad port rather than as
+ * an unknown option.
+ */
+export function looksLikePort(raw) {
+    return /^\d/.test(raw) || /^x[\dx]*$/i.test(raw);
+}
+/**
+ * The filter box reads `3xxx` and `3000:3005` as ports, and everything else —
+ * including a bare `3000` — as a substring, because the filter still has to
+ * find pids, users, and project names. Half-typed input is not an error there,
+ * so an unreadable selector is simply not one.
+ */
+export function tryPortSelector(raw) {
+    const text = raw.trim().toLowerCase();
+    if (!/^\d*x[\dx]*$/.test(text) && !/^\d+:\d+$/.test(text))
+        return null;
+    try {
+        return parsePortSelector(text);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slash-port",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "See what is listening on your ports, understand what it is, and kill it safely.",
   "keywords": [
     "port",