slash-port 0.2.0 → 0.3.0

package/dist/describe.js

@@ -1,97 +1,242 @@
-import { basename } from 'node:path';
+import { userInfo } from 'node:os';
+/**
+ * The last component of a path, splitting on both separators whatever platform
+ * this is running on. `node:path`'s own `basename` follows the host, so on
+ * Linux it reads a Windows command line as one long directory name - and the
+ * CI legs that would catch that are the ones where it cannot happen.
+ */
+function lastComponent(path) {
+    return path.split(/[/\\]/).filter(Boolean).pop() ?? '';
+}
+export const CATEGORY_INFO = {
+    web: {
+        summary: 'Point a browser at it - that is what it is there for.',
+        risk: 'safe',
+        browsable: true,
+    },
+    database: {
+        summary: 'Anything connected to it loses its connection when it stops.',
+        risk: 'caution',
+    },
+    container: {
+        summary: 'The container behind it keeps running unless you stop that too.',
+        risk: 'caution',
+    },
+    messaging: {
+        summary: 'Whatever is producing and consuming messages will drop off.',
+        risk: 'caution',
+    },
+    tooling: {
+        summary: 'Closing it stops the tool and nothing else.',
+        risk: 'safe',
+    },
+    ai: {
+        summary: 'Requests already in flight will fail.',
+        risk: 'caution',
+    },
+    system: {
+        summary: 'Part of the operating system rather than anything you started.',
+        risk: 'risky',
+    },
+    remote: {
+        summary: 'Closing it can lock you out of this machine from elsewhere.',
+        risk: 'risky',
+    },
+    desktop: {
+        summary: 'Quitting it from the app itself is tidier than signalling it.',
+        risk: 'caution',
+    },
+    runtime: {
+        summary: 'slash-port could name the runtime but not the project it belongs to.',
+        risk: 'caution',
+    },
+    unknown: {
+        summary: 'slash-port could not work out what this is.',
+        risk: 'caution',
+    },
+};
+const DEV_SERVER_RESTART = 'Start it again with your dev command, usually `npm run dev`.';
 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' },
+    { pattern: /\bnext(-server)?\b|[/\\]next[/\\]dist[/\\]/i, label: 'Next.js', category: 'web', restart: DEV_SERVER_RESTART },
+    { pattern: /\bnuxt\b/i, label: 'Nuxt', category: 'web', restart: DEV_SERVER_RESTART },
+    { pattern: /[/\\]vite[/\\]|\bvite\b/i, label: 'Vite dev server', category: 'web', restart: DEV_SERVER_RESTART },
+    { pattern: /\bastro\b/i, label: 'Astro', category: 'web', restart: DEV_SERVER_RESTART },
+    { pattern: /\bremix\b/i, label: 'Remix', category: 'web', restart: DEV_SERVER_RESTART },
+    { pattern: /\bsvelte-kit\b|\bsveltekit\b/i, label: 'SvelteKit', category: 'web', restart: DEV_SERVER_RESTART },
+    { pattern: /\bgatsby\b/i, label: 'Gatsby', category: 'web', restart: DEV_SERVER_RESTART },
+    { pattern: /\bnest\b|\bnestjs\b/i, label: 'NestJS', category: 'web', restart: DEV_SERVER_RESTART },
+    { pattern: /\breact-scripts\b/i, label: 'Create React App', category: 'web', restart: DEV_SERVER_RESTART },
+    { pattern: /\bwebpack(-dev-server)?\b/i, label: 'webpack dev server', category: 'web', restart: DEV_SERVER_RESTART },
+    { pattern: /\bparcel\b/i, label: 'Parcel', category: 'web', restart: DEV_SERVER_RESTART },
+    {
+        pattern: /\bstorybook\b/i,
+        label: 'Storybook',
+        category: 'web',
+        summary: 'Nothing but the component catalogue depends on it.',
+        restart: 'Start it again with `npm run storybook`.',
+    },
+    { pattern: /\bexpo\b/i, label: 'Expo', category: 'web', restart: 'Start it again with `npx expo start`.' },
+    { pattern: /\bmetro\b/i, label: 'Metro bundler', category: 'tooling', restart: 'It restarts with the React Native app.' },
+    {
+        pattern: /\bvitest\b/i,
+        label: 'Vitest',
+        category: 'tooling',
+        summary: 'A test runner in watch mode: closing it abandons the run in progress.',
+        restart: 'Start it again with `npm test`.',
+    },
+    {
+        pattern: /\bjest\b/i,
+        label: 'Jest',
+        category: 'tooling',
+        summary: 'A test runner in watch mode: closing it abandons the run in progress.',
+        restart: 'Start it again with `npm test`.',
+    },
+    { pattern: /\bnodemon\b/i, label: 'nodemon', category: 'tooling', restart: DEV_SERVER_RESTART },
+    { pattern: /\btsx\b|\bts-node\b/i, label: 'TypeScript dev process', category: 'tooling', restart: DEV_SERVER_RESTART },
     // 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' },
