slash-port 0.1.0

package/dist/describe.js

@@ -0,0 +1,264 @@
+import { basename } from 'node:path';
+export const SIGNATURES = [
+    // Node frameworks and dev servers, ahead of the runtime that hosts them.
+    { pattern: /\bnext(-server)?\b|[/\\]next[/\\]dist[/\\]/i, label: 'Next.js' },
+    { pattern: /\bnuxt\b/i, label: 'Nuxt' },
+    { pattern: /[/\\]vite[/\\]|\bvite\b/i, label: 'Vite dev server' },
+    { pattern: /\bastro\b/i, label: 'Astro' },
+    { pattern: /\bremix\b/i, label: 'Remix' },
+    { pattern: /\bsvelte-kit\b|\bsveltekit\b/i, label: 'SvelteKit' },
+    { pattern: /\bgatsby\b/i, label: 'Gatsby' },
+    { pattern: /\bnest\b|\bnestjs\b/i, label: 'NestJS' },
+    { pattern: /\breact-scripts\b/i, label: 'Create React App' },
+    { pattern: /\bwebpack(-dev-server)?\b/i, label: 'webpack dev server' },
+    { pattern: /\bparcel\b/i, label: 'Parcel' },
+    { pattern: /\bstorybook\b/i, label: 'Storybook' },
+    { pattern: /\bexpo\b/i, label: 'Expo' },
+    { pattern: /\bmetro\b/i, label: 'Metro bundler' },
+    { pattern: /\bvitest\b/i, label: 'Vitest' },
+    { pattern: /\bjest\b/i, label: 'Jest' },
+    { pattern: /\bnodemon\b/i, label: 'nodemon' },
+    { pattern: /\btsx\b|\bts-node\b/i, label: 'TypeScript dev process' },
+    // Deliberately narrow: a bare "serve" appears in half the daemons on a
+    // machine, so only the npm package's own paths count.
+    { pattern: /\bhttp-server\b|npx\s+serve\b|node_modules[/\\]\.bin[/\\]serve\b/i, label: 'static file server' },
+    { pattern: /\bpm2\b/i, label: 'PM2' },
+    // Python.
+    { pattern: /\bgunicorn\b/i, label: 'Gunicorn' },
+    { pattern: /\buvicorn\b/i, label: 'Uvicorn' },
+    { pattern: /\bhypercorn\b/i, label: 'Hypercorn' },
+    { pattern: /manage\.py\s+runserver/i, label: 'Django dev server' },
+    { pattern: /\bdjango\b/i, label: 'Django' },
+    { pattern: /\bflask\b/i, label: 'Flask' },
+    { pattern: /\bfastapi\b/i, label: 'FastAPI' },
+    { pattern: /\bstreamlit\b/i, label: 'Streamlit' },
+    { pattern: /\bjupyter\b|\bipykernel\b/i, label: 'Jupyter' },
+    { pattern: /\bcelery\b/i, label: 'Celery' },
+    { pattern: /\bhttp\.server\b|SimpleHTTPServer/i, label: 'Python http.server' },
+    // Ruby, PHP, Java, Go, .NET.
+    { pattern: /\bpuma\b/i, label: 'Puma' },
+    { pattern: /\bunicorn\b/i, label: 'Unicorn' },
+    { pattern: /\bsidekiq\b/i, label: 'Sidekiq' },
+    { pattern: /\brails\b/i, label: 'Rails' },
+    { pattern: /\bjekyll\b/i, label: 'Jekyll' },
+    { pattern: /artisan\s+serve/i, label: 'Laravel dev server' },
+    { pattern: /\bphp\b.*\s-S\s/i, label: 'PHP built-in server' },
+    { pattern: /\bspring-boot\b|\borg\.springframework\b/i, label: 'Spring Boot' },
+    { pattern: /\bgradle\b/i, label: 'Gradle' },
+    { pattern: /\btomcat\b|\bcatalina\b/i, label: 'Tomcat' },
+    { pattern: /(?:^|[/\\])air(?:\s|$)/i, label: 'Air (Go live reload)' },
+    { pattern: /\bdotnet\b/i, label: '.NET' },
+    // Datastores and queues, matched on the binary name.
+    { pattern: /\bpostgres(ql)?\b/i, label: 'PostgreSQL' },
+    { pattern: /\bmysqld\b|\bmariadbd\b/i, label: 'MySQL / MariaDB' },
+    { pattern: /\bmongod\b/i, label: 'MongoDB' },
+    { pattern: /\bredis-(server|stack)\b/i, label: 'Redis' },
+    { pattern: /\bvalkey\b/i, label: 'Valkey' },
+    { pattern: /\bmemcached\b/i, label: 'Memcached' },
+    { pattern: /\belasticsearch\b|\bopensearch\b/i, label: 'Elasticsearch / OpenSearch' },
+    { pattern: /\bclickhouse\b/i, label: 'ClickHouse' },
+    { pattern: /\brabbitmq\b|\bbeam\.smp\b/i, label: 'RabbitMQ' },
+    { pattern: /\bkafka\b/i, label: 'Kafka' },
+    { pattern: /\bzookeeper\b/i, label: 'ZooKeeper' },
+    { pattern: /\betcd\b/i, label: 'etcd' },
+    { pattern: /\bminio\b/i, label: 'MinIO' },
+    { pattern: /\blocalstack\b/i, label: 'LocalStack' },
+    { pattern: /\bollama\b/i, label: 'Ollama' },
+    { pattern: /\blm-?studio\b/i, label: 'LM Studio' },
+    { pattern: /\bsupabase\b/i, label: 'Supabase' },
+    // Containers, proxies, and system services.
+    { pattern: /\bdocker-proxy\b/i, label: 'Docker published port' },
+    { pattern: /com\.docker\./i, label: 'Docker Desktop' },
+    { pattern: /\bcontainerd\b/i, label: 'containerd' },
+    { pattern: /\bkubelet\b|\bk3s\b|\bminikube\b/i, label: 'Kubernetes' },
+    { pattern: /\bnginx\b/i, label: 'nginx' },
+    { pattern: /\bcaddy\b/i, label: 'Caddy' },
+    { pattern: /\btraefik\b/i, label: 'Traefik' },
+    { pattern: /\bhttpd\b|\bapache2\b/i, label: 'Apache' },
+    { pattern: /\bngrok\b|\bcloudflared\b/i, label: 'tunnel client' },
+    { pattern: /\bsshd\b/i, label: 'OpenSSH server' },
+    { pattern: /\bmDNSResponder\b|\bavahi\b/i, label: 'mDNS / Bonjour' },
+    { pattern: /\brapportd\b/i, label: 'macOS Handoff' },
+    { pattern: /\bControlCe(nter|ntre)\b/i, label: 'macOS Control Center' },
+    { pattern: /\bcupsd\b/i, label: 'CUPS printing' },
+    { pattern: /\bsystemd-resolve/i, label: 'systemd-resolved' },
+    { pattern: /\bdnsmasq\b/i, label: 'dnsmasq' },
+    // Runtimes last: they only win when nothing more specific matched.
+    { pattern: /\bdeno\b/i, label: 'Deno' },
+    { pattern: /\bbun\b/i, label: 'Bun' },
+    { pattern: /\bnode(js)?\b/i, label: 'Node.js' },
+    { pattern: /\bpython[\d.]*\b/i, label: 'Python' },
+    { pattern: /\bruby\b/i, label: 'Ruby' },
+    { pattern: /\bjava\b/i, label: 'Java' },
+    { pattern: /\bphp\b/i, label: 'PHP' },
+    { pattern: /\bperl\b/i, label: 'Perl' },
+];
+/**
+ * Well-known ports, biased towards the ones a developer actually meets rather
+ * than the full IANA list. Only consulted when the process could not be
+ * identified, which is mostly other users' processes.
+ */
+export const PORT_REGISTRY = {
+    20: { label: 'FTP data' },
+    21: { label: 'FTP' },
+    22: { label: 'SSH' },
+    25: { label: 'SMTP' },
+    53: { label: 'DNS' },
+    80: { label: 'HTTP' },
+    110: { label: 'POP3' },
+    111: { label: 'rpcbind' },
+    123: { label: 'NTP' },
+    143: { label: 'IMAP' },
+    389: { label: 'LDAP' },
+    443: { label: 'HTTPS' },
+    445: { label: 'SMB' },
+    465: { label: 'SMTPS' },
+    514: { label: 'syslog' },
+    548: { label: 'Apple Filing Protocol' },
+    587: { label: 'SMTP submission' },
+    631: { label: 'CUPS printing' },
+    853: { label: 'DNS over TLS' },
+    993: { label: 'IMAPS' },
+    1080: { label: 'SOCKS proxy' },
+    1433: { label: 'SQL Server' },
+    1521: { label: 'Oracle database' },
+    1883: { label: 'MQTT' },
+    1900: { label: 'SSDP / UPnP' },
+    2049: { label: 'NFS' },
+    2375: { label: 'Docker daemon (unencrypted)' },
+    2376: { label: 'Docker daemon (TLS)' },
+    3000: { label: 'dev server', generic: true },
+    3001: { label: 'dev server', generic: true },
+    3306: { label: 'MySQL / MariaDB' },
+    3478: { label: 'STUN / TURN' },
+    4200: { label: 'Angular dev server' },
+    4321: { label: 'Astro dev server' },
+    4873: { label: 'Verdaccio npm registry' },
+    5000: { label: 'AirPlay receiver or Flask' },
+    5173: { label: 'Vite dev server' },
+    5432: { label: 'PostgreSQL' },
+    5601: { label: 'Kibana' },
+    5672: { label: 'RabbitMQ (AMQP)' },
+    5900: { label: 'VNC / screen sharing' },
+    6006: { label: 'Storybook or TensorBoard' },
+    6379: { label: 'Redis' },
+    7000: { label: 'AirPlay' },
+    8000: { label: 'dev server', generic: true },
+    8025: { label: 'Mailpit / MailHog' },
+    8080: { label: 'HTTP alternate', generic: true },
+    8081: { label: 'HTTP alternate', generic: true },
+    8443: { label: 'HTTPS alternate' },
+    8888: { label: 'Jupyter' },
+    9000: { label: 'PHP-FPM or MinIO' },
+    9090: { label: 'Prometheus' },
+    9092: { label: 'Kafka' },
+    9200: { label: 'Elasticsearch' },
+    9229: { label: 'Node.js inspector' },
+    11211: { label: 'Memcached' },
+    15672: { label: 'RabbitMQ management' },
+    27017: { label: 'MongoDB' },
+    50000: { label: 'DB2 or SIP' },
+    54321: { label: 'Supabase / H2O' },
+};
+/** The text the heuristics run against: full command line, else process name. */
+function searchable(socket) {
+    return socket.command?.trim() || socket.processName?.trim() || '';
+}
+export function matchSignature(text) {
+    if (!text)
+        return null;
+    for (const signature of SIGNATURES) {
+        if (signature.pattern.test(text))
+            return signature.label;
+    }
+    return null;
+}
+/**
+ * The project a dev server belongs to, taken as the directory above
+ * `node_modules` in its command line. Without it two Vite servers on 5173 and
+ * 5174 are indistinguishable, which is exactly when you need to tell them
+ * apart.
+ */
+export function projectHint(command) {
+    if (!command)
+        return null;
+    const modules = /([^\s"']+)[/\\]node_modules[/\\]/.exec(command);
+    if (modules?.[1]) {
+        const name = basename(modules[1]);
+        if (name && name !== '.' && name !== '/')
+            return name;
+    }
+    // Python and Ruby have no node_modules; fall back to the directory of the
+    // script argument when the command line names one.
+    const script = /(?:^|\s)([^\s"']*[/\\][^\s"']+\.(?:py|rb|js|ts|mjs|cjs))(?:\s|$)/.exec(command);
+    if (script?.[1]) {
+        const directory = script[1].replace(/[/\\][^/\\]+$/, '');
+        const name = basename(directory);
+        if (name && name !== '.' && name !== '/')
+            return name;
+    }
+    return null;
+}
+/**
+ * Describe a port from three sources, in priority order: what the command line
+ * says it is, then the project it belongs to, then the well-known port
+ * registry as a fallback for processes that could not be identified at all.
+ */
+export function describe(socket) {
+    const text = searchable(socket);
+    const signature = matchSignature(text);
+    const hint = projectHint(socket.command);
+    if (signature)
+        return { label: signature, hint };
+    const registered = PORT_REGISTRY[socket.port];
+    if (registered && !registered.generic)
+        return { label: registered.label, hint };
+    if (socket.processName)
+        return { label: socket.processName, hint };
+    if (socket.pid === null)
+        return { label: 'owner not visible', hint };
+    return { label: 'unknown', hint };
+}
+/**
+ * Processes that are never worth killing from here. Compared on the bare
+ * process name, lowercased and with any `.exe` removed.
+ */
+const PROTECTED_NAMES = {
+    init: 'the init process',
+    systemd: 'the init process',
+    launchd: 'the init process',
+    kernel_task: 'the kernel',
+    sshd: 'the SSH daemon — killing it locks you out of a remote machine',
+    'ssh-agent': 'the SSH agent',
+    loginwindow: 'the macOS session',
+    windowserver: 'the macOS window server',
+    systemuiserver: 'the macOS session',
+    dock: 'the macOS session',
+    finder: 'the macOS session',
+    csrss: 'a Windows session process',
+    wininit: 'a Windows session process',
+    winlogon: 'a Windows session process',
+    services: 'the Windows service controller',
+    lsass: 'the Windows security subsystem',
+    smss: 'a Windows session process',
+    svchost: 'a Windows service host — it runs many unrelated services',
+    system: 'the Windows kernel',
+};
+/**
+ * The reason killing this process is refused, or `null` when it is allowed.
+ * Refusal happens before any dialog is offered: there is no confirmation that
+ * lets you kill your own shell.
+ */
+export function guardReason(socket, context = { self: process.pid, parent: process.ppid }) {
+    const { pid } = socket;
+    if (pid === 1)
+        return 'the init process';
+    if (pid !== null && pid === context.self)
+        return 'slash-port itself';
+    if (pid !== null && pid === context.parent)
+        return 'the shell that launched slash-port';
+    const name = socket.processName?.trim().toLowerCase().replace(/\.exe$/, '');
+    if (name && name in PROTECTED_NAMES)
+        return PROTECTED_NAMES[name];
+    return null;
+}

package/dist/format.js

@@ -0,0 +1,87 @@
+/** Shown wherever a value is genuinely absent, rather than an empty column. */
+export const ABSENT = '-';
+export function formatPort(entry) {
+    return `${entry.port}/${entry.protocol}`;
+}
+export function formatPid(entry) {
+    return entry.pid === null ? ABSENT : String(entry.pid);
+}
+export function formatUser(entry) {
+    return entry.user ?? ABSENT;
+}
+export function formatProcess(entry) {
+    return entry.processName ?? ABSENT;
+}
+export function formatAddresses(entry) {
+    return entry.addresses.join(', ');
+}
+/** The description column: what it is, which project, and whether it is protected. */
+export function formatDescription(entry) {
+    const parts = [entry.label];
+    if (entry.hint)
+        parts.push(`(${entry.hint})`);
+    if (entry.guard)
+        parts.push('[protected]');
+    return parts.join(' ');
+}
+/** Everything a row can be matched on, lowercased once for filtering. */
+export function searchText(entry) {
+    return [
+        String(entry.port),
+        entry.protocol,
+        formatPid(entry),
+        entry.user ?? '',
+        entry.processName ?? '',
+        entry.label,
+        entry.hint ?? '',
+        entry.addresses.join(' '),
+        entry.command ?? '',
+    ]
+        .join(' ')
+        .toLowerCase();
+}
+export function matchesFilter(entry, filter) {
+    const needle = filter.trim().toLowerCase();
+    if (!needle)
+        return true;
+    return searchText(entry).includes(needle);
+}
+/**
+ * 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`.
+ */
+export function plainTable(entries) {
+    const header = ['PORT', 'PID', 'USER', 'PROCESS', 'ADDRESS', 'DESCRIPTION'];
+    const rows = entries.map((entry) => [
+        formatPort(entry),
+        formatPid(entry),
+        formatUser(entry),
+        formatProcess(entry),
+        formatAddresses(entry),
+        formatDescription(entry),
+    ]);
+    const widths = header.map((label, column) => Math.max(label.length, ...rows.map((row) => row[column].length), 0));
+    const render = (row) => row
+        .map((value, column) => (column === row.length - 1 ? value : value.padEnd(widths[column])))
+        .join('  ')
+        .trimEnd();
+    return [render(header), ...rows.map(render)].join('\n');
+}
+/** The `--json` shape. Stable, and a superset of what the table shows. */
+export function toJson(entries) {
+    return entries.map((entry) => ({
+        port: entry.port,
+        protocol: entry.protocol,
+        addresses: entry.addresses,
+        families: entry.families,
+        pid: entry.pid,
+        user: entry.user,
+        process: entry.processName,
+        command: entry.command,
+        description: entry.label,
+        project: entry.hint,
+        protected: entry.guard !== null,
+        protectedReason: entry.guard,
+    }));
+}

package/dist/kill.js

@@ -0,0 +1,117 @@
+import { guardReason } from './describe.js';
+const defaultWait = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * Signal 0 asks the kernel whether the process exists and whether we may
+ * signal it, without delivering anything. `EPERM` means it exists but is
+ * someone else's, which deserves a different message from "gone".
+ */
+export function probe(pid, kill = process.kill) {
+    try {
+        kill(pid, 0);
+        return 'alive';
+    }
+    catch (error) {
+        const failure = error;
+        if (failure.code === 'EPERM')
+            return 'denied';
+        return 'gone';
+    }
+}
+function describeTarget(entry) {
+    const name = entry.processName ?? entry.label;
+    return `${name} (pid ${entry.pid}) on port ${entry.port}`;
+}
+/**
+ * Kill whatever is holding a port.
+ *
+ * The order is fixed and every branch before the signal is a refusal, not a
+ * prompt: guardrails, then an unresolved owner, then a process that has
+ * already gone. SIGTERM is polled for up to `graceMs`; a process that outlives
+ * it is reported as `survived` rather than being escalated, because escalating
+ * is a second, deliberate action by the caller.
+ *
+ * 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.
+ */
+export async function killEntry(entry, options = {}) {
+    const { signal = 'SIGTERM', graceMs = 3000, pollMs = 50, kill = process.kill, wait = defaultWait } = options;
+    const guard = entry.guard ?? guardReason(entry);
+    if (guard) {
+        return {
+            status: 'refused',
+            signal: null,
+            message: `Refusing to kill ${guard}.`,
+        };
+    }
+    if (entry.pid === null) {
+        return {
+            status: 'unresolved',
+            signal: null,
+            message: `Port ${entry.port} has an owner slash-port cannot see. Re-run with sudo to resolve it.`,
+        };
+    }
+    const before = probe(entry.pid, kill);
+    if (before === 'gone') {
+        return {
+            status: 'gone',
+            signal: null,
+            message: `${describeTarget(entry)} had already exited. Nothing was signalled.`,
+        };
+    }
+    if (before === 'denied') {
+        return {
+            status: 'denied',
+            signal: null,
+            message: `${describeTarget(entry)} belongs to another user. Re-run with sudo to signal it.`,
+        };
+    }
+    try {
+        kill(entry.pid, signal);
+    }
+    catch (error) {
+        const failure = error;
+        if (failure.code === 'ESRCH') {
+            return {
+                status: 'gone',
+                signal: null,
+                message: `${describeTarget(entry)} exited before the signal was delivered.`,
+            };
+        }
+        if (failure.code === 'EPERM') {
+            return {
+                status: 'denied',
+                signal: null,
+                message: `${describeTarget(entry)} belongs to another user. Re-run with sudo to signal it.`,
+            };
+        }
+        return {
+            status: 'failed',
+            signal: null,
+            message: `Could not signal ${describeTarget(entry)}: ${failure.message}`,
+        };
+    }
+    const deadline = graceMs;
+    let waited = 0;
+    while (waited <= deadline) {
+        if (probe(entry.pid, kill) !== 'alive') {
+            return {
+                status: 'terminated',
+                signal,
+                message: `${describeTarget(entry)} exited after ${signal}.`,
+            };
+        }
+        await wait(pollMs);
+        waited += pollMs;
+    }
+    return {
+        status: 'survived',
+        signal,
+        message: signal === 'SIGKILL'
+            ? `${describeTarget(entry)} did not exit, even after SIGKILL. It is probably stuck in the kernel.`
+            : `${describeTarget(entry)} ignored SIGTERM after ${graceMs}ms. Force it with SIGKILL to escalate.`,
+    };
+}

package/dist/scan/darwin.js

@@ -0,0 +1,135 @@
+import { run, splitHostPort } from './shared.js';
+import { ScanError } from '../types.js';
+/**
+ * Parse lsof field output (`-F`), which emits one tagged field per line:
+ * `p`/`c`/`L` open a process set, `f` opens a file set within it, and `n`/`t`
+ * describe that file. Far more robust than parsing lsof's aligned columns,
+ * which shift with the width of the values in them.
+ */
+export function parseLsof(output) {
+    const records = [];
+    let pid = null;
+    let command = null;
+    let user = null;
+    let name = null;
+    let type = null;
+    const flushFile = () => {
+        if (pid === null || name === null)
+            return;
+        // `a:b->c:d` is a connected socket, not something listening.
+        if (!name.includes('->')) {
+            const split = splitHostPort(name);
+            if (split && split.port > 0) {
+                records.push({
+                    pid,
+                    command,
+                    user,
+                    address: split.address,
+                    port: split.port,
+                    family: type === 'IPv6' ? 6 : 4,
+                });
+            }
+        }
+        name = null;
+        type = null;
+    };
+    for (const line of output.split('\n')) {
+        if (!line)
+            continue;
+        const tag = line[0];
+        const value = line.slice(1);
+        switch (tag) {
+            case 'p': {
+                flushFile();
+                const parsed = Number.parseInt(value, 10);
+                pid = Number.isInteger(parsed) ? parsed : null;
+                command = null;
+                user = null;
+                break;
+            }
+            case 'c':
+                command = value || null;
+                break;
+            case 'L':
+                user = value || null;
+                break;
+            case 'f':
+                flushFile();
+                break;
+            case 'n':
+                name = value;
+                break;
+            case 't':
+                type = value;
+                break;
+            default:
+                break;
+        }
+    }
+    flushFile();
+    return records;
+}
+/** Parse `ps -axww -o pid=,user=,args=` into pid → user and full command line. */
+export function parsePs(output) {
+    const processes = new Map();
+    for (const line of output.split('\n')) {
+        const match = /^\s*(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+        if (!match)
+            continue;
+        processes.set(Number.parseInt(match[1], 10), { user: match[2], command: match[3].trim() });
+    }
+    return processes;
+}
+/**
+ * lsof exits 1 when it matched nothing, which is a normal outcome rather than
+ * a failure, so its stdout is used either way.
+ */
+async function runLsof(args) {
+    try {
+        const { stdout } = await run('lsof', args);
+        return stdout;
+    }
+    catch (error) {
+        const failure = error;
+        if (failure.code === 'ENOENT') {
+            throw new ScanError('lsof is not installed, and macOS needs it to read the socket table.', 'Install it with `brew install lsof`, or use the system copy at /usr/sbin/lsof.');
+        }
+        if (typeof failure.stdout === 'string')
+            return failure.stdout;
+        throw error;
+    }
+}
+export async function scanDarwin(options = {}) {
+    const jobs = [
+        runLsof(['-nP', '-iTCP', '-sTCP:LISTEN', '-FpcLfnt']).then((stdout) => ({
+            protocol: 'tcp',
+            records: parseLsof(stdout),
+        })),
+    ];
+    if (options.udp) {
+        jobs.push(runLsof(['-nP', '-iUDP', '-FpcLfnt']).then((stdout) => ({
+            protocol: 'udp',
+            records: parseLsof(stdout),
+        })));
+    }
+    // lsof reports a truncated command name; ps supplies the full command line
+    // the description heuristics need. One extra spawn, and it can fail safely.
+    const [groups, psOutput] = await Promise.all([
+        Promise.all(jobs),
+        run('ps', ['-axww', '-o', 'pid=,user=,args=']).then((result) => result.stdout, () => ''),
+    ]);
+    const details = parsePs(psOutput);
+    return groups.flatMap(({ protocol, records }) => records.map((record) => {
+        const detail = details.get(record.pid);
+        return {
+            protocol,
+            family: record.family,
+            address: record.address,
+            port: record.port,
+            pid: record.pid,
+            processName: record.command,
+            command: detail?.command ?? null,
+            user: detail?.user ?? record.user,
+        };
+    }));
+}

package/dist/scan/index.js

@@ -0,0 +1,73 @@
+import { describe, guardReason } from '../describe.js';
+import { ScanError } from '../types.js';
+import { scanDarwin } from './darwin.js';
+import { scanLinux } from './linux.js';
+import { normaliseAddress } from './shared.js';
+import { scanWin32 } from './win32.js';
+export { ScanError } from '../types.js';
+const PROTOCOL_ORDER = { tcp: 0, udp: 1 };
+/**
+ * Collapse the sockets of one server into one row.
+ *
+ * A process bound to both `0.0.0.0` and `::` on port 3000 is one dev server,
+ * not two, and listing it twice makes a busy machine unreadable. Rows with an
+ * unresolved pid stay separate from owned ones, because there is no evidence
+ * they are the same process.
+ */
+export function collapse(sockets) {
+    const groups = new Map();
+    for (const socket of sockets) {
+        const id = `${socket.protocol}:${socket.port}:${socket.pid ?? 'unowned'}`;
+        const group = groups.get(id);
+        if (group)
+            group.sockets.push(socket);
+        else
+            groups.set(id, { sockets: [socket] });
+    }
+    const entries = [];
+    for (const [id, group] of groups) {
+        const first = group.sockets[0];
+        // Prefer whichever socket carried the most process detail; on Linux the
+        // IPv4 and IPv6 rows of one server can resolve differently.
+        const richest = group.sockets.find((socket) => socket.command) ?? first;
+        // Normalised here as well as in the scanners, so this funnel is the one
+        // place that decides how an address is displayed.
+        const addresses = [...new Set(group.sockets.map((socket) => normaliseAddress(socket.address)))].sort();
+        const families = [...new Set(group.sockets.map((socket) => socket.family))].sort();
+        const base = {
+            id,
+            protocol: first.protocol,
+            port: first.port,
+            addresses,
+            families,
+            pid: first.pid,
+            processName: richest.processName ?? first.processName,
+            command: richest.command,
+            user: richest.user ?? first.user,
+        };
+        const description = describe(base);
+        entries.push({
+            ...base,
+            label: description.label,
+            hint: description.hint,
+            guard: guardReason(base),
+        });
+    }
+    return sortEntries(entries);
+}
+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 = {}) {
+    switch (process.platform) {
+        case 'linux':
+            return collapse(await scanLinux(options));
+        case 'darwin':
+            return collapse(await scanDarwin(options));
+        case 'win32':
+            return collapse(await scanWin32(options));
+        default:
+            throw new ScanError(`slash-port has no scanner for ${process.platform}.`, 'Supported platforms are Linux, macOS, and Windows.');
+    }
+}