slash-port 0.3.0 → 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.3.0-0f8b7d?logo=github&logoColor=white)](https://github.com/Slash-ui/slash-port/releases/tag/v0.3.0)<!-- /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)
@@ -91,9 +101,8 @@ Requires Node 22 or newer. Works on Linux, macOS, and Windows.
 
 ### Updating
 
-The current release is
-<!-- release:version -->0.3.0<!-- /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
@@ -162,6 +171,20 @@ at any time, and `d` hides the panel in either.
 | 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.
@@ -341,6 +364,16 @@ are fixed rather than configurable:
 - **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"

package/dist/ui/App.js

@@ -7,7 +7,7 @@ import { ABSENT, formatAddresses, formatDescription, formatPid, formatPort, form
 import { inspectProcess } from '../inspect.js';
 import { killEntry } from '../kill.js';
 import { scan } from '../scan/index.js';
-import { cell, color, layout, truncate } from './theme.js';
+import { cell, color, displayWidth, layout, truncate } from './theme.js';
 /**
  * Every row the interface spends on something other than the list, and what it
  * spends them on. These have to be exact rather than generous: the viewport is
@@ -337,9 +337,65 @@ export function App({ initialEntries, initialFilter = '', udp: initialUdp = fals
                     address: formatAddresses(entry),
                 });
                 return (_jsxs(Box, { children: [_jsxs(Text, { inverse: isSelected, color: rowColor, children: [left, ' '] }), _jsx(Text, { inverse: isSelected, color: rowColor ?? color('accent'), children: cell(formatDescription(entry), columnLayout.description) }), columnLayout.url > 0 && (_jsxs(Text, { inverse: isSelected, color: rowColor ?? color('heading'), children: [' ', cell(entry.url ?? ABSENT, columnLayout.url)] })), columnLayout.risk > 0 && (_jsxs(Text, { inverse: isSelected, color: color(RISK_COLOR[entry.risk]), children: [' ', cell(riskWord(entry.risk), columnLayout.risk)] }))] }, entry.id));
-            }), !loading && entries.length === 0 && (_jsx(Text, { color: color('muted'), children: truncate(`Nothing is listening${udp ? '' : ' on TCP'}. Press u to include UDP, r to rescan.`, columnLayout.total) })), !loading && entries.length > 0 && visible.length === 0 && (_jsx(Text, { color: color('muted'), children: truncate(`No port matches “${filter}”. Press Esc to clear the filter.`, columnLayout.total) })), showPanel && current && !dialog && (_jsx(DetailPanel, { entry: current, mode: mode, detail: detail, docker: docker, width: columnLayout.total })), dialog && (_jsx(ConfirmDialog, { entry: dialog, mode: mode, compact: compact, width: columnLayout.total })), !cramped && filtering && (_jsxs(Text, { children: [_jsx(Text, { color: color('heading'), children: "filter " }), _jsx(Text, { children: truncate(filter, Math.max(8, columnLayout.total - 8)) }), _jsx(Text, { color: color('muted'), children: "\u258E" })] })), !cramped && !filtering && filter !== '' && (_jsxs(Text, { color: color('muted'), children: ["filter: ", truncate(filter, Math.max(8, columnLayout.total - 10))] })), !cramped && status && (_jsx(Text, { color: color(STATUS_COLOR[status.kind]), children: truncate(status.text, columnLayout.total) })), !dialog && (_jsx(Text, { color: color('muted'), children: truncate(beginner
-                    ? '↑↓ move · / find · x close it · r refresh · u udp · d details · m advanced · q quit'
-                    : '↑↓/jk move · PgUp/PgDn/g/G jump · / filter · x kill · r rescan · u udp · d detail · m beginner · q quit', columnLayout.total) }))] }));
+            }), !loading && entries.length === 0 && (_jsx(Text, { color: color('muted'), children: truncate(`Nothing is listening${udp ? '' : ' on TCP'}. Press u to include UDP, r to rescan.`, columnLayout.total) })), !loading && entries.length > 0 && visible.length === 0 && (_jsx(Text, { color: color('muted'), children: truncate(`No port matches “${filter}”. Press Esc to clear the filter.`, columnLayout.total) })), showPanel && current && !dialog && (_jsx(DetailPanel, { entry: current, mode: mode, detail: detail, docker: docker, width: columnLayout.total })), dialog && (_jsx(ConfirmDialog, { entry: dialog, mode: mode, compact: compact, width: columnLayout.total })), !cramped && filtering && (_jsxs(Text, { children: [_jsx(Text, { color: color('heading'), children: "filter " }), _jsx(Text, { children: truncate(filter, Math.max(8, columnLayout.total - 8)) }), _jsx(Text, { color: color('muted'), children: "\u258E" })] })), !cramped && !filtering && filter !== '' && (_jsxs(Text, { color: color('muted'), children: ["filter: ", truncate(filter, Math.max(8, columnLayout.total - 10))] })), !cramped && status && (_jsx(Text, { color: color(STATUS_COLOR[status.kind]), children: truncate(status.text, columnLayout.total) })), !dialog && _jsx(HelpLine, { mode: mode, width: columnLayout.total })] }));
+}
+/**
+ * The keys, kept apart from what they do so the key can be given a colour of
+ * its own. In one colour the line reads as a sentence and the reader has to
+ * pick the keys back out of it, which is the opposite of what a help line is
+ * for.
+ */
+const HELP = {
+    beginner: [
+        ['↑↓', 'move'],
+        ['/', 'find'],
+        ['x', 'close it'],
+        ['r', 'refresh'],
+        ['u', 'udp'],
+        ['d', 'details'],
+        ['m', 'advanced'],
+        ['q', 'quit'],
+    ],
+    advanced: [
+        ['↑↓/jk', 'move'],
+        ['PgUp/PgDn/g/G', 'jump'],
+        ['/', 'filter'],
+        ['x', 'kill'],
+        ['r', 'rescan'],
+        ['u', 'udp'],
+        ['d', 'detail'],
+        ['m', 'beginner'],
+        ['q', 'quit'],
+    ],
+};
+const HELP_SEPARATOR = ' · ';
+/**
+ * Measured in cells and trimmed by dropping whole hints, because half a hint
+ * helps nobody and an ellipsis costs about what a key does.
+ *
+ * `q quit` is kept and the hints before it give way, since the one line a
+ * reader goes looking for is the one that tells them how to get out - and it
+ * is last, which is exactly where trimming from the end would have taken it.
+ *
+ * Always renders, even with nothing left to show: the row is one the height
+ * arithmetic has already paid for, and giving it back would move the list.
+ */
+function HelpLine({ mode, width }) {
+    const hints = HELP[mode];
+    const quit = hints[hints.length - 1];
+    const gap = displayWidth(HELP_SEPARATOR);
+    const cost = ([key, label]) => displayWidth(key) + 1 + displayWidth(label);
+    const shown = [];
+    let used = cost(quit);
+    for (const hint of hints.slice(0, -1)) {
+        if (used + gap + cost(hint) > width)
+            break;
+        shown.push(hint);
+        used += gap + cost(hint);
+    }
+    if (used <= width)
+        shown.push(quit);
+    return (_jsx(Text, { color: color('muted'), children: shown.map(([key, label], index) => (_jsxs(Text, { children: [index === 0 ? '' : HELP_SEPARATOR, _jsx(Text, { color: color('heading'), children: key }), " ", label] }, key))) }));
 }
 /** A `label  value` line, with the labels aligned down the panel. */
 function FieldLines({ fields, width }) {

package/package.json

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