slash-port 0.2.0 → 0.3.0

package/dist/inspect.js

@@ -0,0 +1,271 @@
+import { readFile, readlink } from 'node:fs/promises';
+import { run } from './scan/shared.js';
+/** Never let a probe take the interface down with it. */
+async function attempt(work) {
+    try {
+        return await work();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The same, but keeping the one distinction that carries advice: a permission
+ * failure is somebody else's process and `sudo` would answer it, where a
+ * missing file is a process that exited between the scan and the probe. Both
+ * would otherwise arrive as the same silence.
+ */
+async function attemptOrDenied(work) {
+    try {
+        return { value: await work() };
+    }
+    catch (error) {
+        const code = error.code;
+        return code === 'EACCES' || code === 'EPERM' ? { denied: true } : null;
+    }
+}
+/**
+ * lsof exits 1 when it matched nothing, which is a normal outcome and not a
+ * failure. Treating it as one is why macOS could report a count or nothing at
+ * all, but never "nothing connected" - the one answer that is often the point.
+ */
+async function runTolerant(command, args) {
+    try {
+        return (await run(command, args)).stdout;
+    }
+    catch (error) {
+        const failure = error;
+        if (failure.code === 'ENOENT')
+            return null;
+        return typeof failure.stdout === 'string' ? failure.stdout : null;
+    }
+}
+/**
+ * Count established connections in lsof's field output.
+ *
+ * `-iTCP:PORT` matches a socket whose local *or* remote port is the one asked
+ * about, so every loopback connection appears twice - once from each end. Only
+ * the end whose local side carries the port is counted, or a dev server with
+ * three browser tabs open reports six.
+ */
+export function countLsofEstablished(output, port) {
+    let total = 0;
+    for (const line of output.split('\n')) {
+        if (!line.startsWith('n'))
+            continue;
+        const arrow = line.indexOf('->');
+        if (arrow === -1)
+            continue;
+        if (line.slice(1, arrow).endsWith(`:${port}`))
+            total += 1;
+    }
+    return total;
+}
+/** `[[DD-]HH:]MM:SS` as ps writes it. */
+export function parseElapsed(value) {
+    const match = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/.exec(value.trim());
+    if (!match)
+        return null;
+    const [, days, hours, minutes, seconds] = match;
+    return (Number(days ?? 0) * 86400 +
+        Number(hours ?? 0) * 3600 +
+        Number(minutes ?? 0) * 60 +
+        Number(seconds ?? 0));
+}
+/**
+ * `/proc/[pid]/stat`, whose second field is a command name in parentheses that
+ * may itself contain spaces and parentheses. Everything positional has to be
+ * counted from the last `)`, which is why this is not a `split`.
+ */
+export function parseProcStat(content) {
+    const close = content.lastIndexOf(')');
+    if (close === -1)
+        return null;
+    const fields = content.slice(close + 2).trim().split(/\s+/);
+    // Fields after `comm` start at index 0 = state, so ppid is 1 and starttime,
+    // field 22 in the manual page, is 19 here.
+    const ppid = Number.parseInt(fields[1] ?? '', 10);
+    const startTicks = Number.parseInt(fields[19] ?? '', 10);
+    if (!Number.isInteger(ppid) || !Number.isInteger(startTicks))
+        return null;
+    return { ppid, startTicks };
+}
+function formatClock(startedMsAgo, now) {
+    return new Date(now - startedMsAgo).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+}
+async function inspectLinux(entry, pid) {
+    const detail = {};
+    const stat = await attempt(() => readFile(`/proc/${pid}/stat`, 'utf8'));
+    const parsed = stat === null ? null : parseProcStat(stat);
+    if (parsed) {
+        detail.parentPid = parsed.ppid;
+        const uptime = await attempt(() => readFile('/proc/uptime', 'utf8'));
+        if (uptime) {
+            // The kernel counts a process's start in clock ticks since boot, so its
+            // age is the machine's age minus that. 100 ticks a second is the value
+            // Linux has shipped for decades and there is no portable way to read it.
+            const seconds = Number.parseFloat(uptime.split(/\s+/)[0] ?? '') - parsed.startTicks / 100;
+            if (Number.isFinite(seconds) && seconds >= 0) {
+                detail.uptimeSeconds = seconds;
+                detail.startedAt = formatClock(seconds * 1000, Date.now());
+            }
+        }
+        const comm = await attempt(() => readFile(`/proc/${parsed.ppid}/comm`, 'utf8'));
+        if (comm)
+            detail.parentName = comm.trim();
+    }
+    const status = await attempt(() => readFile(`/proc/${pid}/status`, 'utf8'));
+    const rss = status === null ? null : /^VmRSS:\s+(\d+)\s+kB$/m.exec(status);
+    if (rss?.[1])
+        detail.rssBytes = Number.parseInt(rss[1], 10) * 1024;
+    // Readable only for your own processes, which is exactly when it is useful.
+    // A permission failure is worth saying out loud, because `sudo` answers it.
+    const cwd = await attemptOrDenied(() => readlink(`/proc/${pid}/cwd`));
+    if (cwd && 'value' in cwd)
+        detail.cwd = cwd.value;
+    else if (cwd && 'denied' in cwd)
+        detail.cwdDenied = true;
+    const established = await attempt(() => countEstablishedLinux(entry.port));
+    if (established !== null)
+        detail.established = established;
+    return detail;
+}
+/**
+ * Connections on this port in state 01, ESTABLISHED. Read from the same tables
+ * the Linux scanner already parses, so this costs a file read and no process.
+ */
+async function countEstablishedLinux(port) {
+    const hex = port.toString(16).toUpperCase().padStart(4, '0');
+    let total = 0;
+    for (const table of ['/proc/net/tcp', '/proc/net/tcp6']) {
+        const content = await attempt(() => readFile(table, 'utf8'));
+        if (!content)
+            continue;
+        for (const line of content.split('\n').slice(1)) {
+            const fields = line.trim().split(/\s+/);
+            if (fields.length < 4)
+                continue;
+            if (!fields[1]?.endsWith(`:${hex}`))
+                continue;
+            if (fields[3] === '01')
+                total += 1;
+        }
+    }
+    return total;
+}
+async function inspectDarwin(entry, pid) {
+    const detail = {};
+    const ps = await attempt(() => run('ps', ['-p', String(pid), '-o', 'ppid=,etime=,rss=,pcpu=']));
+    // Each field independently: one blank column must not take the other three
+    // down with it.
+    const fields = ps?.stdout.trim().split(/\s+/) ?? [];
+    const ppid = Number.parseInt(fields[0] ?? '', 10);
+    if (Number.isInteger(ppid)) {
+        detail.parentPid = ppid;
+        const parent = await attempt(() => run('ps', ['-p', String(ppid), '-o', 'comm=']));
+        // `comm` is a full path on macOS; the last component is the name.
+        const name = parent?.stdout.trim().split('/').pop();
+        if (name)
+            detail.parentName = name;
+    }
+    const elapsed = fields[1] === undefined ? null : parseElapsed(fields[1]);
+    if (elapsed !== null) {
+        detail.uptimeSeconds = elapsed;
+        detail.startedAt = formatClock(elapsed * 1000, Date.now());
+    }
+    const rssKb = Number.parseInt(fields[2] ?? '', 10);
+    if (Number.isInteger(rssKb))
+        detail.rssBytes = rssKb * 1024;
+    const cpu = Number.parseFloat(fields[3] ?? '');
+    if (Number.isFinite(cpu))
+        detail.cpuPercent = cpu;
+    // Two lsof runs, and neither needs the other's answer: waiting for them one
+    // after the other doubles how long the panel takes to fill in for nothing.
+    // The connection count is only asked for when the process is ours, because
+    // lsof cannot see another user's sockets and a count that saw half of them
+    // is worse than no count at all.
+    const [cwd, connections] = await Promise.all([
+        runTolerant('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn']),
+        entry.elevation === null
+            ? runTolerant('lsof', ['-nP', `-iTCP:${entry.port}`, '-sTCP:ESTABLISHED', '-Fn'])
+            : Promise.resolve(null),
+    ]);
+    const cwdLine = cwd?.split('\n').find((line) => line.startsWith('n/'));
+    if (cwdLine)
+        detail.cwd = cwdLine.slice(1);
+    else if (cwd !== null && entry.elevation !== null)
+        detail.cwdDenied = true;
+    if (connections !== null)
+        detail.established = countLsofEstablished(connections, entry.port);
+    return detail;
+}
+/**
+ * Windows gives up its process table cheaply and the rest of it expensively.
+ * `tasklist` is already a dependency of the scanner and answers memory;
+ * parents, working directories, and start times all need WMI or PowerShell,
+ * which cost about a second each, so those lines are simply not offered there.
+ */
+async function inspectWin32(entry, pid) {
+    const detail = {};
+    const tasklist = await attempt(() => run('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH']));
+    // The thousands separator is whatever the locale says: a comma, a full stop,
+    // a space, or the non-breaking space French Windows uses.
+    const memory = tasklist === null ? null : /"([^"]+) K"\s*$/m.exec(tasklist.stdout.trim());
+    if (memory?.[1]) {
+        const kb = Number.parseInt(memory[1].replace(/\D/g, ''), 10);
+        if (Number.isInteger(kb))
+            detail.rssBytes = kb * 1024;
+    }
+    const netstat = await attempt(() => run('netstat', ['-ano', '-p', 'TCP']));
+    if (netstat)
+        detail.established = countNetstatEstablished(netstat.stdout, entry.port);
+    return detail;
+}
+/**
+ * Established connections on a port, from `netstat -ano`.
+ *
+ * The state word is translated on a localised Windows - `HERGESTELLT` on a
+ * German build - so the row's shape decides rather than its wording, the same
+ * way the Windows scanner already decides what is listening: a TCP row whose
+ * local port is the one asked about and whose foreign port is not zero is a
+ * connection to it.
+ */
+export function countNetstatEstablished(output, port) {
+    let total = 0;
+    for (const line of output.split('\n')) {
+        const fields = line.trim().split(/\s+/);
+        if (fields.length < 4 || fields[0]?.toUpperCase() !== 'TCP')
+            continue;
+        if (!fields[1]?.endsWith(`:${port}`))
+            continue;
+        const peer = fields[2];
+        if (!peer)
+            continue;
+        const peerPort = Number.parseInt(peer.slice(peer.lastIndexOf(':') + 1), 10);
+        if (Number.isInteger(peerPort) && peerPort > 0)
+            total += 1;
+    }
+    return total;
+}
+/**
+ * Look a single process up in more detail, on demand.
+ *
+ * This is deliberately not part of the scan. A machine with four hundred
+ * listening sockets would pay four hundred times over for facts the reader is
+ * looking at one row at a time, so advanced mode asks only about the row under
+ * the cursor, and asks again when the cursor moves.
+ */
+export async function inspectProcess(entry, platform = process.platform) {
+    if (entry.pid === null)
+        return {};
+    switch (platform) {
+        case 'linux':
+            return inspectLinux(entry, entry.pid);
+        case 'darwin':
+            return inspectDarwin(entry, entry.pid);
+        case 'win32':
+            return inspectWin32(entry, entry.pid);
+        default:
+            return {};
+    }
+}