+    {
+        pattern: /\bhttp-server\b|npx\s+serve\b|node_modules[/\\]\.bin[/\\]serve\b/i,
+        label: 'static file server',
+        category: 'web',
+        restart: 'Start it again with `npx serve`.',
+    },
+    {
+        pattern: /\bpm2\b/i,
+        label: 'PM2',
+        category: 'tooling',
+        summary: 'It restarts the apps it supervises, so stopping it stops them too.',
+        risk: 'caution',
+        restart: 'Bring it back with `pm2 resurrect`.',
+    },
     // 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' },
+    { pattern: /\bgunicorn\b/i, label: 'Gunicorn', category: 'web' },
+    { pattern: /\buvicorn\b/i, label: 'Uvicorn', category: 'web' },
+    { pattern: /\bhypercorn\b/i, label: 'Hypercorn', category: 'web' },
+    {
+        pattern: /manage\.py\s+runserver/i,
+        label: 'Django dev server',
+        category: 'web',
+        restart: 'Start it again with `python manage.py runserver`.',
+    },
+    { pattern: /\bdjango\b/i, label: 'Django', category: 'web' },
+    { pattern: /\bflask\b/i, label: 'Flask', category: 'web', restart: 'Start it again with `flask run`.' },
+    { pattern: /\bfastapi\b/i, label: 'FastAPI', category: 'web' },
+    { pattern: /\bstreamlit\b/i, label: 'Streamlit', category: 'web', restart: 'Start it again with `streamlit run`.' },
+    {
+        pattern: /\bjupyter\b|\bipykernel\b/i,
+        label: 'Jupyter',
+        category: 'tooling',
+        summary: 'Unsaved cells in an open notebook are lost when it stops.',
+        risk: 'caution',
+        restart: 'Start it again with `jupyter lab`.',
+    },
+    { pattern: /\bcelery\b/i, label: 'Celery', category: 'messaging' },
+    { pattern: /\bhttp\.server\b|SimpleHTTPServer/i, label: 'Python http.server', category: 'web' },
     // 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' },
+    { pattern: /\bpuma\b/i, label: 'Puma', category: 'web' },
+    { pattern: /\bunicorn\b/i, label: 'Unicorn', category: 'web' },
+    { pattern: /\bsidekiq\b/i, label: 'Sidekiq', category: 'messaging' },
+    { pattern: /\brails\b/i, label: 'Rails', category: 'web', restart: 'Start it again with `bin/rails server`.' },
+    { pattern: /\bjekyll\b/i, label: 'Jekyll', category: 'web' },
+    { pattern: /artisan\s+serve/i, label: 'Laravel dev server', category: 'web', restart: 'Start it again with `php artisan serve`.' },
+    { pattern: /\bphp\b.*\s-S\s/i, label: 'PHP built-in server', category: 'web' },
+    { pattern: /\bspring-boot\b|\borg\.springframework\b/i, label: 'Spring Boot', category: 'web' },
+    { pattern: /\bgradle\b/i, label: 'Gradle', category: 'tooling', summary: 'A build daemon: the next build starts it again.' },
+    { pattern: /\btomcat\b|\bcatalina\b/i, label: 'Tomcat', category: 'web' },
+    { pattern: /(?:^|[/\\])air(?:\s|$)/i, label: 'Air (Go live reload)', category: 'web', restart: 'Start it again with `air`.' },
+    { pattern: /\bdotnet\b/i, label: '.NET', category: 'web' },
     // 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' },
