portless-studio 0.1.1 → 0.1.3

package/dist/server/application/terminals.js

@@ -23,6 +23,8 @@ export class TerminalManager {
     #graceMs;
     #maxTerminals;
     #namingTimeoutMs;
+    #processTree;
+    #homeDir;
     #entries = new Map();
     #watchers = new Set();
     /** Folders a local program ran a terminal in. */
@@ -30,6 +32,8 @@ export class TerminalManager {
     #nextId = 1;
     #stopWorkspaceWatch;
     #naming = false;
+    #refreshingPorts = false;
+    #portsAgain = false;
     constructor(options) {
         this.#spawner = options.spawner;
         this.#workspace = options.workspace;
@@ -39,6 +43,8 @@ export class TerminalManager {
         this.#graceMs = options.graceMs ?? DEFAULT_GRACE_MS;
         this.#maxTerminals = options.maxTerminals ?? DEFAULT_MAX_TERMINALS;
         this.#namingTimeoutMs = options.namingTimeoutMs ?? DEFAULT_NAMING_TIMEOUT_MS;
+        this.#processTree = options.processTree;
+        this.#homeDir = options.homeDir;
     }
     get mode() {
         return this.#spawner.mode;
@@ -53,7 +59,21 @@ export class TerminalManager {
     /** Calls `onChange` when a terminal starts, ends, is named or closes. */
     watch(onChange) {
         this.#watchers.add(onChange);
-        return () => this.#watchers.delete(onChange);
+        this.#updateWorkspaceWatch();
+        return () => {
+            this.#watchers.delete(onChange);
+            this.#updateWorkspaceWatch();
+        };
+    }
+    /** Gives the terminal a name of its own; an empty one gives back the default title. */
+    rename(id, title) {
+        const entry = this.#entries.get(id);
+        if (!entry)
+            return notFound(id);
+        const wanted = title.trim().slice(0, MAX_TITLE_CHARS);
+        entry.info = { ...entry.info, title: wanted || entry.defaultTitle };
+        this.#publishStatus(entry);
+        return ok({ ...entry.info });
     }
     async create(request, origin) {
         if (this.#entries.size >= this.#maxTerminals) {
@@ -71,14 +91,20 @@ export class TerminalManager {
         const cols = readSize(request.cols, DEFAULT_COLS);
         const rows = readSize(request.rows, DEFAULT_ROWS);
         const naming = readNaming(request.name);
-        const title = (request.title?.trim() || command.value || "shell").slice(0, MAX_TITLE_CHARS);
+        const defaultTitle = (command.value || this.#spawner.shellName || "shell").slice(0, MAX_TITLE_CHARS);
+        const title = request.title?.trim().slice(0, MAX_TITLE_CHARS) || defaultTitle;
+        const project = await this.#projectOf(cwd.value);
         const entry = {
+            defaultTitle,
             info: {
                 id,
                 title,
                 cwd: cwd.value,
                 command: command.value ?? "",
-                project: await this.#projectOf(cwd.value),
+                project: project?.name ?? null,
+                worktree: project?.worktree ?? null,
+                branch: project?.branch ?? null,
+                ports: [],
                 status: "running",
                 exitCode: null,
                 startedAt: this.#now(),
@@ -117,7 +143,11 @@ export class TerminalManager {
         this.#entries.set(id, entry);
         if (naming)
             this.#startNaming(entry);
+        else
+            this.#updateWorkspaceWatch();
         this.#changed();
+        if (this.#watchers.size > 0)
+            void this.#refreshPorts();
         return ok({ ...entry.info });
     }
     input(id, text) {
@@ -157,6 +187,9 @@ export class TerminalManager {
         entry.info = { ...entry.info, status: "running", exitCode: null, endedAt: null };
         entry.info.startedAt = this.#now();
         this.#publishStatus(entry);
+        this.#updateWorkspaceWatch();
+        if (this.#watchers.size > 0)
+            void this.#refreshPorts();
         return ok({ ...entry.info });
     }
     /** Closes the terminal; its command, if still running, is killed. */
@@ -170,7 +203,7 @@ export class TerminalManager {
             entry.process.kill();
         entry.process = null;
         entry.watchers.clear();
-        this.#updateNamingWatch();
+        this.#updateWorkspaceWatch();
         this.#changed();
         return ok(undefined);
     }
@@ -232,7 +265,9 @@ export class TerminalManager {
                     message: "The command ended before it opened a port.",
                 });
             }
+            entry.info.ports = [];
             this.#publishStatus(entry);
+            this.#updateWorkspaceWatch();
         });
         return ok(undefined);
     }
@@ -270,6 +305,8 @@ export class TerminalManager {
             watcher();
     }
     async #resolveFolder(request, origin) {
+        if (origin.picked)
+            return this.#pickedFolder(request.cwd);
         if (typeof request.project === "string" && request.project !== "" && !request.cwd) {
             const folder = await this.#projectFolder(request.project);
             if (folder === null) {
@@ -294,6 +331,24 @@ export class TerminalManager {
             return ok(folder);
         return err(appError("path_not_allowed", "Terminals run only in project folders Studio shows. Start it from the CLI to use another folder."));
     }
+    /** A folder typed in the page's picker: any existing folder, with `~` as the home folder. */
+    #pickedFolder(typed) {
+        if (typeof typed !== "string" || typed.trim() === "") {
+            return err(appError("invalid_request", "Give the folder to open."));
+        }
+        let wanted = typed.trim();
+        if (this.#homeDir && (wanted === "~" || /^~[\\/]/.test(wanted))) {
+            wanted = `${this.#homeDir}${wanted.slice(1)}`;
+        }
+        if (!isAbsolute(wanted)) {
+            return err(appError("invalid_request", "The folder must be an absolute path or start with ~."));
+        }
+        const folder = this.#folders.directory(wanted);
+        if (folder === null) {
+            return err(appError("path_not_allowed", `${wanted} is not a folder on this machine.`));
+        }
+        return ok(folder);
+    }
     async #projectFolder(name) {
         const { routes, detected } = await this.#workspace.snapshot();
         for (const item of [...routes, ...detected]) {
@@ -303,6 +358,7 @@ export class TerminalManager {
         }
         return null;
     }
+    /** The project whose folder holds `cwd`, the innermost one when several do. */
     async #projectOf(cwd) {
         const { routes, detected } = await this.#workspace.snapshot();
         let best = null;
@@ -310,10 +366,70 @@ export class TerminalManager {
             const path = item.project?.path;
             if (!item.project || !path || !this.#folders.contains(path, cwd))
                 continue;
-            if (!best || path.length > best.length)
-                best = { name: item.project.name, length: path.length };
+            if (!best?.path || path.length > best.path.length)
+                best = item.project;
+        }
+        return best;
+    }
+    /**
+     * Links every listening process to the running terminal it descends from, and publishes the
+     * terminals whose ports changed. Calls that arrive while one runs make it run once more.
+     */
+    async #refreshPorts() {
+        const tree = this.#processTree;
+        if (!tree)
+            return;
+        if (this.#refreshingPorts) {
+            this.#portsAgain = true;
+            return;
+        }
+        this.#refreshingPorts = true;
+        try {
+            do {
+                this.#portsAgain = false;
+                await this.#linkPorts(tree);
+            } while (this.#portsAgain);
+        }
+        finally {
+            this.#refreshingPorts = false;
+        }
+    }
+    async #linkPorts(tree) {
+        const running = [...this.#entries.values()].filter((entry) => entry.info.status === "running" && entry.info.pid !== null);
+        if (running.length === 0)
+            return;
+        const { routes, detected } = await this.#workspace.snapshot();
+        const listeners = new Map();
+        for (const item of detected) {
+            if (item.pid !== null)
+                listeners.set(item.port, { port: item.port, route: null, url: null });
+        }
+        const pids = new Map();
+        for (const item of detected)
+            if (item.pid !== null)
+                pids.set(item.port, item.pid);
+        for (const item of routes) {
+            if (item.listenerPid === undefined)
+                continue;
+            pids.set(item.port, item.listenerPid);
+            listeners.set(item.port, { port: item.port, route: item.name, url: item.url });
+        }
+        const ancestry = new Map();
+        for (const pid of new Set(pids.values())) {
+            ancestry.set(pid, await tree.ancestors(pid).catch(() => []));
+        }
+        for (const entry of running) {
+            const pid = entry.info.pid;
+            const ports = [...pids]
+                .filter(([, listener]) => listener === pid || ancestry.get(listener)?.includes(pid ?? -1))
+                .map(([port]) => listeners.get(port))
+                .filter((port) => port !== undefined)
+                .sort((a, b) => a.port - b.port);
+            if (JSON.stringify(ports) === JSON.stringify(entry.info.ports))
+                continue;
+            entry.info = { ...entry.info, ports };
+            this.#publishStatus(entry);
         }
-        return best?.name ?? null;
     }
     async #portsInUse() {
         const { routes, detected } = await this.#workspace.snapshot();
@@ -330,18 +446,29 @@ export class TerminalManager {
             this.#publishStatus(entry);
         }, this.#namingTimeoutMs);
         entry.namingTimer.unref?.();
-        this.#updateNamingWatch();
+        this.#updateWorkspaceWatch();
     }
     #waitingEntries() {
         return [...this.#entries.values()].filter((entry) => entry.info.naming?.state === "waiting");
     }
-    /** Watches the workspace, which keeps Studio scanning, only while a terminal waits for a port. */
-    #updateNamingWatch() {
-        const waiting = this.#waitingEntries().length > 0;
-        if (waiting && !this.#stopWorkspaceWatch) {
-            this.#stopWorkspaceWatch = this.#workspace.watch(() => void this.#nameNewPorts());
+    /**
+     * Watches the workspace, which keeps Studio scanning, only while a terminal waits for a port,
+     * or while someone watches the list and a terminal runs, so the ports it opened stay current.
+     */
+    #updateWorkspaceWatch() {
+        const linking = this.#processTree !== undefined &&
+            this.#watchers.size > 0 &&
+            [...this.#entries.values()].some((entry) => entry.info.status === "running");
+        const needed = linking || this.#waitingEntries().length > 0;
+        if (needed && !this.#stopWorkspaceWatch) {
+            this.#stopWorkspaceWatch = this.#workspace.watch(() => {
+                if (this.#waitingEntries().length > 0)
+                    void this.#nameNewPorts();
+                if (this.#watchers.size > 0)
+                    void this.#refreshPorts();
+            });
         }
-        else if (!waiting && this.#stopWorkspaceWatch) {
+        else if (!needed && this.#stopWorkspaceWatch) {
             this.#stopWorkspaceWatch();
             this.#stopWorkspaceWatch = undefined;
         }
@@ -357,7 +484,7 @@ export class TerminalManager {
         }
         finally {
             this.#naming = false;
-            this.#updateNamingWatch();
+            this.#updateWorkspaceWatch();
         }
     }
     async #nameFor(entry, routes, detected) {

package/dist/server/infrastructure/system/docker-containers.js

@@ -0,0 +1,64 @@
+import { parseDockerPs } from "../../../core/ports/docker-container.js";
+import { err, ok } from "../../../core/result.js";
+import { appError } from "../../application/app-error.js";
+import { execute } from "../portless/portless-cli.js";
+/** A scan runs every few seconds; one `docker ps` serves the scans in between. */
+const FRESH_MS = 3000;
+/** Docker that is stopped or refuses this user is asked again less often. */
+const UNAVAILABLE_MS = 15_000;
+/** No `docker` on PATH: asked again in case it gets installed. */
+const MISSING_MS = 60_000;
+const LIST_TIMEOUT_MS = 2000;
+/** `docker stop` waits up to 10 seconds for the container before it kills it. */
+const STOP_TIMEOUT_MS = 30_000;
+const LIST_ARGS = ["ps", "--format", "{{json .}}"];
+const defaultRun = (args, timeoutMs) => execute("docker", args, { timeoutMs });
+/**
+ * Reads running containers with `docker ps`, which works the same with Docker Engine on Linux and
+ * with Docker Desktop, OrbStack or Colima on macOS and Windows. Any failure reads as no containers.
+ */
+export class DockerContainers {
+    #run;
+    #now;
+    #last = null;
+    #reading = null;
+    constructor(options = {}) {
+        this.#run = options.run ?? defaultRun;
+        this.#now = options.now ?? Date.now;
+    }
+    read() {
+        const last = this.#last;
+        if (last && this.#now() - last.at < maxAge(last.reading))
+            return Promise.resolve(last.reading);
+        this.#reading ??= this.#list().then((reading) => {
+            this.#last = { reading, at: this.#now() };
+            this.#reading = null;
+            return reading;
+        });
+        return this.#reading;
+    }
+    async stop(name) {
+        const outcome = await this.#run(["stop", name], STOP_TIMEOUT_MS).catch(() => null);
+        // The next read lists the containers again instead of showing the stopped one.
+        this.#last = null;
+        if (outcome?.exitCode === 0)
+            return ok(undefined);
+        const printed = outcome?.combined.trim() ?? "";
+        return err(appError("command_failed", printed || `docker stop ${name} did not finish.`, `docker stop ${name}`));
+    }
+    async #list() {
+        const outcome = await this.#run(LIST_ARGS, LIST_TIMEOUT_MS).catch(() => null);
+        if (outcome === null)
+            return { state: "unavailable" };
+        if (outcome.missing)
+            return { state: "missing" };
+        if (outcome.exitCode !== 0)
+            return { state: "unavailable" };
+        return { state: "ok", containers: parseDockerPs(outcome.stdout) };
+    }
+}
+function maxAge(reading) {
+    if (reading.state === "ok")
+        return FRESH_MS;
+    return reading.state === "missing" ? MISSING_MS : UNAVAILABLE_MS;
+}

package/dist/server/infrastructure/system/doctor-facts.js

@@ -1,3 +1,4 @@
+import { request } from "node:http";
 import { createServer } from "node:net";
 import * as path from "node:path";
 import { DEFAULT_CONFIG } from "../../../core/config/studio-config.js";
@@ -99,19 +100,22 @@ export async function proxyPidsAmong(platform, io, pids) {
 /** Gathers the facts the doctor checks. Each part is read once; nothing is changed. */
 export async function collectDoctorFacts(options) {
     const { platform, registry, configStore } = options;
-    const [state, proxyPid, stored, proxyProcesses, loginService, systemNotifier] = await Promise.all([
+    const [state, proxyPid, stored, proxyProcesses, loginService, systemNotifier, docker, port80] = await Promise.all([
         registry.readSnapshot(),
         registry.proxyPid(),
         configStore.read(),
         listProxyProcesses(platform, options.io, options.uid),
         options.loginService ? options.loginService() : Promise.resolve(null),
         options.systemNotifier ? options.systemNotifier() : Promise.resolve(undefined),
+        options.docker ? dockerFacts(options.docker) : Promise.resolve(undefined),
+        options.lowPort ? options.lowPort(80) : Promise.resolve(undefined),
     ]);
     const config = stored.ok ? stored.value : DEFAULT_CONFIG;
     const proxyOwner = state.proxy.running && proxyPid !== null
         ? await options.processes.ownerOf(proxyPid)
         : "unknown";
     const https = state.proxy.running ? state.proxy.https : config.proxyHttps;
+    const shortUrls = await options.shortUrls?.(config).catch(() => undefined);
     return {
         platform,
         portless: state.portless,
@@ -128,8 +132,46 @@ export async function collectDoctorFacts(options) {
         loginService,
         ...(systemNotifier === undefined ? {} : { systemNotifier }),
         ...(options.routesFile ? { routesFile: options.routesFile() } : {}),
+        ...(docker === undefined ? {} : { docker }),
+        ...(port80 === undefined ? {} : { port80 }),
+        ...(shortUrls === undefined ? {} : { shortUrls }),
     };
 }
+/** Only how many containers run reaches the doctor, never their names. */
+async function dockerFacts(read) {
+    const reading = await read().catch(() => ({ state: "unavailable" }));
+    return reading.state === "ok"
+        ? { state: "ok", containers: reading.containers.length }
+        : { state: reading.state };
+}
+/**
+ * Tries to listen on a loopback port and closes it at once, without sudo: `denied` when the system
+ * refuses this user (Linux below `ip_unprivileged_port_start`), `in-use` when a program holds it.
+ */
+export function testBind(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", (error) => resolve(error.code === "EADDRINUSE" ? "in-use" : "denied"));
+        server.listen({ port, host: "127.0.0.1", exclusive: true }, () => server.close(() => resolve("free")));
+    });
+}
+/**
+ * Whether a request to this loopback port reaches a portless proxy (it sends `X-Portless`), as it
+ * does through Studio's short-URL forwarder.
+ */
+export function reachesPortless(port, timeoutMs = 1000) {
+    return new Promise((resolve) => {
+        const req = request({ host: "127.0.0.1", port, method: "HEAD", path: "/", timeout: timeoutMs, agent: false }, (res) => {
+            res.resume();
+            req.destroy();
+            resolve(res.headers["x-portless"] !== undefined);
+        });
+        req.on("timeout", () => req.destroy());
+        req.on("error", () => resolve(false));
+        req.on("close", () => resolve(false));
+        req.end();
+    });
+}
 /** Paths are built for the platform the facts describe, not the one running the code. */
 function pathsOf(platform) {
     return platform === "win32" ? path.win32 : path.posix;

package/dist/server/infrastructure/system/ephemeral-ports.js

@@ -0,0 +1,62 @@
+import { DEFAULT_EPHEMERAL_RANGES } from "../../../core/ports/helper-ports.js";
+/** Reads `/proc/sys/net/ipv4/ip_local_port_range`: two numbers separated by whitespace. */
+export function parseLinuxPortRange(text) {
+    const [first, last] = text.trim().split(/\s+/).map(Number);
+    return validRange(first, last);
+}
+/** Reads `sysctl -n net.inet.ip.portrange.first net.inet.ip.portrange.last`: one number per line. */
+export function parseSysctlPortRange(text) {
+    return parseLinuxPortRange(text);
+}
+/** Reads `netsh int ipv4 show dynamicport tcp`: a start port and a number of ports. */
+export function parseNetshDynamicPorts(text) {
+    const numbers = [...text.matchAll(/:\s*(\d+)/g)].map((match) => Number(match[1]));
+    const [start, count] = numbers;
+    if (start === undefined || count === undefined || count < 1)
+        return null;
+    return validRange(start, start + count - 1);
+}
+function validRange(first, last) {
+    if (first === undefined || last === undefined)
+        return null;
+    if (!Number.isInteger(first) || !Number.isInteger(last))
+        return null;
+    if (first < 1 || last > 65535 || first > last)
+        return null;
+    return { first, last };
+}
+/**
+ * The range the system hands out for port 0, read once and kept: it only changes when someone
+ * edits a kernel setting. Falls back to the platform default when it cannot be read.
+ */
+export function ephemeralRangeReader(platform, io) {
+    let reading = null;
+    return () => {
+        reading ??= readEphemeralRange(platform, io).catch(() => fallbackRange(platform));
+        return reading;
+    };
+}
+async function readEphemeralRange(platform, io) {
+    let range = null;
+    if (platform === "linux") {
+        range = parseLinuxPortRange(io.readFile("/proc/sys/net/ipv4/ip_local_port_range") ?? "");
+    }
+    else if (platform === "darwin") {
+        const out = await io.run("sysctl", [
+            "-n",
+            "net.inet.ip.portrange.first",
+            "net.inet.ip.portrange.last",
+        ]);
+        range = parseSysctlPortRange(out.stdout);
+    }
+    else if (platform === "win32") {
+        const out = await io.run("netsh", ["int", "ipv4", "show", "dynamicport", "tcp"]);
+        range = parseNetshDynamicPorts(out.stdout);
+    }
+    return range ?? fallbackRange(platform);
+}
+function fallbackRange(platform) {
+    if (platform === "darwin" || platform === "win32")
+        return DEFAULT_EPHEMERAL_RANGES[platform];
+    return DEFAULT_EPHEMERAL_RANGES.linux;
+}

package/dist/server/infrastructure/system/port-forwarder.js

@@ -0,0 +1,78 @@
+import { createServer, connect as tcpConnect } from "node:net";
+import { err, ok } from "../../../core/result.js";
+/** Loopback on IPv4 and IPv6, because browsers may resolve `name.localhost` to either. */
+export const LOOPBACK_HOSTS = ["127.0.0.1", "::1"];
+/** A system without IPv6 cannot bind `::1`; that is not a failure when IPv4 works. */
+const NO_ADDRESS = new Set(["EADDRNOTAVAIL", "EAFNOSUPPORT"]);
+/**
+ * Listens on loopback and pipes every TCP connection to the target, byte for byte. Piping the
+ * connection rather than re-sending requests keeps the Host header, the method, streamed bodies,
+ * keep-alive and WebSocket upgrades exactly as the browser sent them; portless then adds its own
+ * `X-Forwarded-*` headers from that Host. Never asks for more rights: a refused bind is reported.
+ */
+export async function startForwarder(options) {
+    const hosts = options.hosts ?? LOOPBACK_HOSTS;
+    const targetHost = options.targetHost ?? "127.0.0.1";
+    const sockets = new Set();
+    const servers = [];
+    let port = options.port;
+    const handle = (client) => {
+        const upstream = tcpConnect({ host: targetHost, port: options.targetPort });
+        sockets.add(client);
+        sockets.add(upstream);
+        client.setNoDelay(true);
+        upstream.setNoDelay(true);
+        const finish = () => {
+            client.destroy();
+            upstream.destroy();
+            sockets.delete(client);
+            sockets.delete(upstream);
+        };
+        client.on("error", finish);
+        upstream.on("error", finish);
+        client.on("close", finish);
+        upstream.on("close", finish);
+        client.pipe(upstream);
+        upstream.pipe(client);
+    };
+    const close = async () => {
+        for (const socket of sockets)
+            socket.destroy();
+        sockets.clear();
+        await Promise.all(servers.map((server) => new Promise((resolve) => server.close(() => resolve()))));
+    };
+    for (const [index, host] of hosts.entries()) {
+        const server = createServer(handle);
+        const bound = await new Promise((resolve) => {
+            server.once("error", resolve);
+            server.listen({ port, host, exclusive: true }, () => {
+                server.off("error", resolve);
+                resolve(null);
+            });
+        });
+        if (bound === null) {
+            servers.push(server);
+            // Port 0 picks a free port on the first host; the others use that same one.
+            if (index === 0)
+                port = server.address().port;
+            continue;
+        }
+        if (index > 0 && NO_ADDRESS.has(bound.code ?? ""))
+            continue;
+        await close();
+        return err(failureOf(bound, port));
+    }
+    return ok({ port, close });
+}
+function failureOf(error, port) {
+    if (error.code === "EADDRINUSE") {
+        return { reason: "in-use", message: `port ${port} is in use by another program.` };
+    }
+    if (error.code === "EACCES" || error.code === "EPERM") {
+        return {
+            reason: "denied",
+            message: `this system does not let this user listen on port ${port} without sudo.`,
+        };
+    }
+    return { reason: "failed", message: `could not listen on port ${port}: ${error.message}` };
+}

package/dist/server/infrastructure/system/process-runner.js

@@ -64,7 +64,8 @@ export function resolveWindowsCommand(bin, lookup) {
     return null;
 }
 const found = new Map();
-function nodeWindowsLookup() {
+/** PATH, PATHEXT and file checks of this machine, for `resolveWindowsCommand`. */
+export function nodeWindowsLookup() {
     const pathValue = process.env.PATH ?? process.env.Path ?? "";
     return {
         pathDirs: pathValue

package/dist/server/infrastructure/system/system-port-scanner.js

@@ -1,5 +1,6 @@
 import { request } from "node:http";
 import { STUDIO_HEADER } from "../../../core/api/contract.js";
+import { isDebuggerVersionInfo } from "../../../core/ports/helper-ports.js";
 import { listLinuxPorts } from "./linux-ports.js";
 import { listMacosPorts } from "./macos-ports.js";
 import { nodeSystemIo } from "./system-io.js";
@@ -30,6 +31,7 @@ export class SystemPortScanner {
     #timeoutMs;
     #pidByPort = new Map();
     #answers = new Map();
+    #debuggers = new Map();
     constructor(list, timeoutMs = PROBE_TIMEOUT_MS) {
         this.#list = list;
         this.#timeoutMs = timeoutMs;
@@ -44,13 +46,28 @@ export class SystemPortScanner {
         }
         this.#pidByPort = new Map(ports.map((port) => [port.port, port.pid]));
         // Forget answers for processes that are gone, so the cache does not grow forever.
-        for (const key of this.#answers.keys()) {
-            const [port, pid] = key.split(":");
-            if (String(this.#pidByPort.get(Number(port))) !== pid)
-                this.#answers.delete(key);
+        for (const cache of [this.#answers, this.#debuggers]) {
+            for (const key of cache.keys()) {
+                const [port, pid] = key.split(":");
+                if (String(this.#pidByPort.get(Number(port))) !== pid)
+                    cache.delete(key);
+            }
         }
         return ports;
     }
+    /** Asked once per port and process, like `answersHttp`. */
+    probeDebugger(port) {
+        const pid = this.#pidByPort.get(port) ?? null;
+        if (pid === null)
+            return probeDebuggerPort(port, this.#timeoutMs);
+        const key = `${port}:${pid}`;
+        let answer = this.#debuggers.get(key);
+        if (!answer) {
+            answer = probeDebuggerPort(port, this.#timeoutMs);
+            this.#debuggers.set(key, answer);
+        }
+        return answer;
+    }
     answersHttp(port) {
         const pid = this.#pidByPort.get(port) ?? null;
         // Without a pid we cannot tell a restarted process apart, so the answer is not kept.
@@ -65,6 +82,49 @@ export class SystemPortScanner {
         return answer;
     }
 }
+/** A `/json/version` answer is a few hundred bytes; anything longer is not a debugger. */
+const MAX_VERSION_BODY = 16_384;
+/**
+ * Asks `GET /json/version`, which Node's inspector and Chrome DevTools answer with JSON naming
+ * the browser and protocol. `other` when the port answered something else, `unknown` when
+ * nothing answered in time.
+ */
+export async function probeDebuggerPort(port, timeoutMs = PROBE_TIMEOUT_MS) {
+    for (const host of LOOPBACK_HOSTS) {
+        const body = await getText(host, port, "/json/version", timeoutMs);
+        if (body === null)
+            continue;
+        try {
+            return isDebuggerVersionInfo(JSON.parse(body)) ? "debugger" : "other";
+        }
+        catch {
+            return "other";
+        }
+    }
+    return "unknown";
+}
+function getText(host, port, path, timeoutMs) {
+    return new Promise((resolve) => {
+        const options = { host, port, method: "GET", path, timeout: timeoutMs, agent: false };
+        const req = request(options, (res) => {
+            let body = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                body += chunk;
+                if (body.length <= MAX_VERSION_BODY)
+                    return;
+                resolve("");
+                req.destroy();
+            });
+            res.on("end", () => resolve(body));
+            res.on("error", () => resolve(body));
+        });
+        req.on("timeout", () => req.destroy());
+        req.on("error", () => resolve(null));
+        req.on("close", () => resolve(null));
+        req.end();
+    });
+}
 /**
  * True when anything on loopback answers `HEAD /` with an HTTP response, whatever its status,
  * unless the response comes from a Portless Studio.