package/dist/kill.js

@@ -1,4 +1,4 @@
-import { guardReason } from './describe.js';
+import { elevationRemedy, guardReason } from './describe.js';
 const defaultWait = (ms) => new Promise((resolve) => {
     setTimeout(resolve, ms);
 });
@@ -20,7 +20,7 @@ export function probe(pid, kill = process.kill) {
     }
 }
 function describeTarget(entry) {
-    const name = entry.processName ?? entry.label;
+    const name = entry.processName ?? entry.label ?? 'the process';
     return `${name} (pid ${entry.pid}) on port ${entry.port}`;
 }
 /**
@@ -35,7 +35,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 +51,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 +66,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 +85,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/mode.js

@@ -0,0 +1,46 @@
+/**
+ * Everything decided before the first socket is read, and decided the same way
+ * every slash-* tool decides it: flags, then environment, then the default.
+ * There is no config file to consult, and there is not going to be one - this
+ * tool reads the socket table and writes nothing.
+ */
+export const MODES = ['beginner', 'advanced'];
+/**
+ * Beginner is the default, and deliberately so. The person who does not know
+ * what took port 3000 is the person who went looking for a tool that would
+ * tell them; someone who already knows can say `--advanced` once, or set
+ * `SLASH_PORT_MODE` and never say it again.
+ */
+export const DEFAULT_MODE = 'beginner';
+export function isMode(value) {
+    return MODES.includes(value);
+}
+export function resolveMode(flag, env = process.env) {
+    if (flag)
+        return flag;
+    const configured = env['SLASH_PORT_MODE']?.trim().toLowerCase();
+    if (configured && isMode(configured))
+        return configured;
+    return DEFAULT_MODE;
+}
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+const FALSY = new Set(['0', 'false', 'no', 'off']);
+/**
+ * Whether to ask the local Docker engine which container publishes a port.
+ *
+ * Off unless asked for. It is the only thing slash-port asks anything, and a
+ * tool whose whole claim is that it reads two local tables and stops should
+ * not quietly start talking to a daemon because a daemon happened to be there.
+ * `--docker` turns it on for one run; `SLASH_PORT_DOCKER=1` turns it on for
+ * good, and `--no-docker` still overrules that.
+ */
+export function resolveDocker(flag, env = process.env) {
+    if (flag !== null)
+        return flag;
+    const configured = env['SLASH_PORT_DOCKER']?.trim().toLowerCase();
+    if (configured && TRUTHY.has(configured))
+        return true;
+    if (configured && FALSY.has(configured))
+        return false;
+    return false;
+}

