slash-port 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Slash UI Pte Ltd
+
+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

@@ -0,0 +1,209 @@
+# slash-port
+
+[![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)
+[![Release](https://github.com/Slash-ui/slash-port/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/Slash-ui/slash-port/actions/workflows/release.yml)
+[![node](https://img.shields.io/node/v/slash-port?color=5a6a78)](https://nodejs.org)
+[![licence](https://img.shields.io/npm/l/slash-port?color=5a6a78)](LICENSE)
+[![Conventional Commits](https://img.shields.io/badge/commits-conventional-0f8b7d)](https://www.conventionalcommits.org)
+
+See what is listening on your ports, understand what it is, and kill it safely.
+
+**[slash-ui.github.io/slash-port](https://slash-ui.github.io/slash-port/)**
+
+`EADDRINUSE: address already in use :::3000` tells you a port is taken. It does
+not tell you what took it, which project it belongs to, or whether killing it is
+a good idea. `slash-port` answers all three, then kills the process for you
+after a confirmation that names it.
+
+```
+slash-port                                                               6/6 tcp
+PORT        PID     USER       PROCESS            DESCRIPTION
+3000/tcp    41822   amin       node               Next.js (shop)
+5173/tcp    41905   amin       node               Vite dev server (admin)
+5432/tcp    612     postgres   postgres           PostgreSQL
+6379/tcp    788     redis      redis-server       Redis
+8080/tcp    39044   amin       docker-proxy       Docker published port
+22/tcp      1       root       sshd               OpenSSH server [protected]
+↑↓/jk move · PgUp/PgDn/g/G jump · / filter · x kill · r rescan · u udp · q quit
+```
+
+## Install
+
+```sh
+npm install -g slash-port
+```
+
+Or run it once, without installing:
+
+```sh
+npx slash-port
+```
+
+Requires Node 22 or newer. Works on Linux, macOS, and Windows.
+
+## Use
+
+```sh
+slash-port              # the interactive list
+slash-port 3000         # open on port 3000
+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
+```
+
+To kill something from a script, name it and confirm it:
+
+```sh
+slash-port --kill --port 3000 --yes
+```
+
+There is no flag combination that kills something without naming it first.
+
+### Keys
+
+| Key | Does |
+| --- | --- |
+| `↑` `↓` or `j` `k` | Move |
+| `PgUp` `PgDn` | Page |
+| `g` `G` | First, last |
+| `/` | Filter; `Enter` keeps it, `Esc` clears it |
+| `x` or `Enter` | Kill the selected port |
+| `r` | Rescan |
+| `u` | Show UDP as well as TCP |
+| `q` | Quit |
+
+In the confirmation dialog: `y` sends SIGTERM, `f` forces with SIGKILL, `n`
+cancels. The kill key is deliberately not next to a navigation key.
+
+### Options
+
+| Option | Does |
+| --- | --- |
+| `-p`, `--port <number>` | Only this port |
+| `-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 |
+| `--grace <ms>` | Wait this long for a graceful exit (default 3000) |
+| `--no-color` | Disable colour. `NO_COLOR` is honoured too |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show the version |
+
+### Exit codes
+
+| 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.
+
+## Safety
+
+Killing the wrong process at a terminal is easy and unrecoverable, so the rules
+are fixed rather than configurable:
+
+- **Nothing is killed without a confirmation that names it.** Not in the
+  interactive list, and not with flags.
+- **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
+  launched it.
+- **SIGTERM before SIGKILL.** A process that ignores SIGTERM is reported as
+  having survived. Escalating is a second, deliberate action, never automatic.
+- **A process that has already exited is never signalled**, because by then its
+  pid may belong to something else.
+
+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"
+do the same thing.
+
+## Privacy
+
+`slash-port` makes no network connections at any point. It reads the local
+socket table and the local process table, and that is all it does. There is no
+telemetry, no update check, and no configuration file.
+
+## Terminal behaviour
+
+- 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.
+- `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.
+- The list is windowed to the visible rows, so a machine with four hundred
+  listening sockets renders a screenful, not four hundred lines.
+- Columns are dropped in order of how little they carry as the window narrows,
+  and values that are cut are marked with an ellipsis.
+
+## How it identifies a process
+
+Three sources, in priority order:
+
+1. **The command line.** Specific frameworks are matched before the runtimes
+   that host them, so `node …/vite` reports Vite rather than Node.js.
+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
+   nothing are suppressed: "dev server" on port 3000 is not information.
+
+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
+  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
+  and avoid PowerShell's startup cost.
+
+## Not built yet
+
+Deliberate omissions, listed so you know they are choices rather than
+oversights:
+
+- **Docker awareness.** A published port shows `docker-proxy` rather than the
+  container behind it. Resolving that means talking to the Docker socket, which
+  is a real dependency and belongs behind a flag.
+- **Process trees.** Killing a dev server sometimes leaves children behind. A
+  `--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.
+
+## Versioning and releases
+
+Versions follow [Semantic Versioning](https://semver.org) and are chosen by the
+pipeline rather than by hand: every commit on `main` is a
+[Conventional Commit](https://www.conventionalcommits.org), and the release
+workflow reads the types since the last tag to decide between a major, a minor,
+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.
+
+See the [changelog](CHANGELOG.md) for what changed when.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The one step that is a requirement
+rather than a suggestion is enabling the repository's git hooks:
+
+```sh
+git config core.hooksPath .githooks
+```
+
+## Licence
+
+MIT © Amin Shariati

package/dist/cli.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+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 { scan } from './scan/index.js';
+import { ScanError } from './types.js';
+/** 0 success · 1 the action could not be completed · 2 invalid usage. */
+const EXIT_OK = 0;
+const EXIT_FAILED = 1;
+const EXIT_USAGE = 2;
+class UsageError extends Error {
+}
+function parseArgs(argv) {
+    const options = {
+        port: null,
+        udp: false,
+        json: false,
+        plain: false,
+        kill: false,
+        force: false,
+        yes: false,
+        graceMs: 3000,
+        color: true,
+        help: false,
+        version: false,
+    };
+    const value = (flag, next) => {
+        if (next === undefined || next.startsWith('-'))
+            throw new UsageError(`${flag} needs a value.`);
+        return next;
+    };
+    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;
+                break;
+            }
+            case '-u':
+            case '--udp':
+                options.udp = true;
+                break;
+            case '--json':
+                options.json = true;
+                break;
+            case '--plain':
+                options.plain = true;
+                break;
+            case '--kill':
+                options.kill = true;
+                break;
+            case '--force':
+                options.force = true;
+                break;
+            case '-y':
+            case '--yes':
+                options.yes = true;
+                break;
+            case '--grace': {
+                const raw = value(argument, argv[++index]);
+                const ms = Number.parseInt(raw, 10);
+                if (!Number.isInteger(ms) || ms < 0)
+                    throw new UsageError(`${raw} is not a number of milliseconds.`);
+                options.graceMs = ms;
+                break;
+            }
+            case '--no-color':
+            case '--no-colour':
+                options.color = false;
+                break;
+            case '-h':
+            case '--help':
+                options.help = true;
+                break;
+            case '-v':
+            case '--version':
+                options.version = true;
+                break;
+            default:
+                if (/^\d+$/.test(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;
+                    break;
+                }
+                throw new UsageError(`Unknown option: ${argument}`);
+        }
+    }
+    if (options.json && options.plain)
+        throw new UsageError('--json and --plain cannot both be used.');
+    // The one rule that matters: nothing is ever killed without being named and
+    // confirmed, and no flag combination gets round it.
+    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.force && !options.kill)
+        throw new UsageError('--force 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]
+
+Options
+  -p, --port <number>  Only this port
+  -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
+      --grace <ms>     Wait this long for a graceful exit (default 3000)
+      --no-color       Disable colour
+  -h, --help           Show this help
+  -v, --version        Show the version
+
+Keys
+  up/down or j/k  move          /  filter      x or Enter  kill
+  PgUp/PgDn       page          r  rescan      u           toggle UDP
+  g / G           first / last  q  quit        y/f/n       confirm dialog
+
+Exit codes
+  0  success
+  1  the requested action could not be completed
+  2  invalid usage
+
+slash-port never kills without confirmation; never kills init, sshd, your
+session, or the shell that launched it; sends SIGTERM before SIGKILL; and
+never touches the network.`;
+function readVersion() {
+    try {
+        const manifest = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+        return JSON.parse(manifest).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function selectPort(entries, options) {
+    if (options.port === null)
+        return [...entries];
+    return entries.filter((entry) => entry.port === options.port && (options.udp || entry.protocol === 'tcp'));
+}
+async function killFromCli(entries, options) {
+    const targets = selectPort(entries, options);
+    if (targets.length === 0) {
+        process.stderr.write(`Nothing is listening on port ${options.port}.\n`);
+        return EXIT_FAILED;
+    }
+    let failures = 0;
+    for (const target of targets) {
+        const result = await killEntry(target, {
+            signal: options.force ? 'SIGKILL' : 'SIGTERM',
+            graceMs: options.graceMs,
+        });
+        const ok = result.status === 'terminated' || result.status === 'gone';
+        (ok ? process.stdout : process.stderr).write(`${result.message}\n`);
+        if (!ok)
+            failures += 1;
+    }
+    return failures === 0 ? EXIT_OK : EXIT_FAILED;
+}
+async function main(argv) {
+    let options;
+    try {
+        options = parseArgs(argv);
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n\nRun slash-port --help for usage.\n`);
+        return EXIT_USAGE;
+    }
+    if (options.help) {
+        process.stdout.write(`${HELP}\n`);
+        return EXIT_OK;
+    }
+    if (options.version) {
+        process.stdout.write(`${readVersion()}\n`);
+        return EXIT_OK;
+    }
+    // Set before Ink or chalk is loaded, because both decide colour support at
+    // import time. This is why the UI is imported lazily further down.
+    if (!options.color)
+        process.env['NO_COLOR'] = '1';
+    let entries;
+    try {
+        entries = await scan({ udp: options.udp });
+    }
+    catch (error) {
+        if (error instanceof ScanError) {
+            process.stderr.write(`${error.message}\n`);
+            if (error.hint)
+                process.stderr.write(`${error.hint}\n`);
+            return EXIT_FAILED;
+        }
+        throw error;
+    }
+    if (options.kill)
+        return killFromCli(entries, options);
+    // A pipe or a redirect gets plain text, never control codes, and the TUI is
+    // never started when either stream is not a terminal.
+    const interactive = !options.json && !options.plain && Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY);
+    if (!interactive) {
+        const selected = selectPort(entries, options);
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(toJson(selected), null, 2)}\n`);
+        }
+        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;
+    }
+    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 }));
+    await instance.waitUntilExit();
+    return EXIT_OK;
+}
+main(process.argv.slice(2)).then((code) => {
+    // Set rather than exit, so piped stdout is flushed before the process ends.
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = EXIT_FAILED;
+});