slash-port 0.2.0 → 0.3.0

package/dist/docker.js

@@ -0,0 +1,208 @@
+import { request } from 'node:http';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { posix } from 'node:path';
+import { browserUrl, matchSignatureEntry, redundantHint } from './describe.js';
+/**
+ * Where the engine listens, in the order worth trying. Docker Desktop, Colima,
+ * Rancher, and a plain Linux install each put the socket somewhere different,
+ * and the alternative to knowing all four is telling a Colima user their
+ * containers do not exist.
+ */
+export function socketCandidates(env = process.env, platform = process.platform, home = homedir()) {
+    const host = env['DOCKER_HOST'];
+    // A TCP DOCKER_HOST is somebody else's machine, and slash-port does not make
+    // network connections. Falling through to the local sockets would answer a
+    // question about the wrong host, so it is left unanswered instead.
+    if (host?.startsWith('unix://'))
+        return [host.slice('unix://'.length)];
+    // Docker Desktop on Windows sets `npipe:////./pipe/docker_engine`, which is
+    // the same pipe written the other way round.
+    if (host?.startsWith('npipe://')) {
+        return [host.slice('npipe://'.length).replace(/\//g, '\\')];
+    }
+    if (host)
+        return [];
+    if (platform === 'win32')
+        return ['\\\\.\\pipe\\docker_engine'];
+    // Joined as posix paths rather than with `join`, which follows the host
+    // separator. These four are unix sockets whatever machine is asking about
+    // them, and the win32 branch above has already taken the one platform where
+    // a backslash would have been right.
+    return [
+        '/var/run/docker.sock',
+        posix.join(home, '.docker/run/docker.sock'),
+        posix.join(home, '.colima/default/docker.sock'),
+        posix.join(home, '.rd/docker.sock'),
+    ];
+}
+function plausibleSockets(candidates) {
+    // A named pipe is not a file, so on Windows the only way to find out is to
+    // try it - which the request below does, and gives up on quickly.
+    return candidates.filter((path) => path.startsWith('\\\\') || existsSync(path));
+}
+/**
+ * Ask the local engine over its unix socket. Nothing here touches the network:
+ * this is a file on this machine, the same as `/proc/net/tcp` is.
+ *
+ * Every failure is the same failure - no annotations - because a machine
+ * without Docker, a machine whose user is not in the `docker` group, and a
+ * machine whose engine is starting up are all cases where the right thing to
+ * do is describe the port the way it would have been described anyway.
+ */
+/** Enough of a container list to name a port; a bigger reply is not one. */
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+async function listContainers(socketPath, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            call.destroy();
+            resolve(value);
+        };
+        const call = request({
+            socketPath,
+            path: '/containers/json',
+            method: 'GET',
+            // Not the global agent: its keep-alive would park a connection to the
+            // engine for the life of the interface.
+            agent: false,
+        }, (response) => {
+            if (response.statusCode !== 200) {
+                response.resume();
+                finish([]);
+                return;
+            }
+            let body = '';
+            response.setEncoding('utf8');
+            response.on('data', (chunk) => {
+                body += chunk;
+                if (body.length > MAX_BODY_BYTES)
+                    finish([]);
+            });
+            response.on('end', () => {
+                try {
+                    const parsed = JSON.parse(body);
+                    finish(Array.isArray(parsed) ? parsed : []);
+                }
+                catch {
+                    finish([]);
+                }
+            });
+        });
+        // A deadline, not `timeout`, which arms `socket.setTimeout` and so only
+        // fires after that long with no traffic at all. An engine dribbling out a
+        // reply would keep resetting it and hold the scan open indefinitely.
+        const deadline = setTimeout(() => finish([]), timeoutMs);
+        call.on('error', () => finish([]));
+        call.end();
+    });
+}
+/** Published port to the container behind it. */
+export function indexPorts(containers) {
+    const index = new Map();
+    for (const container of containers) {
+        const name = container.Names?.[0]?.replace(/^\//, '') ?? null;
+        const image = container.Image ?? null;
+        if (!name || !image)
+            continue;
+        const info = {
+            name,
+            image,
+            project: container.Labels?.['com.docker.compose.project'] ?? null,
+            service: container.Labels?.['com.docker.compose.service'] ?? null,
+        };
+        for (const published of container.Ports ?? []) {
+            // An unpublished port is not reachable from here and will not appear in
+            // the socket table, so indexing it would only invite a false match.
+            if (typeof published.PublicPort === 'number')
+                index.set(published.PublicPort, info);
+        }
+    }
+    return index;
+}
+/** `postgres:16-alpine` and `ghcr.io/org/api:sha-1234` are both one word. */
+export function imageName(image) {
+    const withoutTag = image.replace(/@sha256:[\da-f]+$/i, '').replace(/:[^:/]+$/, '');
+    return withoutTag.split('/').pop() || image;
+}
+/**
+ * Fold what the container knows into the row.
+ *
+ * This is the difference between "Docker published port" - true, and useless -
+ * and "PostgreSQL in Docker (shop)", which names the thing and the project it
+ * belongs to. The image is run through the same signatures as a command line,
+ * so `postgres:16` reads as PostgreSQL and inherits everything that goes with
+ * being a database, including how carefully to treat it.
+ */
+export function annotate(entry, container) {
+    const signature = matchSignatureEntry(`${imageName(container.image)} ${container.name}`);
+    const what = signature?.label ?? imageName(container.image);
+    const label = `${what} in Docker`;
+    // A compose project called `docker` is Docker's own honest answer and still
+    // tells nobody anything, so the container's name takes over when the project
+    // would only repeat the label.
+    const project = container.project && !redundantHint(container.project, label)
+        ? container.project
+        : container.name;
+    const category = signature?.category ?? 'container';
+    const annotated = {
+        ...entry,
+        label,
+        source: 'docker',
+        category,
+        hint: project,
+        // The compose project is only mentioned when it survived the redundancy
+        // check above; naming a project called `docker` helps nobody.
+        summary: project === container.project
+            ? `The container ${container.name}, from the ${container.project} compose project, running ${container.image}.`
+            : `The container ${container.name}, running ${container.image}.`,
+        // The compose form only makes sense when the project name survived the
+        // redundancy check; `docker start` names the container and always does.
+        restart: project === container.project
+            ? `Bring it back with \`${['docker compose up -d', container.service].filter(Boolean).join(' ')}\`.`
+            : `Bring it back with \`docker start ${container.name}\`.`,
+        // Killing docker-proxy leaves the container running and the port
+        // unpublished, which is a stranger state than either stopping or leaving
+        // it. Saying so is worth more than a signal ever is.
+        riskReason: `stop the container instead: \`docker stop ${container.name}\``,
+        risk: 'caution',
+    };
+    // The category may have changed - a `container` row that turned out to be
+    // Adminer is a web page now - so whether a browser is the right thing to
+    // point at it has to be decided again.
+    return { ...annotated, url: browserUrl(annotated) };
+}
+/**
+ * Name the containers behind published ports, when there is a local engine to
+ * ask. Best effort and quick to give up: a machine with no Docker pays one
+ * `existsSync` for this, and one that has it pays a request to a unix socket.
+ */
+export async function annotateContainers(entries, options = {}) {
+    const wanted = entries.some((entry) => entry.category === 'container');
+    if (!wanted)
+        return [...entries];
+    // Every socket that might be there is tried in turn, not just the first that
+    // exists: a stopped Docker Desktop leaves /var/run/docker.sock behind, and
+    // giving up on it would hide a Colima engine that is running perfectly well.
+    let index = new Map();
+    for (const socketPath of plausibleSockets(options.candidates ?? socketCandidates())) {
+        index = indexPorts(await listContainers(socketPath, options.timeoutMs ?? 500));
+        if (index.size > 0)
+            break;
+    }
+    if (index.size === 0)
+        return [...entries];
+    return entries.map((entry) => {
+        // Only rows Docker was already credited with: a coincidence between a
+        // published port and an unrelated process must not be dressed up as a
+        // container.
+        if (entry.category !== 'container')
+            return entry;
+        const container = index.get(entry.port);
+        return container ? annotate(entry, container) : entry;
+    });
+}

package/dist/explain.js

@@ -0,0 +1,209 @@
+import { CATEGORY_INFO, elevationRemedy, ownedByCurrentUser } from './describe.js';
+/** The category as a noun phrase, so it can follow "is". */
+const CATEGORY_NOUN = {
+    web: 'a web server',
+    database: 'a database',
+    container: 'a container port',
+    messaging: 'a message broker',
+    tooling: 'a development tool',
+    ai: 'a local model server',
+    system: 'a system service',
+    remote: 'a way in from another machine',
+    desktop: 'a desktop app',
+    runtime: 'a program',
+    unknown: 'something slash-port could not identify',
+};
+/**
+ * The short answer for the "can I close it" column. One or two words, because
+ * the column has to survive an eighty-column terminal, with the whole reason
+ * waiting in the panel underneath.
+ */
+export function riskWord(risk, platform = process.platform) {
+    switch (risk) {
+        case 'safe':
+            return 'Yes';
+        case 'caution':
+            return 'Probably';
+        case 'risky':
+            return 'Better not';
+        case 'protected':
+            return 'No';
+        default:
+            return platform === 'win32' ? 'Not as you' : 'Needs sudo';
+    }
+}
+/**
+ * The same answer with its reason, short enough for a table column. A table
+ * that wraps is a table that has stopped being one.
+ */
+export function riskSentence(entry) {
+    // ASCII, deliberately. This string reaches `--plain`, which is what a pipe
+    // and a batch script read, and an em dash under a legacy Windows code page
+    // is not a dash.
+    return `${riskWord(entry.risk)} - ${entry.riskReason}`;
+}
+/**
+ * The answer with the way back, for the one place that has room for a sentence
+ * and no room for a second line.
+ */
+export function riskAdvice(entry) {
+    const restart = entry.risk === 'safe' || entry.risk === 'caution' ? entry.restart : null;
+    return [`${riskSentence(entry)}.`, restart].filter(Boolean).join(' ');
+}
+/**
+ * The one-line answer to "what is this", built so that it never repeats the
+ * process name back at the reader. When nothing was identified it says so,
+ * because "unidentified" is a fact and `figma_agent` next to `figma_agent` is
+ * not.
+ */
+export function headline(entry) {
+    const noun = CATEGORY_NOUN[entry.category];
+    if (!entry.label) {
+        return entry.processName ? `${entry.processName} - not identified` : 'Not identified';
+    }
+    const named = entry.hint ? `${entry.label} (${entry.hint})` : entry.label;
+    // "Redis - a database" earns its dash; "a desktop app - a desktop app" does
+    // not, so a label that already is the noun does not get it twice.
+    return entry.label.toLowerCase() === noun.replace(/^an? /, '') ? named : `${named} - ${noun}`;
+}
+function ownerPhrase(entry) {
+    const parts = [];
+    if (entry.user)
+        parts.push(ownedByCurrentUser(entry) ? `you (${entry.user})` : entry.user);
+    else
+        parts.push('an owner slash-port cannot see');
+    if (entry.processName)
+        parts.push(entry.processName);
+    if (entry.pid !== null)
+        parts.push(`pid ${entry.pid}`);
+    return parts.join(' · ');
+}
+/**
+ * What beginner mode puts under the list: what it is, where to look at it, who
+ * started it, and whether closing it is a good idea. Everything a person needs
+ * to decide, and nothing that only matters once they have decided.
+ */
+export function beginnerBrief(entry, options = {}) {
+    const fields = [];
+    if (entry.hint && entry.label) {
+        fields.push({ label: entry.source === 'docker' ? 'Container' : 'Project', value: entry.hint });
+    }
+    else if (entry.category === 'container' && options.docker !== true) {
+        // Otherwise the default quietly costs the answer: "Docker Desktop" on 5432
+        // is true, useless, and one flag away from naming the container.
+        fields.push({ label: 'Container', value: 'not looked up - re-run with --docker to name it' });
+    }
+    if (entry.url)
+        fields.push({ label: 'Open', value: entry.url });
+    fields.push({ label: 'Started by', value: ownerPhrase(entry) });
+    fields.push({ label: 'Close it', value: riskSentence(entry) });
+    // The way back gets its own line rather than trailing the verdict, because
+    // it is the half of the answer that would be truncated away, and it is the
+    // half that turns "you can close this" into something a person will do.
+    const restart = entry.risk === 'safe' || entry.risk === 'caution' ? entry.restart : null;
+    if (restart)
+        fields.push({ label: 'Afterwards', value: restart });
+    if (entry.risk === 'blocked' && entry.pid !== null) {
+        fields.push({
+            label: 'To signal it',
+            value: `Run slash-port again with ${elevationRemedy()}.`,
+        });
+    }
+    return {
+        headline: headline(entry),
+        summary: entry.summary,
+        fields,
+    };
+}
+/** `2h 11m`, `4d 3h`, `38s` - the coarsest two units that are still true. */
+export function formatDuration(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return '-';
+    const days = Math.floor(seconds / 86400);
+    const hours = Math.floor((seconds % 86400) / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const rest = Math.floor(seconds % 60);
+    if (days > 0)
+        return `${days}d ${hours}h`;
+    if (hours > 0)
+        return `${hours}h ${minutes}m`;
+    if (minutes > 0)
+        return `${minutes}m ${rest}s`;
+    return `${rest}s`;
+}
+/** Bytes as the unit a person would have said out loud. */
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return '-';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value >= 10 || unit === 0 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`;
+}
+const SOURCE_PHRASE = {
+    signature: 'command line',
+    docker: 'the Docker engine',
+    registry: 'well-known port',
+    application: 'install path',
+    location: 'path shape only',
+    none: 'nothing matched',
+};
+/**
+ * What advanced mode puts under the list. The extra facts here are the ones
+ * you want once you have decided something is in the way and are working out
+ * which of two identical-looking processes it is: the working directory, the
+ * parent, how long it has been up, and whether anything is actually talking
+ * to it.
+ *
+ * `detail` is filled in asynchronously for the selected row only, so the lines
+ * it feeds appear a moment after the rest rather than holding up the list.
+ */
+export function advancedFields(entry, detail) {
+    const fields = [];
+    const process = [
+        entry.processName ?? 'unknown',
+        entry.pid === null ? null : `pid ${entry.pid}`,
+        detail?.parentPid === undefined
+            ? null
+            : `parent ${detail.parentPid}${detail.parentName ? ` ${detail.parentName}` : ''}`,
+    ]
+        .filter(Boolean)
+        .join(' · ');
+    fields.push({ label: 'Process', value: process });
+    fields.push({ label: 'User', value: entry.user ?? 'not visible' });
+    const listen = `${entry.addresses.join(', ')} · ${entry.protocol.toUpperCase()} · IPv${entry.families.join('/IPv')}`;
+    fields.push({ label: 'Listening', value: listen });
+    if (detail?.established !== undefined) {
+        fields.push({
+            label: 'Clients',
+            value: detail.established === 0
+                ? 'nothing connected'
+                : `${detail.established} connection${detail.established === 1 ? '' : 's'} open`,
+        });
+    }
+    if (detail?.uptimeSeconds !== undefined) {
+        const started = detail.startedAt ? ` (since ${detail.startedAt})` : '';
+        fields.push({ label: 'Running', value: `${formatDuration(detail.uptimeSeconds)}${started}` });
+    }
+    if (detail?.rssBytes !== undefined) {
+        const cpu = detail.cpuPercent === undefined ? '' : ` · ${detail.cpuPercent.toFixed(1)}% CPU`;
+        fields.push({ label: 'Memory', value: `${formatBytes(detail.rssBytes)}${cpu}` });
+    }
+    if (detail?.cwd)
+        fields.push({ label: 'Directory', value: detail.cwd });
+    else if (detail?.cwdDenied) {
+        fields.push({ label: 'Directory', value: `not visible - re-run with ${elevationRemedy()}` });
+    }
+    if (entry.command)
+        fields.push({ label: 'Command', value: entry.command });
+    fields.push({
+        label: 'Identified',
+        value: `${entry.label ?? 'not identified'} · ${entry.category} · from ${SOURCE_PHRASE[entry.source]}`,
+    });
+    fields.push({ label: 'Kill', value: riskAdvice(entry) });
+    return fields;
+}

package/dist/format.js

@@ -1,3 +1,4 @@
+import { riskSentence } from './explain.js';
 import { matchesPort, tryPortSelector } from './ports.js';
 /** Shown wherever a value is genuinely absent, rather than an empty column. */
 export const ABSENT = '-';
@@ -16,13 +17,23 @@ export function formatProcess(entry) {
 export function formatAddresses(entry) {
     return entry.addresses.join(', ');
 }
-/** The description column: what it is, which project, and whether it is protected. */
+/**
+ * The description column: what it is, which project, and whether you can do
+ * anything about it. A guarded row is never also marked `[locked]` - it is
+ * refused whoever you are, so the extra badge would only add noise.
+ *
+ * A row nothing could be worked out about shows `-`, never the process name
+ * over again. The process is already a column; repeating it here would dress
+ * "slash-port has no idea" up as an answer.
+ */
 export function formatDescription(entry) {
-    const parts = [entry.label];
+    const parts = [entry.label ?? ABSENT];
     if (entry.hint)
         parts.push(`(${entry.hint})`);
     if (entry.guard)
         parts.push('[protected]');
+    else if (entry.elevation)
+        parts.push('[locked]');
     return parts.join(' ');
 }
 /** Everything a row can be matched on, lowercased once for filtering. */
@@ -33,7 +44,8 @@ export function searchText(entry) {
         formatPid(entry),
         entry.user ?? '',
         entry.processName ?? '',
-        entry.label,
+        entry.label ?? '',
+        entry.category,
         entry.hint ?? '',
         entry.addresses.join(' '),
         entry.command ?? '',
@@ -56,9 +68,17 @@ export function matchesFilter(entry, filter) {
  * The plain-text table used whenever output is not a terminal. Aligned to the
  * widest value in each column and containing no control codes at all, so it
  * survives a pipe, a redirect, and a `grep`.
+ *
+ * The first six columns are the same in both modes and always will be: a
+ * script that already splits this output keeps working. Mode only ever adds a
+ * column on the end - what closing it would mean for a beginner, the command
+ * line for everybody else - because appending is the one change to a table
+ * that cannot break a reader of it.
  */
-export function plainTable(entries) {
+export function plainTable(entries, mode = 'beginner') {
+    const beginner = mode === 'beginner';
     const header = ['PORT', 'PID', 'USER', 'PROCESS', 'ADDRESS', 'DESCRIPTION'];
+    header.push(beginner ? 'CAN I CLOSE IT?' : 'COMMAND');
     const rows = entries.map((entry) => [
         formatPort(entry),
         formatPid(entry),
@@ -66,6 +86,7 @@ export function plainTable(entries) {
         formatProcess(entry),
         formatAddresses(entry),
         formatDescription(entry),
+        beginner ? riskSentence(entry) : (entry.command ?? ABSENT),
     ]);
     const widths = header.map((label, column) => Math.max(label.length, ...rows.map((row) => row[column].length), 0));
     const render = (row) => row
@@ -74,7 +95,15 @@ export function plainTable(entries) {
         .trimEnd();
     return [render(header), ...rows.map(render)].join('\n');
 }
-/** The `--json` shape. Stable, and a superset of what the table shows. */
+/**
+ * The `--json` shape: a superset of every mode, because a program reading this
+ * has no mode. Fields are added over time and never repurposed, so `jq` on an
+ * old field keeps working.
+ *
+ * `description` is null rather than a repeat of `process` when nothing could be
+ * identified, which is the one thing here that a reader has to know: absence is
+ * reported as absence.
+ */
 export function toJson(entries) {
     return entries.map((entry) => ({
         port: entry.port,
@@ -86,8 +115,17 @@ export function toJson(entries) {
         process: entry.processName,
         command: entry.command,
         description: entry.label,
+        descriptionSource: entry.source,
+        category: entry.category,
         project: entry.hint,
+        summary: entry.summary,
+        url: entry.url,
+        restart: entry.restart,
+        risk: entry.risk,
+        riskReason: entry.riskReason,
         protected: entry.guard !== null,
         protectedReason: entry.guard,
+        locked: entry.elevation !== null,
+        lockedReason: entry.elevation,
     }));
 }