+    {
+        pattern: /\bpostgres(ql)?\b/i,
+        label: 'PostgreSQL',
+        category: 'database',
+        summary: 'Open transactions are rolled back when it stops.',
+    },
+    { pattern: /\bmysqld\b|\bmariadbd\b/i, label: 'MySQL / MariaDB', category: 'database' },
+    { pattern: /\bmongod\b/i, label: 'MongoDB', category: 'database' },
+    {
+        pattern: /\bredis(-(server|stack))?\b/i,
+        label: 'Redis',
+        category: 'database',
+        summary: 'Anything it holds only in memory is gone when it stops.',
+    },
+    { pattern: /\bvalkey\b/i, label: 'Valkey', category: 'database' },
+    {
+        pattern: /\bmemcached\b/i,
+        label: 'Memcached',
+        category: 'database',
+        summary: 'Losing its contents is survivable by design.',
+        risk: 'safe',
+    },
+    { pattern: /\belasticsearch\b|\bopensearch\b/i, label: 'Elasticsearch / OpenSearch', category: 'database' },
+    { pattern: /\bclickhouse\b/i, label: 'ClickHouse', category: 'database' },
+    { pattern: /\brabbitmq\b|\bbeam\.smp\b/i, label: 'RabbitMQ', category: 'messaging' },
+    { pattern: /\bkafka\b/i, label: 'Kafka', category: 'messaging' },
+    { pattern: /\bzookeeper\b/i, label: 'ZooKeeper', category: 'messaging' },
+    { pattern: /\betcd\b/i, label: 'etcd', category: 'database' },
+    { pattern: /\bminio\b/i, label: 'MinIO', category: 'database' },
+    { pattern: /\blocalstack\b/i, label: 'LocalStack', category: 'tooling' },
+    {
+        pattern: /\bollama\b/i,
+        label: 'Ollama',
+        category: 'ai',
+        restart: 'Start it again with `ollama serve`, or by opening the app.',
+    },
+    { pattern: /\blm-?studio\b/i, label: 'LM Studio', category: 'ai' },
+    {
+        pattern: /\bsupabase\b/i,
+        label: 'Supabase',
+        category: 'database',
+        summary: 'Several containers rather than one process.',
+        restart: 'Bring it back with `supabase start`.',
+    },
     // 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' },
