slash-port 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,16 @@
+<p align="center">
+  <a href="https://github.com/Slash-ui">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-slashui-dark.svg" />
+      <img src="docs/assets/logo-slashui-light.svg" alt="Slash UI" width="159" height="65" />
+    </picture>
+  </a>
+</p>
+
 # 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 -->
+<!-- release:badge -->
+[![github](https://img.shields.io/badge/github-v0.4.0-0f8b7d?logo=github&logoColor=white)](https://github.com/Slash-ui/slash-port/releases/tag/v0.4.0)<!-- /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)
@@ -19,15 +29,60 @@ 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
+slash-port                                                    8/8 tcp · beginner
+PORT        WHAT IT IS                       OPEN AT                 CLOSE IT?
+22/tcp      OpenSSH server [protected]       -                       No
+3000/tcp    Next.js (shop)                   http://localhost:3000   Yes
+5173/tcp    Vite dev server (admin)          http://localhost:5173   Yes
+5432/tcp    Docker Desktop                   -                       Probably
+6379/tcp    Redis                            -                       Probably
+8025/tcp    Docker Desktop                   http://localhost:8025   Probably
+49470/tcp   Visual Studio Code (Node.js)     -                       Probably
+51061/tcp   macOS Handoff                    -                       Better not
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ Port 3000 · Next.js (shop) - a web server                                    │
+│ Point a browser at it - that is what it is there for.                        │
+│ Project    shop                                                              │
+│ Open       http://localhost:3000                                             │
+│ Started by you (slashui) · node · pid 41822                                  │
+│ Close it   Yes - yours, and as easy to start again as it was to start        │
+│ Afterwards Start it again with your dev command, usually `npm run dev`.      │
+╰──────────────────────────────────────────────────────────────────────────────╯
+↑↓ move · / find · x close it · r refresh · u udp · d details · m advanced · q …
+```
+
+Every row says something the process name does not. The process behind
+`Visual Studio Code` is called `Code Helper`, and the one behind `macOS
+Handoff` is called `rapportd`. Neither name would have told you anything, which
+is the point: when nothing at all can be worked out, the column says `-` rather
+than repeating the process name back at you.
+
+Press `m` for advanced mode, which trades the explanations for the facts that
+tell two identical-looking dev servers apart:
+
+```
+slash-port                                                                        8/8 tcp · advanced
+PORT        PID     USER       PROCESS            ADDRESS           DESCRIPTION
+22/tcp      947     root       sshd               *                 OpenSSH server [protected]
+3000/tcp    41822   slashui    node               *                 Next.js (shop)
+5173/tcp    41905   slashui    node               *                 Vite dev server (admin)
+5432/tcp    39044   slashui    com.docker.backend *                 Docker Desktop
+6379/tcp    788     slashui    redis-server       127.0.0.1         Redis
+8025/tcp    39044   slashui    com.docker.backend *                 Docker Desktop
+49470/tcp   1737    slashui    Code Helper        127.0.0.1         Visual Studio Code (Node.js)
+51061/tcp   694     slashui    rapportd           *                 macOS Handoff
+╭──────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ Process   node · pid 41822 · parent 1204 zsh                                                     │
+│ User      slashui                                                                                │
+│ Listening * · TCP · IPv4                                                                         │
+│ Clients   3 connections open                                                                     │
+│ Running   2h 11m (since 14:02)                                                                   │
+│ Memory    431 MB · 0.4% CPU                                                                      │
+│ Directory /Users/slashui/code/shop                                                               │
+│ Command   node /Users/slashui/code/shop/node_modules/.bin/next dev                               │
+│ Kill      Yes - yours, and as easy to start again as it was to start. Start it again with your … │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
+↑↓/jk move · PgUp/PgDn/g/G jump · / filter · x kill · r rescan · u udp · d detail · m beginner · q …
 ```
 
 ## Install
@@ -46,9 +101,8 @@ 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:
+The current release is <!-- release:version -->0.4.0<!-- /release:version -->. To
+see what you have, and what is published:
 
 ```sh
 slash-port --version        # the one you are running
@@ -90,15 +144,90 @@ reading before you take it.
 ## Use
 
 ```sh
-slash-port              # the interactive list
+slash-port              # the interactive list, in beginner mode
+slash-port --advanced   # the same list, with the full detail
 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
+slash-port --docker     # name the container behind a published port
 ```
 
+### Beginner and advanced
+
+There are two modes, and **beginner is the default**. The person who does not
+know what took port 3000 is the person who went looking for a tool that would
+tell them; anyone who already knows can say `--advanced` once, or set
+`SLASH_PORT_MODE=advanced` and never say it again. `m` switches between them
+at any time, and `d` hides the panel in either.
+
+| | Beginner | Advanced |
+| --- | --- | --- |
+| Columns | Port, what it is, where to open it, whether to close it | Port, pid, user, process, address, description |
+| Narrow terminals | Keeps the verdict down to forty-two columns; the URL column stands down first, and stands down entirely when no row has one | Drops address, user, process, pid, in that order |
+| Panel | What kind of thing it is, which project, who started it, whether closing it is a good idea, and how to start it again | Parent process, open connections, uptime, memory, working directory, full command line, and how the description was arrived at |
+| Confirmation | Says what closing it costs and how to undo it | Names the signal |
+| Cost | One scan | One scan, plus a lookup for the row under the cursor |
+
+Both modes on a working machine, where the list is forty-two ports long
+rather than the tidy eight above:
+
+![Beginner mode on a real machine: mailpit and adminer in Docker, five
+http.server processes on 8001 to 8005, Ollama, Figma, Visual Studio Code and
+macOS Handoff, each with where to open it and whether closing it is a good
+idea, and a panel explaining that port 8001 is a web server and safe to
+close](docs/assets/screenshot-beginner.png)
+
+![The same machine in advanced mode: pid, user, process and address for every
+row, and a panel with the parent process, open connections, uptime, memory,
+working directory and the full command
+line](docs/assets/screenshot-advanced.png)
+
+Advanced mode's extra facts are fetched for the selected row only. A machine
+with four hundred listening sockets would otherwise pay four hundred times over
+for facts you are reading one row at a time.
+
+### Docker
+
+A published container port shows as `Docker Desktop`, which is true and no help
+at all - and the beginner panel says so rather than leaving you to wonder where
+the name went:
+
+```
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ Port 5432 · Docker Desktop - a container port                                │
+│ Publishing a port on behalf of a container.                                  │
+│ Container  not looked up - re-run with --docker to name it                   │
+│ Started by you (slashui) · com.docker.backend · pid 39044                    │
+│ Close it   Probably - yours, but something may be relying on it              │
+│ Afterwards Stopping the container that owns the port is the change you prob… │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+`--docker` asks the local engine which container is behind the port. The image
+is read the same way a command line is, so `postgres:16` reports PostgreSQL and
+is treated with the care a database deserves, and the compose project becomes
+the hint - which is how two Supabase stacks on 5432 and 54322 stop being
+interchangeable:
+
+```
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ Port 5432 · PostgreSQL in Docker (shop) - a database                         │
+│ The container shop-db, from the shop compose project, running postgres:16-a… │
+│ Container  shop                                                              │
+│ Started by you (slashui) · com.docker.backend · pid 39044                    │
+│ Close it   Probably - stop the container instead: `docker stop shop-db`      │
+│ Afterwards Bring it back with `docker compose up -d db`.                     │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+It stays off until you ask for it. Reading two local tables and stopping is the
+property this tool is built around, and a nicer default is not worth trading it
+for. `SLASH_PORT_DOCKER=1` turns it on for good if you would rather not type
+it, and `--no-docker` overrules that for one run.
+
 ### Naming ports
 
 `--port` and the interactive filter take the same three forms:
@@ -140,6 +269,8 @@ There is no flag combination that kills something without naming it first.
 | `x` or `Enter` | Kill the selected port |
 | `r` | Rescan |
 | `u` | Show UDP as well as TCP |
+| `m` | Switch between beginner and advanced |
+| `d` | Show or hide the detail panel |
 | `q` | Quit |
 
 In the confirmation dialog: `y` sends SIGTERM, `f` forces with SIGKILL, `n`
@@ -150,7 +281,11 @@ cancels. The kill key is deliberately not next to a navigation key.
 | Option | Does |
 | --- | --- |
 | `-p`, `--port <ports>` | Only these ports: `3000`, `3xxx`, or `3000:3005` |
+| `--beginner` | Explain each port in plain language. The default |
+| `--advanced` | Show the full detail instead of the explanations |
+| `--mode <name>` | `beginner` or `advanced`. `SLASH_PORT_MODE` sets the default |
 | `-u`, `--udp` | Include UDP sockets |
+| `--docker` | Ask the local Docker socket which container holds a port. Off by default; `SLASH_PORT_DOCKER=1` sets the default |
 | `--json` | Print JSON and exit |
 | `--plain` | Print a plain table and exit |
 | `--kill` | Kill the process on `--port`. Requires `--yes` |
@@ -162,6 +297,19 @@ cancels. The kill key is deliberately not next to a navigation key.
 | `-h`, `--help` | Show help |
 | `-v`, `--version` | Show the version |
 
+### Output for scripts
+
+`--json` is the stable machine surface. Fields are added over time and never
+repurposed, so a `jq` expression written against an old version keeps working.
+`description` is `null` rather than a copy of `process` when nothing could be
+identified, which is the one thing worth knowing before parsing it: absence is
+reported as absence.
+
+`--plain` keeps the same six columns in both modes and always will, so anything
+already splitting that output keeps working. A mode only ever appends a column
+on the end - what closing it would mean in beginner mode, the full command line
+in advanced.
+
 ### Exit codes
 
 The same codes across every `slash-*` tool, so a script that wraps one can wrap
@@ -204,11 +352,28 @@ are fixed rather than configurable:
   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.
+- **Whether closing it is a good idea is settled before you decide.** Every row
+  carries a verdict - `Yes`, `Probably`, `Better not`, `No`, `Needs sudo` -
+  worked out from what it is, who owns it, and whether a guardrail already
+  refuses it. The verdict is a word in a column, never a colour alone.
+- **The confirmation is never the thing that gets truncated.** On a terminal
+  too short to show it and the list behind it, the list gives way; a question
+  you cannot read is a question you cannot answer.
 - **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.
 
+The confirmation for a row that is safe to close names the process, says what
+closing it costs, and keeps the polite close and the forced one on separate
+keys:
+
+![The confirmation over the list: Close whatever is using port 8002, the
+process named as Python http.server, pid 11575, user slashui, the verdict that
+it is yours and as easy to start again as it was to start, and the keys y to
+close it politely, f to force it, n to leave it
+alone](docs/assets/screenshot-close.png)
+
 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"
@@ -216,9 +381,17 @@ 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.
+`slash-port` makes no network connections at any point. By default it reads
+the local socket table and the local process table, and asks nothing else on
+the machine anything either. There is no telemetry, no update check, and no
+configuration file.
+
+`--docker` is the single exception, and it is off until you ask for it. It
+reads the local Docker socket - a file on this machine, the same as
+`/proc/net/tcp` is - to name the container behind a published port. A
+`DOCKER_HOST` pointing at another machine over TCP is ignored rather than
+connected to. `SLASH_PORT_DOCKER=1` turns it on for good if you would rather
+not type it; `--no-docker` still overrules that for one run.
 
 ## Terminal behaviour
 
@@ -233,19 +406,50 @@ telemetry, no update check, and no configuration file.
 - 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.
+  and values that are cut are marked with an ellipsis. Beginner mode keeps all
+  four of its columns down to eighty, because the fourth is the answer.
+- A column that has nothing to show stands down rather than printing a column
+  of dashes: `OPEN AT` appears when the rows on screen have URLs.
 
 ## How it identifies a process
 
-Three sources, in priority order:
+The description column exists to say something the process column did not. So
+the first rule is that it never repeats the process name: when nothing could be
+worked out, it says `-`, because "slash-port has no idea" is a fact and
+`figma_agent` beside `figma_agent` is a column doing nothing.
+
+What it consults, 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.
+2. **The container**, if you passed `--docker`. The local engine is asked which
+   container publishes the port, and the image is then read like a command
+   line, so `postgres:16` reports "PostgreSQL in Docker" and is treated with
+   the care a database deserves. The compose project - or the container name
+   when there is no project - becomes the hint, which is how `5432` and `54322`
+   stop being interchangeable. Without the flag a published port reports
+   `Docker Desktop`, and beginner mode says so rather than leaving you to
+   wonder why the name is missing.
+3. **The application.** The bundle or install directory the binary sits in,
+   so `Code Helper` reports Visual Studio Code and `figma_agent` reports Figma.
+   The outermost bundle wins, and a vendor directory beats the bundle inside it.
+4. **The project.** The directory above `node_modules` in the command line, so
+   two Vite servers on 5173 and 5174 can be told apart. A directory that only
+   names a convention - `lib`, `src`, `bin` - is passed over for the script
+   itself, which is why `…/google-cloud-sdk/lib/gcloud.py` reads as `gcloud`.
+5. **A well-known port registry**, for processes that could not be identified
+   at all - mostly other users'. Generic entries are demoted rather than
+   suppressed: "dev server" loses to anything specific, and beats saying
+   nothing.
+6. **The shape of the path.** A binary under `/usr/libexec` is a system service
+   whoever wrote it, which is worth more than its own name repeated back.
+
+Beginner mode adds one more question on top of all that: whether closing it is
+a good idea. That answer folds together what kind of thing it is, whether you
+own it, and whether a guardrail already refuses it - and the last two win,
+because they are facts about this machine rather than guesses about software. A
+Postgres you do not own is `Needs sudo` whatever anyone thinks of closing
+databases.
 
 Per platform:
 
@@ -258,14 +462,22 @@ Per platform:
 - **Windows** uses `netstat -ano` and `tasklist`, which exist on every edition
   and avoid PowerShell's startup cost.
 
+Advanced mode's per-row lookups follow the same rule of asking the cheapest
+thing that can answer: `/proc` on Linux with no subprocess at all, `ps` and
+`lsof` on macOS, and on Windows only what `tasklist` and `netstat` already
+know. Parents, working directories, and start times need WMI or PowerShell
+there, which cost about a second each, so those lines are left out rather than
+paid for. A platform that cannot answer omits the line; it never guesses.
+
 ## 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.
+- **Docker awareness by default.** `--docker` names the container behind a
+  published port, and it stays opt-in. Reading two local tables and stopping is
+  the property this tool is built around, and it is not worth trading for a
+  nicer default.
 - **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.

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 { isMode, resolveDocker, resolveMode } from './mode.js';
 import { describePortSelector, looksLikePort, matchesPort, parsePortSelector } from './ports.js';
 import { scan } from './scan/index.js';
 import { ScanError } from './types.js';
@@ -39,7 +40,9 @@ class UsageError extends Error {
 function parseArgs(argv) {
     const options = {
         port: null,
+        mode: null,
         udp: false,
+        docker: null,
         json: false,
         plain: false,
         kill: false,
@@ -73,10 +76,29 @@ function parseArgs(argv) {
             case '--port':
                 options.port = selector(value(argument, argv[++index]));
                 break;
+            case '--beginner':
+                options.mode = 'beginner';
+                break;
+            case '--advanced':
+                options.mode = 'advanced';
+                break;
+            case '--mode': {
+                const raw = value(argument, argv[++index]).toLowerCase();
+                if (!isMode(raw))
+                    throw new UsageError(`${raw} is not a mode. Use beginner or advanced.`);
+                options.mode = raw;
+                break;
+            }
             case '-u':
             case '--udp':
                 options.udp = true;
                 break;
+            case '--docker':
+                options.docker = true;
+                break;
+            case '--no-docker':
+                options.docker = false;
+                break;
             case '--json':
                 options.json = true;
                 break;
@@ -159,7 +181,11 @@ Ports
 
 Options
   -p, --port <ports>   Only these ports, in any of the forms above
+      --beginner       Explain each port in plain language (the default)
+      --advanced       Show the full detail instead of the explanations
+      --mode <name>    beginner or advanced. SLASH_PORT_MODE sets the default
   -u, --udp            Include UDP sockets as well as TCP
+      --docker         Ask the local Docker socket which container holds a port
       --json           Print JSON to stdout and exit
       --plain          Print a plain table and exit
       --kill           Kill the process on --port. Requires --yes
@@ -175,6 +201,13 @@ 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
+  m  switch mode                d  show or hide the detail panel
+
+Modes
+  Beginner mode is the default. It says what each port is in plain language,
+  where to open it, and whether closing it is a good idea. Advanced mode shows
+  pids, users, bind addresses, command lines, working directories, uptime, and
+  how many connections are open. Press m to switch, or set SLASH_PORT_MODE.
 
 Exit codes
   0  success
@@ -184,8 +217,12 @@ Exit codes
   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
-never touches the network.`;
+session, or the shell that launched it; and sends SIGTERM before SIGKILL.
+
+It makes no network connections, and asks nothing else on the machine anything
+either. --docker is the single exception: it reads the local Docker socket - a
+file on this machine - for the name of the container behind a published port.
+SLASH_PORT_DOCKER=1 turns that on for good.`;
 function readVersion() {
     try {
         const manifest = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
@@ -247,6 +284,8 @@ async function main(argv) {
             process.stderr.write('\nRun slash-port --help for usage.\n');
         return code;
     }
+    const mode = resolveMode(options.mode);
+    const docker = resolveDocker(options.docker);
     if (options.help) {
         process.stdout.write(`${HELP}\n`);
         return EXIT_OK;
@@ -261,7 +300,7 @@ async function main(argv) {
         process.env['NO_COLOR'] = '1';
     let entries;
     try {
-        entries = await scan({ udp: options.udp });
+        entries = await scan({ udp: options.udp, docker });
     }
     catch (error) {
         if (error instanceof ScanError) {
@@ -283,14 +322,14 @@ async function main(argv) {
             process.stdout.write(`${JSON.stringify(toJson(selected), null, 2)}\n`);
         }
         else {
-            process.stdout.write(`${plainTable(selected)}\n`);
+            process.stdout.write(`${plainTable(selected, mode)}\n`);
         }
         // 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 ? '' : options.port.text, udp: options.udp }));
+    const instance = render(_jsx(App, { initialEntries: entries, initialFilter: options.port === null ? '' : options.port.text, udp: options.udp, docker: docker, mode: mode }));
     await instance.waitUntilExit();
     return EXIT_OK;
 }