slash-port 0.2.0 → 0.3.0

package/dist/cli.js

@@ -3,19 +3,46 @@ 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';
-/** 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 = {
         port: null,
+        mode: null,
         udp: false,
+        docker: null,
         json: false,
         plain: false,
         kill: false,
@@ -49,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;
@@ -108,12 +154,13 @@ 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.`);
+            throw new UsageError(`--kill needs --all to use ${options.port.text}, so killing every match is deliberate.`, EXIT_REFUSED);
         }
     }
     if (options.force && !options.kill)
@@ -122,7 +169,7 @@ function parseArgs(argv) {
         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 [ports] [options]
@@ -134,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
@@ -150,15 +201,28 @@ 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
-  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
-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');
@@ -180,8 +244,9 @@ async function killFromCli(entries, options) {
     const targets = selectPort(entries, options);
     if (targets.length === 0) {
         process.stderr.write(`Nothing is listening on ${describePortSelector(selector)}.\n`);
-        return EXIT_FAILED;
+        return EXIT_NOT_FOUND;
     }
+    let refusals = 0;
     let failures = 0;
     for (const target of targets) {
         const result = await killEntry(target, {
@@ -190,10 +255,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;
@@ -201,9 +276,16 @@ 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;
     }
+    const mode = resolveMode(options.mode);
+    const docker = resolveDocker(options.docker);
     if (options.help) {
         process.stdout.write(`${HELP}\n`);
         return EXIT_OK;
@@ -218,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) {
@@ -240,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 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 ? '' : 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;
 }