+    {
+        pattern: /\bdocker-proxy\b/i,
+        label: 'Docker published port',
+        category: 'container',
+        summary: 'The forwarder Docker puts in front of a container port, not the container itself.',
+        restart: 'It comes back on its own when the container is restarted.',
+    },
+    {
+        pattern: /com\.docker\./i,
+        label: 'Docker Desktop',
+        category: 'container',
+        summary: 'Publishing a port on behalf of a container.',
+        restart: 'Stopping the container that owns the port is the change you probably want.',
+    },
+    { pattern: /\bcontainerd\b/i, label: 'containerd', category: 'container' },
+    { pattern: /\bkubelet\b|\bk3s\b|\bminikube\b/i, label: 'Kubernetes', category: 'container' },
+    { pattern: /\bnginx\b/i, label: 'nginx', category: 'web', risk: 'caution' },
+    { pattern: /\bcaddy\b/i, label: 'Caddy', category: 'web', risk: 'caution' },
+    { pattern: /\btraefik\b/i, label: 'Traefik', category: 'web', risk: 'caution' },
+    { pattern: /\bhttpd\b|\bapache2\b/i, label: 'Apache', category: 'web', risk: 'caution' },
+    {
+        pattern: /\bngrok\b|\bcloudflared\b/i,
+        label: 'tunnel client',
+        category: 'remote',
+        summary: 'A tunnel exposing something on this machine to the internet.',
+        risk: 'caution',
+    },
+    { pattern: /\bsshd\b/i, label: 'OpenSSH server', category: 'remote' },
+    { pattern: /\bmDNSResponder\b|\bavahi\b/i, label: 'mDNS / Bonjour', category: 'system' },
+    { pattern: /\brapportd\b/i, label: 'macOS Handoff', category: 'system' },
+    { pattern: /\bControlCe(nter|ntre)\b/i, label: 'macOS Control Center', category: 'system' },
+    { pattern: /\bcupsd\b/i, label: 'CUPS printing', category: 'system' },
+    { pattern: /\bsystemd-resolve/i, label: 'systemd-resolved', category: 'system' },
+    { pattern: /\bdnsmasq\b/i, label: 'dnsmasq', category: 'system' },
+    // Runtimes last: they only win when nothing more specific matched, and even
+    // then they lose their place as the label to an application name.
+    { pattern: /\bdeno\b/i, label: 'Deno', category: 'runtime', runtime: true },
+    { pattern: /\bbun\b/i, label: 'Bun', category: 'runtime', runtime: true },
+    { pattern: /\bnode(js)?\b/i, label: 'Node.js', category: 'runtime', runtime: true },
+    { pattern: /\bpython[\d.]*\b/i, label: 'Python', category: 'runtime', runtime: true },
+    { pattern: /\bruby\b/i, label: 'Ruby', category: 'runtime', runtime: true },
+    { pattern: /\bjava\b/i, label: 'Java', category: 'runtime', runtime: true },
+    { pattern: /\bphp\b/i, label: 'PHP', category: 'runtime', runtime: true },
+    { pattern: /\bperl\b/i, label: 'Perl', category: 'runtime', runtime: true },
 ];
 /**
  * Well-known ports, biased towards the ones a developer actually meets rather
@@ -99,125 +244,403 @@ export const SIGNATURES = [
  * 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' },
+    20: { label: 'FTP data', category: 'system' },
+    21: { label: 'FTP', category: 'system' },
+    22: { label: 'SSH', category: 'remote' },
+    25: { label: 'SMTP', category: 'system' },
+    53: { label: 'DNS', category: 'system' },
+    80: { label: 'HTTP', category: 'web' },
+    110: { label: 'POP3', category: 'system' },
+    111: { label: 'rpcbind', category: 'system' },
+    123: { label: 'NTP', category: 'system' },
+    143: { label: 'IMAP', category: 'system' },
+    389: { label: 'LDAP', category: 'system' },
+    443: { label: 'HTTPS', category: 'web' },
+    445: { label: 'SMB', category: 'system' },
+    465: { label: 'SMTPS', category: 'system' },
+    514: { label: 'syslog', category: 'system' },
+    548: { label: 'Apple Filing Protocol', category: 'system' },
+    587: { label: 'SMTP submission', category: 'system' },
+    631: { label: 'CUPS printing', category: 'system' },
+    853: { label: 'DNS over TLS', category: 'system' },
+    993: { label: 'IMAPS', category: 'system' },
+    1080: { label: 'SOCKS proxy', category: 'remote' },
+    1433: { label: 'SQL Server', category: 'database' },
+    1521: { label: 'Oracle database', category: 'database' },
+    1883: { label: 'MQTT', category: 'messaging' },
+    1900: { label: 'SSDP / UPnP', category: 'system' },
+    2049: { label: 'NFS', category: 'system' },
+    2375: { label: 'Docker daemon (unencrypted)', category: 'container' },
+    2376: { label: 'Docker daemon (TLS)', category: 'container' },
+    3000: { label: 'dev server', category: 'web', generic: true },
+    3001: { label: 'dev server', category: 'web', generic: true },
+    3306: { label: 'MySQL / MariaDB', category: 'database' },
+    3478: { label: 'STUN / TURN', category: 'system' },
+    4200: { label: 'Angular dev server', category: 'web' },
+    4321: { label: 'Astro dev server', category: 'web' },
+    4873: { label: 'Verdaccio npm registry', category: 'tooling' },
+    5000: { label: 'AirPlay receiver or Flask', category: 'web' },
+    5173: { label: 'Vite dev server', category: 'web' },
+    5432: { label: 'PostgreSQL', category: 'database' },
+    5601: { label: 'Kibana', category: 'web' },
+    5672: { label: 'RabbitMQ (AMQP)', category: 'messaging' },
+    5900: { label: 'VNC / screen sharing', category: 'remote' },
+    6006: { label: 'Storybook or TensorBoard', category: 'web' },
+    6379: { label: 'Redis', category: 'database' },
+    7000: { label: 'AirPlay', category: 'system' },
+    8000: { label: 'dev server', category: 'web', generic: true },
+    8025: { label: 'Mailpit / MailHog', category: 'web' },
+    8080: { label: 'HTTP alternate', category: 'web', generic: true },
+    8081: { label: 'HTTP alternate', category: 'web', generic: true },
+    8443: { label: 'HTTPS alternate', category: 'web' },
+    8888: { label: 'Jupyter', category: 'tooling' },
+    9000: { label: 'PHP-FPM or MinIO', category: 'web' },
+    9090: { label: 'Prometheus', category: 'web' },
+    9092: { label: 'Kafka', category: 'messaging' },
+    9200: { label: 'Elasticsearch', category: 'database' },
+    9229: { label: 'Node.js inspector', category: 'tooling' },
+    11211: { label: 'Memcached', category: 'database' },
+    15672: { label: 'RabbitMQ management', category: 'web' },
+    27017: { label: 'MongoDB', category: 'database' },
+    50000: { label: 'DB2 or SIP', category: 'database' },
+    54321: { label: 'Supabase / H2O', category: 'web' },
 };
 /** 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) {
+function findSignature(text) {
     if (!text)
         return null;
     for (const signature of SIGNATURES) {
         if (signature.pattern.test(text))
-            return signature.label;
+            return signature;
     }
     return null;
 }
+export function matchSignature(text) {
+    return findSignature(text)?.label ?? null;
+}
+/**
+ * The whole record, for callers that have their own text to identify - a
+ * container image, say - and want the category and the advice that come with
+ * a match rather than only its name.
+ */
+export function matchSignatureEntry(text) {
+    return findSignature(text);
+}
+/**
+ * Directory names that name a convention rather than a thing. Seeing `lib` as
+ * the project a server belongs to is worse than seeing nothing, because it
+ * reads like an answer.
+ */
+const ANONYMOUS_DIRECTORIES = new Set([
+    'app',
+    'apps',
+    'bin',
+    'build',
+    'cellar',
+    'code',
+    'contents',
+    'current',
+    'dev',
+    'dist',
+    'docs',
+    'home',
+    'homebrew',
+    'lib',
+    'lib64',
+    'libexec',
+    'linuxbrew',
+    'local',
+    'macos',
+    'opt',
+    'out',
+    'packages',
+    'projects',
+    'repos',
+    'resources',
+    'sbin',
+    'scripts',
+    'server',
+    'share',
+    'site-packages',
+    'source',
+    'src',
+    'srv',
+    'tmp',
+    'usr',
+    'users',
+    'var',
+    'work',
+    'workspace',
+]);
+function meaningfulDirectory(name) {
+    if (!name || name === '.' || name === '/' || name === '..')
+        return null;
+    if (ANONYMOUS_DIRECTORIES.has(name.toLowerCase()))
+        return null;
+    return name;
+}
 /**
  * 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.
+ *
+ * A script under a directory that only names a convention - `lib`, `src`,
+ * `bin` - falls back to the script itself, because `gcloud` says more about
+ * what is running than `lib` does.
  */
 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 !== '/')