package/dist/ports.js

@@ -24,7 +24,7 @@ function portNumber(raw) {
 /**
  * `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
+ * 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) {
@@ -95,8 +95,8 @@ 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
+ * 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.
  */

package/dist/scan/index.js

@@ -1,4 +1,5 @@
-import { describe, guardReason } from '../describe.js';
+import { assessRisk, browserUrl, describe, elevationReason, guardReason } from '../describe.js';
+import { annotateContainers } from '../docker.js';
 import { ScanError } from '../types.js';
 import { scanDarwin } from './darwin.js';
 import { scanLinux } from './linux.js';
@@ -46,11 +47,18 @@ export function collapse(sockets) {
             user: richest.user ?? first.user,
         };
         const description = describe(base);
+        const guard = guardReason(base);
+        const elevation = elevationReason(base);
+        // Risk needs the guard and the elevation, and the URL needs the addresses,
+        // so both are settled here rather than inside `describe`, which only ever
+        // sees one socket's worth of the picture.
+        const shape = { ...base, ...description, guard, elevation };
+        const verdict = assessRisk(shape);
         entries.push({
-            ...base,
-            label: description.label,
-            hint: description.hint,
-            guard: guardReason(base),
+            ...shape,
+            url: browserUrl(shape),
+            risk: verdict.risk,
+            riskReason: verdict.reason,
         });
     }
     return sortEntries(entries);
