slash-port 0.1.0 → 0.2.1

package/README.md

@@ -1,5 +1,6 @@
 # slash-port
 
+<!-- release:badge -->[![github](https://img.shields.io/badge/github-v0.2.1-0f8b7d?logo=github&logoColor=white)](https://github.com/Slash-ui/slash-port/releases/tag/v0.2.1)<!-- /release:badge -->
 [![npm](https://img.shields.io/npm/v/slash-port?logo=npm&logoColor=white&color=0f8b7d)](https://www.npmjs.com/package/slash-port)
 [![downloads](https://img.shields.io/npm/dm/slash-port?color=0f8b7d)](https://www.npmjs.com/package/slash-port)
 [![CI](https://github.com/Slash-ui/slash-port/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Slash-ui/slash-port/actions/workflows/ci.yml)
@@ -43,22 +44,89 @@ npx slash-port
 
 Requires Node 22 or newer. Works on Linux, macOS, and Windows.
 
+### Updating
+
+The current release is
+<!-- release:version -->0.2.1<!-- /release:version -->. To see what you have,
+and what is published:
+
+```sh
+slash-port --version        # the one you are running
+npm view slash-port version # the one on npm
+```
+
+To move to the latest:
+
+```sh
+npm install -g slash-port@latest
+```
+
+`npm install -g …@latest` rather than `npm update -g slash-port`, because
+`update` will not cross a major version - and before 1.0.0 it will not cross a
+minor one either, which is every release this tool has had so far. Naming
+`@latest` always gets you the newest published version.
+
+`npx` caches the version it first downloaded, so ask it for the latest
+explicitly:
+
+```sh
+npx slash-port@latest
+```
+
+There is no automatic update check. `slash-port` makes no network connections
+at all, which means it will never tell you a new version exists - you find out
+here, or from npm. Upgrading is safe: there is no state, no configuration file,
+and nothing to migrate. To go the other way, name the version you want -
+`npm install -g slash-port@0.1.0` - and to remove it entirely:
+
+```sh
+npm uninstall -g slash-port
+```
+
+Breaking changes are listed under **Breaking changes** in the
+[changelog](CHANGELOG.md), so a major - or, before 1.0.0, a minor - is worth
+reading before you take it.
+
 ## Use
 
 ```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 +136,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 +149,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 |
@@ -95,15 +164,27 @@ cancels. The kill key is deliberately not next to a navigation key.
 
 ### Exit codes
 
+The same codes across every `slash-*` tool, so a script that wraps one can wrap
+any of them:
+
 | Code | Means |
 | --- | --- |
 | `0` | Success |
-| `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.
+| `1` | Invalid arguments or usage |
+| `2` | Nothing is listening on the ports asked about |
+| `3` | Refused: a confirmation was missing, or a guardrail tripped |
+| `4` | The operation was attempted and failed |
+
+Asking about a port is a question with a yes-or-no answer, so
+`slash-port --port 3000 --plain` exits `2` when nothing is listening there, and
+so does `--port 3xxx` when nothing matches. Listing every port exits `0` even
+when the list is empty.
+
+The distinction between `1` and `3` is whether the command made sense:
+`--kill` with no `--port` did not name a target and exits `1`, while `--kill`
+with a target but no `--yes` named one and did not confirm it, and exits `3`.
+The standard reserves `5` for an integrity failure, which this tool has nothing
+to verify and never returns.
 
 ## Safety
 
@@ -112,8 +193,15 @@ 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.
+- **A signal that will bounce is flagged before you decide, not after.** A row
+  owned by somebody else is marked `[locked]`, and the confirmation says what
+  it would take to signal it - rather than letting you confirm a kill that was
+  never going to land.
 - **Some processes are refused outright**, before any dialog is offered: the
-  init process, `sshd` — killing it locks you out of a remote machine — macOS
+  init process, `sshd` - killing it locks you out of a remote machine - macOS
   and Windows session processes, `slash-port` itself, and the shell that
   launched it.
 - **SIGTERM before SIGKILL.** A process that ignores SIGTERM is reported as
@@ -123,7 +211,7 @@ are fixed rather than configurable:
 
 On Windows there is no signal delivery: SIGTERM becomes `TerminateProcess`,
 which a process cannot catch or ignore, so nothing there gets the chance to
-shut down cleanly. The confirmation still applies — but "terminate" and "force"
+shut down cleanly. The confirmation still applies - but "terminate" and "force"
 do the same thing.
 
 ## Privacy
@@ -136,8 +224,9 @@ telemetry, no update check, and no configuration file.
 
 - Only the sixteen named terminal colours, so the display inherits your theme
   rather than fighting it.
-- Colour never carries meaning on its own — a protected row is labelled
-  `[protected]` as well as coloured.
+- Colour never carries meaning on its own - a protected row is labelled
+  `[protected]` and one you cannot signal is labelled `[locked]`, as well as
+  being coloured.
 - `NO_COLOR` and `--no-color` are honoured.
 - Redirected or piped output is plain text with no control codes, and the
   interactive interface never starts unless both streams are a terminal.
@@ -155,7 +244,7 @@ Three sources, in priority order:
 2. **The project.** The directory above `node_modules` in the command line, so
    two Vite servers on 5173 and 5174 can be told apart.
 3. **A well-known port registry**, used only when the process itself could not
-   be identified — mostly other users' processes. Entries that would add
+   be identified - mostly other users' processes. Entries that would add
    nothing are suppressed: "dev server" on port 3000 is not information.
 
 Per platform:
@@ -163,7 +252,7 @@ Per platform:
 - **Linux** reads `/proc/net/tcp` and maps socket inodes through
   `/proc/[pid]/fd`. No `lsof`, which many container images do not have, and no
   subprocess. Descriptors belonging to other users are not readable without
-  privileges, so those rows show no owner rather than failing the scan — run
+  privileges, so those rows show no owner rather than failing the scan - run
   with `sudo` to resolve them.
 - **macOS** uses `lsof` in field-output mode, plus `ps` for full command lines.
 - **Windows** uses `netstat -ano` and `tasklist`, which exist on every edition
@@ -181,7 +270,7 @@ oversights:
   `--tree` option would signal the whole group.
 - **Watch mode.** The list rescans on `r`, not on a timer.
 - **Port history.** "What was on 3000 an hour ago" needs persistent state, and
-  this tool currently has none — which is worth keeping.
+  this tool currently has none - which is worth keeping.
 
 ## Versioning and releases
 
@@ -193,6 +282,13 @@ and a patch. Every release is published with npm
 [provenance](https://docs.npmjs.com/generating-provenance-statements), so the
 tarball can be traced to the exact commit and workflow that built it.
 
+One commit does the whole bump: `package.json`, the changelog entry, and the
+version badge at the top of this file are written together, so the three cannot
+name different versions. The badges either side of it are read live - npm and
+the download count from the registry, CI and Release from the Actions API - so
+the `github` badge and the `npm` badge agreeing means the publish landed, and
+them disagreeing means it did not.
+
 See the [changelog](CHANGELOG.md) for what changed when.
 
 ## Contributing

package/dist/cli.js

@@ -3,13 +3,38 @@ 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. */
+/**
+ * The exit codes every slash-* tool shares, so a script that wraps one can
+ * wrap any of them:
+ *
+ *   0  success
+ *   1  invalid arguments or usage
+ *   2  the thing asked about was not found
+ *   3  refused - a confirmation was missing, or a guardrail tripped
+ *   4  the operation was attempted and failed
+ *
+ * The standard reserves 5 for an integrity failure, which this tool has
+ * nothing to verify and so never returns.
+ */
 const EXIT_OK = 0;
-const EXIT_FAILED = 1;
-const EXIT_USAGE = 2;
+const EXIT_USAGE = 1;
+const EXIT_NOT_FOUND = 2;
+const EXIT_REFUSED = 3;
+const EXIT_FAILED = 4;
+/**
+ * A command line that cannot be run. Most of these are malformed and exit 1,
+ * but a missing confirmation is a refusal rather than a mistake, so the code
+ * travels with the message.
+ */
 class UsageError extends Error {
+    code;
+    constructor(message, code = EXIT_USAGE) {
+        super(message);
+        this.code = code;
+    }
 }
 function parseArgs(argv) {
     const options = {
@@ -20,6 +45,7 @@ function parseArgs(argv) {
         kill: false,
         force: false,
         yes: false,
+        all: false,
         graceMs: 3000,
         color: true,
         help: false,
@@ -30,19 +56,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 +93,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 +117,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}`);
@@ -102,26 +132,40 @@ function parseArgs(argv) {
     if (options.kill) {
         if (options.port === null)
             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.');
+        if (!options.yes) {
+            throw new UsageError('--kill needs --yes, so the kill is confirmed.', EXIT_REFUSED);
+        }
+        // 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.`, EXIT_REFUSED);
+        }
     }
     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.
+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
@@ -134,8 +178,10 @@ Keys
 
 Exit codes
   0  success
-  1  the requested action could not be completed
-  2  invalid usage
+  1  invalid arguments or usage
+  2  nothing is listening on the ports asked about
+  3  refused: a confirmation was missing, or a guardrail tripped
+  4  the operation was attempted and failed
 
 slash-port never kills without confirmation; never kills init, sshd, your
 session, or the shell that launched it; sends SIGTERM before SIGKILL; and
@@ -150,16 +196,20 @@ 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`);
-        return EXIT_FAILED;
+        process.stderr.write(`Nothing is listening on ${describePortSelector(selector)}.\n`);
+        return EXIT_NOT_FOUND;
     }
+    let refusals = 0;
     let failures = 0;
     for (const target of targets) {
         const result = await killEntry(target, {
@@ -168,10 +218,20 @@ async function killFromCli(entries, options) {
         });
         const ok = result.status === 'terminated' || result.status === 'gone';
         (ok ? process.stdout : process.stderr).write(`${result.message}\n`);
-        if (!ok)
-            failures += 1;
+        if (!ok) {
+            if (result.status === 'refused')
+                refusals += 1;
+            else
+                failures += 1;
+        }
     }
-    return failures === 0 ? EXIT_OK : EXIT_FAILED;
+    // A guardrail that stopped a kill is a refusal; a signal that was sent and
+    // did not work is a failure, and outranks it when one command did both.
+    if (failures > 0)
+        return EXIT_FAILED;
+    if (refusals > 0)
+        return EXIT_REFUSED;
+    return EXIT_OK;
 }
 async function main(argv) {
     let options;
@@ -179,8 +239,13 @@ async function main(argv) {
         options = parseArgs(argv);
     }
     catch (error) {
-        process.stderr.write(`${error.message}\n\nRun slash-port --help for usage.\n`);
-        return EXIT_USAGE;
+        const code = error instanceof UsageError ? error.code : EXIT_USAGE;
+        process.stderr.write(`${error.message}\n`);
+        // A refusal names the flag that answers it, so the help pointer would be
+        // noise. A malformed command line is the case that needs pointing.
+        if (code === EXIT_USAGE)
+            process.stderr.write('\nRun slash-port --help for usage.\n');
+        return code;
     }
     if (options.help) {
         process.stdout.write(`${HELP}\n`);
@@ -220,12 +285,12 @@ async function main(argv) {
         else {
             process.stdout.write(`${plainTable(selected)}\n`);
         }
-        // Asking about one port is a question with a yes-or-no answer, so an empty
-        // result is a failure. Asking for the whole list is not.
-        return options.port !== null && selected.length === 0 ? EXIT_FAILED : EXIT_OK;
+        // Asking about a port is a question with a yes-or-no answer, so an empty
+        // result means not found. Asking for the whole list is not a question.
+        return options.port !== null && selected.length === 0 ? EXIT_NOT_FOUND : 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/describe.js

@@ -1,3 +1,4 @@
+import { userInfo } from 'node:os';
 import { basename } from 'node:path';
 export const SIGNATURES = [
     // Node frameworks and dev servers, ahead of the runtime that hosts them.
@@ -228,8 +229,14 @@ const PROTECTED_NAMES = {
     systemd: 'the init process',
     launchd: 'the init process',
     kernel_task: 'the kernel',
-    sshd: 'the SSH daemon — killing it locks you out of a remote machine',
+    sshd: 'the SSH daemon - killing it locks you out of a remote machine',
     'ssh-agent': 'the SSH agent',
+    'dbus-daemon': 'the D-Bus message bus - the desktop session is built on it',
+    // `/proc/[pid]/comm` is capped at fifteen characters, so the resolver
+    // arrives with its last letter missing. Both spellings are the same daemon.
+    'systemd-resolve': 'the systemd DNS resolver - killing it takes DNS down for everything',
+    'systemd-resolved': 'the systemd DNS resolver - killing it takes DNS down for everything',
+    'systemd-logind': 'the systemd login manager - killing it ends every session on the machine',
     loginwindow: 'the macOS session',
     windowserver: 'the macOS window server',
     systemuiserver: 'the macOS session',
@@ -241,7 +248,7 @@ const PROTECTED_NAMES = {
     services: 'the Windows service controller',
     lsass: 'the Windows security subsystem',
     smss: 'a Windows session process',
-    svchost: 'a Windows service host — it runs many unrelated services',
+    svchost: 'a Windows service host - it runs many unrelated services',
     system: 'the Windows kernel',
 };
 /**
@@ -262,3 +269,54 @@ export function guardReason(socket, context = { self: process.pid, parent: proce
         return PROTECTED_NAMES[name];
     return null;
 }
+function currentOwner() {
+    return {
+        uid: typeof process.getuid === 'function' ? process.getuid() : null,
+        // A uid with no passwd entry - a container running as a bare number -
+        // makes this throw rather than return anything useful.
+        user: (() => {
+            try {
+                return userInfo().username;
+            }
+            catch {
+                return null;
+            }
+        })(),
+        platform: process.platform,
+    };
+}
+/** Windows writes `MACHINE\amin`, and is not case sensitive about either half. */
+function sameUser(a, b, platform) {
+    if (platform !== 'win32')
+        return a === b;
+    const bare = (name) => (name.split('\\').pop() ?? name).toLowerCase();
+    return bare(a) === bare(b);
+}
+/**
+ * Why a signal to this process is expected to be refused, or `null` when it
+ * should land.
+ *
+ * The scan already knows who owns every socket, so this is settled while the
+ * list is built rather than discovered after a confirmation. That is the whole
+ * point: "sudo" is worth knowing before you decide, not after. Nothing here
+ * refuses anything - `killEntry` still asks the kernel, which is the only
+ * authority on the answer.
+ */
+export function elevationReason(socket, context = currentOwner()) {
+    // Root can signal anything.
+    if (context.uid === 0)
+        return null;
+    if (socket.pid === null) {
+        // Windows reports pid 0 for the idle process rather than hiding an owner,
+        // so an unresolved pid there is not a permission wall.
+        return context.platform === 'win32' ? null : 'its owner is not visible';
+    }
+    if (socket.user === null || context.user === null)
+        return null;
+    if (sameUser(socket.user, context.user, context.platform))
+        return null;
+    // The scanners fall back to the numeric uid when /etc/passwd has no name.
+    if (context.uid !== null && socket.user === String(context.uid))
+        return null;
+    return `it belongs to ${socket.user}`;
+}

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) {
@@ -15,15 +16,29 @@ export function formatProcess(entry) {
 export function formatAddresses(entry) {
     return entry.addresses.join(', ');
 }
-/** The description column: what it is, which project, and whether it is protected. */
+/**
+ * The description column: what it is, which project, and whether you can do
+ * anything about it. A guarded row is never also marked `[locked]` - it is
+ * refused whoever you are, so the extra badge would only add noise.
+ */
 export function formatDescription(entry) {
     const parts = [entry.label];
     if (entry.hint)
         parts.push(`(${entry.hint})`);
     if (entry.guard)
         parts.push('[protected]');
+    else if (entry.elevation)
+        parts.push('[locked]');
     return parts.join(' ');
 }
+/**
+ * What to do about a locked row. `sudo` is the answer almost everywhere and
+ * the wrong word on Windows, so the remedy is named per platform while the
+ * badge stays the same in every terminal.
+ */
+export function elevationRemedy(platform = process.platform) {
+    return platform === 'win32' ? 'an elevated terminal' : 'sudo';
+}
 /** Everything a row can be matched on, lowercased once for filtering. */
 export function searchText(entry) {
     return [
@@ -44,6 +59,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);
 }
 /**
@@ -83,5 +103,7 @@ export function toJson(entries) {
         project: entry.hint,
         protected: entry.guard !== null,
         protectedReason: entry.guard,
+        locked: entry.elevation !== null,
+        lockedReason: entry.elevation,
     }));
 }

package/dist/kill.js

@@ -1,4 +1,5 @@
 import { guardReason } from './describe.js';
+import { elevationRemedy } from './format.js';
 const defaultWait = (ms) => new Promise((resolve) => {
     setTimeout(resolve, ms);
 });
@@ -35,7 +36,7 @@ function describeTarget(entry) {
  * On Windows there is no signal delivery: SIGTERM becomes TerminateProcess,
  * which cannot be caught or ignored, so a process never gets the chance to
  * shut down cleanly and `survived` is unreachable. The grace period still
- * applies — it is how long the process is given to disappear.
+ * applies - it is how long the process is given to disappear.
  */
 export async function killEntry(entry, options = {}) {
     const { signal = 'SIGTERM', graceMs = 3000, pollMs = 50, kill = process.kill, wait = defaultWait } = options;
@@ -51,7 +52,7 @@ export async function killEntry(entry, options = {}) {
         return {
             status: 'unresolved',
             signal: null,
-            message: `Port ${entry.port} has an owner slash-port cannot see. Re-run with sudo to resolve it.`,
+            message: `Port ${entry.port} has an owner slash-port cannot see. Re-run with ${elevationRemedy()} to resolve it.`,
         };
     }
     const before = probe(entry.pid, kill);
@@ -66,7 +67,7 @@ export async function killEntry(entry, options = {}) {
         return {
             status: 'denied',
             signal: null,
-            message: `${describeTarget(entry)} belongs to another user. Re-run with sudo to signal it.`,
+            message: `${describeTarget(entry)} belongs to another user. Re-run with ${elevationRemedy()} to signal it.`,
         };
     }
     try {
@@ -85,7 +86,7 @@ export async function killEntry(entry, options = {}) {
             return {
                 status: 'denied',
                 signal: null,
-                message: `${describeTarget(entry)} belongs to another user. Re-run with sudo to signal it.`,
+                message: `${describeTarget(entry)} belongs to another user. Re-run with ${elevationRemedy()} to signal it.`,
             };
         }
         return {

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/dist/scan/index.js

@@ -1,4 +1,4 @@
-import { describe, guardReason } from '../describe.js';
+import { describe, elevationReason, guardReason } from '../describe.js';
 import { ScanError } from '../types.js';
 import { scanDarwin } from './darwin.js';
 import { scanLinux } from './linux.js';
@@ -51,6 +51,7 @@ export function collapse(sockets) {
             label: description.label,
             hint: description.hint,
             guard: guardReason(base),
+            elevation: elevationReason(base),
         });
     }
     return sortEntries(entries);

package/dist/scan/win32.js

@@ -18,7 +18,7 @@ export function parseNetstat(output) {
         if (protocol !== 'TCP' && protocol !== 'UDP')
             continue;
         // Localised builds translate the state word, so a TCP row also counts as
-        // listening when it has no peer — only LISTEN has a foreign port of zero.
+        // listening when it has no peer - only LISTEN has a foreign port of zero.
         if (protocol === 'TCP') {
             if (fields.length < 5)
                 continue;

package/dist/ui/App.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text, useApp, useInput, useStdout } from 'ink';
 import { useCallback, useEffect, useMemo, useState } from 'react';
-import { formatAddresses, formatDescription, formatPid, formatPort, formatProcess, formatUser, matchesFilter, } from '../format.js';
+import { elevationRemedy, formatAddresses, formatDescription, formatPid, formatPort, formatProcess, formatUser, matchesFilter, } from '../format.js';
 import { killEntry } from '../kill.js';
 import { scan } from '../scan/index.js';
 import { cell, color, layout, truncate } from './theme.js';
@@ -75,8 +75,8 @@ export function App({ initialEntries, initialFilter = '', udp: initialUdp = fals
     }, []);
     const visible = useMemo(() => entries.filter((entry) => matchesFilter(entry, filter)), [entries, filter]);
     const viewport = Math.max(3, rows - CHROME_ROWS);
-    // The list can shrink underneath the cursor — a filter keystroke, or a
-    // rescan after a kill — so the selection is clamped rather than left dangling.
+    // The list can shrink underneath the cursor - a filter keystroke, or a
+    // rescan after a kill - so the selection is clamped rather than left dangling.
     useEffect(() => {
         setSelected((current) => Math.min(current, Math.max(0, visible.length - 1)));
     }, [visible.length]);
@@ -199,7 +199,13 @@ export function App({ initialEntries, initialFilter = '', udp: initialUdp = fals
                             ? 'scanning…'
                             : `${visible.length}/${entries.length} ${udp ? 'tcp+udp' : 'tcp'}` })] }), _jsxs(Box, { children: [_jsxs(Text, { color: color('muted'), children: [header, " "] }), _jsx(Text, { color: color('muted'), children: cell('DESCRIPTION', columnLayout.description) })] }), window.map((entry, index) => {
                 const isSelected = offset + index === selected;
-                const rowColor = entry.guard ? color('warn') : entry.pid === null ? color('muted') : undefined;
+                // Muted means "you can look at this but not touch it": either the
+                // owner is somebody else, or there is no owner to signal at all.
+                const rowColor = entry.guard
+                    ? color('warn')
+                    : entry.elevation || entry.pid === null
+                        ? color('muted')
+                        : undefined;
                 const left = columnise({
                     port: formatPort(entry),
                     pid: formatPid(entry),
@@ -219,5 +225,5 @@ function ConfirmDialog({ entry, width }) {
     ]
         .filter(Boolean)
         .join(' · ');
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: color('warn'), paddingX: 1, children: [_jsx(Text, { color: color('warn'), bold: true, children: truncate(`Kill whatever holds port ${entry.port}/${entry.protocol}?`, inner) }), _jsx(Text, { children: truncate(formatDescription(entry), inner) }), _jsx(Text, { color: color('muted'), children: truncate(owner, inner) }), _jsx(Text, { children: " " }), _jsxs(Text, { children: [_jsx(Text, { color: color('ok'), children: "y" }), " terminate (SIGTERM) \u00B7", ' ', _jsx(Text, { color: color('danger'), children: "f" }), " force (SIGKILL) \u00B7 ", _jsx(Text, { color: color('heading'), children: "n" }), " cancel"] })] }));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: color('warn'), paddingX: 1, children: [_jsx(Text, { color: color('warn'), bold: true, children: truncate(`Kill whatever holds port ${entry.port}/${entry.protocol}?`, inner) }), _jsx(Text, { children: truncate(formatDescription(entry), inner) }), _jsx(Text, { color: color('muted'), children: truncate(owner, inner) }), entry.elevation && (_jsx(Text, { color: color('warn'), children: truncate(`Without ${elevationRemedy()} this will be refused: ${entry.elevation}.`, inner) })), _jsx(Text, { children: " " }), _jsxs(Text, { children: [_jsx(Text, { color: color('ok'), children: "y" }), " terminate (SIGTERM) \u00B7", ' ', _jsx(Text, { color: color('danger'), children: "f" }), " force (SIGKILL) \u00B7 ", _jsx(Text, { color: color('heading'), children: "n" }), " cancel"] })] }));
 }

package/dist/ui/theme.js

@@ -51,7 +51,7 @@ const TARGET_DESCRIPTION = 28;
  *
  * Columns are allocated by how much they carry. The port is never dropped,
  * the description is reserved next because it is the reason the tool exists,
- * and the rest compete for what is left — so an 80-column window keeps the
+ * and the rest compete for what is left - so an 80-column window keeps the
  * columns that matter and a 40-column one still reads.
  *
  * A zero width means the column is not shown at all.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slash-port",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "See what is listening on your ports, understand what it is, and kill it safely.",
   "keywords": [
     "port",
@@ -48,10 +48,10 @@
     "react": "^19.2.0"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
+    "@types/node": "^26.4.0",
     "@types/react": "^19.2.0",
     "ink-testing-library": "^4.0.0",
-    "typescript": "^5.9.0",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.0"
   }
 }