+    // Anchored on the marker and read backwards, never split on whitespace: a
+    // project at `/Users/amin/My Project/node_modules/...` is called `My
+    // Project`, and a capture that stops at the space calls it `Project`.
+    const modules = /[/\\]node_modules[/\\]/.exec(command);
+    if (modules) {
+        const name = meaningfulDirectory(enclosingDirectory(command.slice(0, modules.index)));
+        if (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);
+    // script argument when the command line names one. The file name may not
+    // contain spaces, but every directory above it may.
+    const script = /[/\\]([^/\\\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 !== '/')
+        const directory = meaningfulDirectory(enclosingDirectory(command.slice(0, script.index)));
+        if (directory)
+            return directory;
+        // `.../google-cloud-sdk/lib/gcloud.py` is gcloud, whatever `lib` says.
+        const file = script[1].replace(/\.\w+$/, '');
+        if (file && file !== 'main' && file !== 'index' && file !== '__main__')
+            return file;
+    }
+    return null;
+}
+/**
+ * The directory a marker sits in, given everything to the left of it. Its own
+ * last component is the answer, spaces and all - which is the whole reason
+ * this reads backwards from the marker instead of matching a path forwards.
+ */
+function enclosingDirectory(prefix) {
+    const trimmed = prefix.replace(/[/\\]+$/, '');
+    const separator = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
+    const name = (separator === -1 ? trimmed : trimmed.slice(separator + 1)).replace(/^["']/, '').trim();
+    return name || undefined;
+}
+/**
+ * The product a binary belongs to, read off the path it was installed at.
+ *
+ * This is the answer to the commonest kind of unhelpful row: a process called
+ * `figma_agent` described as "figma_agent". A path says which application put
+ * it there, which is the thing the reader wanted and the process name was
+ * never going to give them.
+ */
+export function applicationName(command) {
+    if (!command)
+        return null;
+    // Vendor directories are more specific than bundles: `Figma/FigmaAgent.app`
+    // is Figma's, and saying so beats repeating the helper's own name.
+    const support = /[/\\]Application Support[/\\]([^/\\]+)[/\\]/.exec(command);
+    if (support?.[1]) {
+        const name = meaningfulDirectory(support[1].replace(/\.localized$/, ''));
+        if (name)
+            return name;
+    }
+    // The outermost bundle, so a helper nested inside Visual Studio Code reports
+    // the editor rather than the helper.
+    const bundle = /([^/\\]+)\.app[/\\]/.exec(command);
+    if (bundle?.[1]) {
+        const name = meaningfulDirectory(bundle[1]);
+        if (name)
+            return name;
+    }
+    const windows = /[/\\]Program Files(?: \(x86\))?[/\\]([^/\\]+)[/\\]/i.exec(command);
+    if (windows?.[1]) {
+        const name = meaningfulDirectory(windows[1]);
+        if (name)
+            return name;
+    }
+    const unix = /[/\\](?:opt|snap)[/\\]([^/\\]+)[/\\]/.exec(command);
+    if (unix?.[1]) {
+        const name = meaningfulDirectory(unix[1]);
+        if (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.
+ * What the shape of a path says when its name says nothing: a binary under
+ * `/usr/libexec` is a system service whoever wrote it, and that is worth more
+ * to a reader than its own name repeated back at them.
+ */
+export function locationCategory(command) {
+    if (!command)
+        return null;
+    if (/^\/(?:System|usr\/libexec|sbin|usr\/sbin)\//.test(command))
+        return 'system';
+    if (/[/\\](?:LaunchDaemons|LaunchAgents)[/\\]/.test(command))
+        return 'system';
+    if (/^\/(?:lib|usr\/lib)\/systemd\//.test(command))
+        return 'system';
+    if (/[/\\]Windows[/\\]System32[/\\]/i.test(command))
+        return 'system';
+    if (/\.app[/\\]/.test(command) || /^\/Applications\//.test(command))
+        return 'desktop';
+    if (/[/\\]Program Files(?: \(x86\))?[/\\]/i.test(command))
+        return 'desktop';
+    return null;
+}
+const LOCATION_LABEL = {
+    system: 'system service',
+    desktop: 'desktop app',
+};
+/**
+ * Describe a port from everything that is knowable without asking anything to
+ * identify itself, in priority order: what the command line says it is, the
+ * application it was installed as, the well-known port registry, and finally
+ * the shape of its path.
+ *
+ * The one rule the order exists to enforce is that the description never
+ * repeats the process name. A column that says `figma_agent` next to a column
+ * that says `figma_agent` is a column that has told the reader nothing, and it
+ * is better to say so than to fill the space.
  */
 export function describe(socket) {
     const text = searchable(socket);
-    const signature = matchSignature(text);
-    const hint = projectHint(socket.command);
-    if (signature)
-        return { label: signature, hint };
+    const signature = findSignature(text);
+    const application = applicationName(socket.command);
     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 };
+    const located = locationCategory(socket.command);
+    const project = projectHint(socket.command);
+    const build = (label, source, category, hint) => {
+        const info = CATEGORY_INFO[category];
+        return {
+            label,
+            source,
+            category,
+            // "Docker Desktop (Docker)" is one fact wearing two hats. A hint only
+            // earns its brackets by saying something the label did not.
+            hint: hint !== null && redundantHint(hint, label) ? null : hint,
+            summary: signature?.summary ?? info.summary,
+            restart: signature?.restart ?? null,
+        };
+    };
+    // A named framework or daemon beats everything: it is the one source that
+    // says what the program does rather than where it came from.
+    if (signature && !signature.runtime) {
+        return build(signature.label, 'signature', signature.category, project ?? application);
+    }
+    if (registered && !registered.generic && !signature) {
+        return build(registered.label, 'registry', registered.category, project ?? application);
+    }
+    // An application name outranks a bare runtime: "Visual Studio Code (Node.js)"
+    // is the useful way round, not "Node.js (Visual Studio Code)". But a runtime
+    // installed at `Program Files\nodejs` is not an application that happens to
+    // use Node - it is Node - so a directory that only spells the runtime out
+    // again loses to the signature, which at least knows how to capitalise it.
+    if (application &&
+        !sameName(application, socket.processName) &&
+        !sameName(application, signature?.label ?? null)) {
+        return build(application, 'application', 
+        // Where it is installed beats what it is written in: once the label is
+        // the application, "Visual Studio Code - a desktop app" says more than
+        // "Visual Studio Code - a program", and the runtime moves to the hint.
+        located ?? signature?.category ?? registered?.category ?? 'desktop', project ?? signature?.label ?? null);
+    }
+    if (signature) {
+        return build(signature.label, 'signature', signature.category, project);
+    }
+    if (registered) {
+        return build(registered.label, 'registry', registered.category, project);
+    }
+    if (located) {
+        return build(LOCATION_LABEL[located] ?? null, 'location', located, project);
+    }
+    // Nothing matched. Saying nothing is the honest answer; the process name is
+    // already in its own column, and repeating it there would be a lie about how
+    // much slash-port worked out.
+    return build(null, 'none', 'unknown', project);
+}
+/**
+ * A name reduced to what it is, for comparing two of them. The extension goes
+ * first: stripping separators first turns `node.exe` into `nodeexe`, which
+ * matches nothing, and Windows then gets the duplicated columns the whole
+ * never-repeat-the-process-name rule exists to prevent.
+ */
+const bareName = (value) => value.toLowerCase().replace(/\.exe$/, '').replace(/[\s._-]/g, '');
+/** Whether two names would only say the same thing twice. */
+function sameName(candidate, other) {
+    if (!other)
+        return false;
+    return bareName(candidate) === bareName(other);
+}
+/**
+ * Whether a hint is already contained in its label. "Docker Desktop (Docker)"
+ * passes an equality test and still says one thing twice.
+ */
+export function redundantHint(hint, label) {
+    if (!label)
+        return false;
+    const [a, b] = [bareName(hint), bareName(label)];
+    return a.includes(b) || b.includes(a);
+}
+/** Loopback and wildcard binds are the ones a browser here can actually reach. */
+function reachableLocally(addresses) {
+    return addresses.some((address) => address === '*' || address === '127.0.0.1' || address === '::1' || address === 'localhost');
+}
+/**
+ * Where to point a browser, for the ports that answer one. Offered only for
+ * TCP that is reachable from this machine, because a URL you cannot open is
+ * worse than no URL at all.
+ */
+export function browserUrl(entry) {
+    if (entry.protocol !== 'tcp')
+        return null;
+    if (!reachableLocally(entry.addresses))
+        return null;
+    // The port has the last word on this. A container publishing 8080 is almost
+    // certainly HTTP whatever its image is called, and mailpit's 1025 is almost
+    // certainly not, whatever the web UI on 8025 might suggest.
+    const browsable = CATEGORY_INFO[entry.category].browsable === true || PORT_REGISTRY[entry.port]?.category === 'web';
+    if (!browsable)
+        return null;
+    const scheme = entry.port === 443 || entry.port === 8443 ? 'https' : 'http';
+    return `${scheme}://localhost:${entry.port}`;
+}
+/**
+ * Whether this can be closed, folding together what it is, who owns it, and
+ * whether a guardrail already refuses it.
+ *
+ * Guards and ownership outrank the category, because they are facts about this
+ * machine rather than guesses about the software: a Postgres you do not own is
+ * blocked whatever anybody thinks of closing databases.
+ */
+export function assessRisk(entry) {
+    if (entry.guard) {
+        return { risk: 'protected', reason: `slash-port will not kill ${entry.guard}` };
+    }
+    if (entry.elevation) {
+        return {
+            risk: 'blocked',
+            reason: `not yours to signal - ${entry.elevation}`,
+        };
+    }
+    if (entry.pid === null) {
+        return { risk: 'blocked', reason: 'there is no owner to signal' };
+    }
+    const signature = findSignature(entry.command?.trim() || entry.processName?.trim() || '');
+    const risk = signature?.risk ?? CATEGORY_INFO[entry.category].risk;
+    switch (risk) {
+        case 'safe':
+            return { risk, reason: 'yours, and as easy to start again as it was to start' };
+        case 'caution':
+            return { risk, reason: 'yours, but something may be relying on it' };
+        default:
+            return { risk: 'risky', reason: 'the system’s, not part of your work' };
+    }
 }
 /**
  * Processes that are never worth killing from here. Compared on the bare
@@ -228,8 +651,14 @@ const PROTECTED_NAMES = {
     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',
+    sshd: 'the SSH daemon - killing it locks you out of a remote machine',
     'ssh-agent': 'the SSH agent',
+    'dbus-daemon': 'the D-Bus message bus - the desktop session is built on it',
+    // `/proc/[pid]/comm` is capped at fifteen characters, so the resolver
+    // arrives with its last letter missing. Both spellings are the same daemon.
+    'systemd-resolve': 'the systemd DNS resolver - killing it takes DNS down for everything',
+    'systemd-resolved': 'the systemd DNS resolver - killing it takes DNS down for everything',
+    'systemd-logind': 'the systemd login manager - killing it ends every session on the machine',
     loginwindow: 'the macOS session',
     windowserver: 'the macOS window server',
     systemuiserver: 'the macOS session',
@@ -241,7 +670,7 @@ const PROTECTED_NAMES = {
     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',
+    svchost: 'a Windows service host - it runs many unrelated services',
     system: 'the Windows kernel',
 };
 /**
@@ -262,3 +691,68 @@ export function guardReason(socket, context = { self: process.pid, parent: proce
         return PROTECTED_NAMES[name];
     return null;
 }
+function currentOwner() {
+    return {
+        uid: typeof process.getuid === 'function' ? process.getuid() : null,
+        // A uid with no passwd entry - a container running as a bare number -
+        // makes this throw rather than return anything useful.
+        user: (() => {
+            try {
+                return userInfo().username;
+            }
+            catch {
+                return null;
+            }
+        })(),
+        platform: process.platform,
+    };
+}
+/** Windows writes `MACHINE\amin`, and is not case sensitive about either half. */
+function sameUser(a, b, platform) {
+    if (platform !== 'win32')
+        return a === b;
+    const bare = (name) => (name.split('\\').pop() ?? name).toLowerCase();
+    return bare(a) === bare(b);
+}
+/** Whether the process belongs to whoever is running slash-port. */
+export function ownedByCurrentUser(socket, context = currentOwner()) {
+    if (socket.user === null || context.user === null)
+        return false;
+    return sameUser(socket.user, context.user, context.platform);
+}
+/**
+ * What to do about a process you cannot signal. `sudo` is the answer almost
+ * everywhere and the wrong word on Windows, so the remedy is named per
+ * platform while the badge stays the same in every terminal.
+ */
+export function elevationRemedy(platform = process.platform) {
+    return platform === 'win32' ? 'an elevated terminal' : 'sudo';
+}
+/**
+ * Why a signal to this process is expected to be refused, or `null` when it
+ * should land.
+ *
+ * The scan already knows who owns every socket, so this is settled while the
+ * list is built rather than discovered after a confirmation. That is the whole
+ * point: "sudo" is worth knowing before you decide, not after. Nothing here
+ * refuses anything - `killEntry` still asks the kernel, which is the only
+ * authority on the answer.
+ */
+export function elevationReason(socket, context = currentOwner()) {
+    // Root can signal anything.
+    if (context.uid === 0)
+        return null;
+    if (socket.pid === null) {
+        // Windows reports pid 0 for the idle process rather than hiding an owner,
+        // so an unresolved pid there is not a permission wall.
+        return context.platform === 'win32' ? null : 'its owner is not visible';
+    }
+    if (socket.user === null || context.user === null)
+        return null;
+    if (sameUser(socket.user, context.user, context.platform))
+        return null;
+    // The scanners fall back to the numeric uid when /etc/passwd has no name.
+    if (context.uid !== null && socket.user === String(context.uid))
+        return null;
+    return `it belongs to ${socket.user}`;
+}