@@ -58,16 +66,29 @@ export function collapse(sockets) {
 export function sortEntries(entries) {
     return entries.sort((a, b) => a.port - b.port || PROTOCOL_ORDER[a.protocol] - PROTOCOL_ORDER[b.protocol] || (a.pid ?? 0) - (b.pid ?? 0));
 }
-/** Read the local socket table. Nothing in this path touches the network. */
-export async function scan(options = {}) {
+async function scanPlatform(options) {
     switch (process.platform) {
         case 'linux':
-            return collapse(await scanLinux(options));
+            return scanLinux(options);
         case 'darwin':
-            return collapse(await scanDarwin(options));
+            return scanDarwin(options);
         case 'win32':
-            return collapse(await scanWin32(options));
+            return scanWin32(options);
         default:
             throw new ScanError(`slash-port has no scanner for ${process.platform}.`, 'Supported platforms are Linux, macOS, and Windows.');
     }
 }
+/**
+ * Read the local socket table. Nothing in this path touches anything.
+ *
+ * The one thing that could is the container pass, and it only runs when it was
+ * asked for. What it talks to is a unix socket on this machine - the same kind
+ * of local file the scanners read - but "reads two local tables and stops" is
+ * a property worth keeping by default rather than one to opt back into.
+ */
+export async function scan(options = {}) {
+    const entries = collapse(await scanPlatform(options));
+    if (options.docker !== true)
+        return entries;
+    return annotateContainers(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;