portless-studio 0.1.0 → 0.1.2

package/dist/core/ports/docker-container.js

@@ -0,0 +1,85 @@
+// Docker's own rule for container names; it also keeps names from reading as flags.
+const CONTAINER_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+// A host binding such as `0.0.0.0:8000-8002->8000-8002/tcp` or `[::]:8080->80/tcp`.
+const BINDING = /:(\d+)(?:-(\d+))?->\d+(?:-\d+)?\/(tcp|udp|sctp)$/;
+// A range wider than this is a mistake in the compose file, not something to probe port by port.
+const MAX_RANGE = 1000;
+export function isContainerName(value) {
+    return CONTAINER_NAME.test(value);
+}
+/** Host TCP ports from the `Ports` column; unpublished ports (`80/tcp`) and UDP are skipped. */
+export function parsePublishedPorts(text) {
+    const ports = new Set();
+    for (const part of text.split(",")) {
+        const match = BINDING.exec(part.trim());
+        if (match?.[3] !== "tcp")
+            continue;
+        const first = Number(match[1]);
+        const last = match[2] === undefined ? first : Number(match[2]);
+        if (last < first || last - first >= MAX_RANGE)
+            continue;
+        for (let port = first; port <= last; port += 1) {
+            if (port >= 1 && port <= 65535)
+                ports.add(port);
+        }
+    }
+    return [...ports].sort((a, b) => a - b);
+}
+/** Reads `docker ps --format '{{json .}}'`: one JSON object per line. Bad lines are skipped. */
+export function parseDockerPs(text) {
+    const containers = [];
+    for (const raw of text.split("\n")) {
+        const row = parseLine(raw.trim());
+        if (row === null)
+            continue;
+        const name = (stringField(row, "Names") ?? "").split(",")[0]?.trim() ?? "";
+        if (!isContainerName(name))
+            continue;
+        const labels = parseLabels(stringField(row, "Labels") ?? "");
+        containers.push({
+            name,
+            image: stringField(row, "Image") ?? "",
+            composeProject: labels.get("com.docker.compose.project") || null,
+            composeService: labels.get("com.docker.compose.service") || null,
+            ports: parsePublishedPorts(stringField(row, "Ports") ?? ""),
+        });
+    }
+    return containers;
+}
+/**
+ * What the name template reads for a container: the compose service as the package and the
+ * compose project as the repository (`api.acme`), else the container name as the folder.
+ */
+export function containerProjectInfo(container) {
+    return {
+        packageName: container.composeService,
+        repoName: container.composeProject,
+        folderName: container.name,
+        worktreeName: null,
+    };
+}
+function parseLine(line) {
+    if (!line.startsWith("{"))
+        return null;
+    try {
+        const value = JSON.parse(line);
+        return typeof value === "object" && value !== null ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stringField(row, key) {
+    const value = row[key];
+    return typeof value === "string" ? value : null;
+}
+/** `a=1,b=2`; label values with commas are rare and only the compose labels matter here. */
+function parseLabels(text) {
+    const labels = new Map();
+    for (const pair of text.split(",")) {
+        const index = pair.indexOf("=");
+        if (index > 0)
+            labels.set(pair.slice(0, index).trim(), pair.slice(index + 1).trim());
+    }
+    return labels;
+}

package/dist/core/routes/route.js

@@ -19,10 +19,22 @@ export function nameFromHostname(hostname, tlds) {
     }
     return hostname;
 }
-/** Builds the browser URL; omits the port when it is the protocol default. */
+/**
+ * Builds the browser URL on the port names open on: the public port when there is one, else the
+ * proxy's. Omits the port when it is the protocol default.
+ */
 export function routeUrl(hostname, proxy) {
     const scheme = proxy.https ? "https" : "http";
     const defaultPort = proxy.https ? 443 : 80;
-    const port = proxy.port === null || proxy.port === defaultPort ? "" : `:${proxy.port}`;
+    const open = proxy.publicPort ?? proxy.port;
+    const port = open === null || open === defaultPort ? "" : `:${open}`;
     return `${scheme}://${hostname}${port}`;
 }
+/** Points every route URL at `publicPort`, the port Studio forwards to the proxy; null keeps them. */
+export function withPublicPort(state, publicPort) {
+    if (publicPort === null)
+        return state;
+    const proxy = { ...state.proxy, publicPort };
+    const routes = state.routes.map((route) => ({ ...route, url: routeUrl(route.hostname, proxy) }));
+    return { ...state, proxy, routes };
+}

package/dist/core/updates/version.js

@@ -0,0 +1,62 @@
+/** The command that installs the latest release globally, shown with every update notice. */
+export const UPDATE_COMMAND = "npm i -g portless-studio";
+const VERSION = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+/**
+ * Compares two semver versions: negative when `a` is older, positive when newer, 0 when equal.
+ * A prerelease sorts before its release. Returns null when either is not a version.
+ */
+export function compareVersions(a, b) {
+    const left = VERSION.exec(a.trim());
+    const right = VERSION.exec(b.trim());
+    if (!left || !right)
+        return null;
+    for (let index = 1; index <= 3; index++) {
+        const difference = Number(left[index]) - Number(right[index]);
+        if (difference !== 0)
+            return Math.sign(difference);
+    }
+    return comparePrereleases(left[4], right[4]);
+}
+/** True when `latest` is a newer version than `current`; false for anything unreadable. */
+export function isNewerVersion(latest, current) {
+    const order = compareVersions(latest, current);
+    return order !== null && order > 0;
+}
+/** The line Studio prints on start when a newer release exists. */
+export function updateMessage(current, latest) {
+    return (`A new version of portless-studio is available: ${current} -> ${latest}. ` +
+        `Update with: ${UPDATE_COMMAND}`);
+}
+function comparePrereleases(a, b) {
+    if (a === b)
+        return 0;
+    if (a === undefined)
+        return 1;
+    if (b === undefined)
+        return -1;
+    const left = a.split(".");
+    const right = b.split(".");
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const x = left[index];
+        const y = right[index];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xNumeric = /^\d+$/.test(x);
+        const yNumeric = /^\d+$/.test(y);
+        if (xNumeric && yNumeric) {
+            const difference = Number(x) - Number(y);
+            if (difference !== 0)
+                return Math.sign(difference);
+        }
+        else if (xNumeric !== yNumeric) {
+            // Numeric identifiers sort before alphanumeric ones.
+            return xNumeric ? -1 : 1;
+        }
+        else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}

package/dist/server/application/auto-namer.js

@@ -8,6 +8,8 @@ export class AutoNamer {
     #log;
     #hooks;
     #attempted = new Set();
+    /** In how many scans in a row each port and process pair showed up unnamed. */
+    #streaks = new Map();
     constructor(registry, log, hooks = {}) {
         this.#registry = registry;
         this.#log = log;
@@ -15,6 +17,8 @@ export class AutoNamer {
     }
     /** Returns how many ports got a name. */
     async name(detected) {
+        const stableScans = this.#hooks.stableScans ?? 2;
+        const streaks = new Map();
         let named = 0;
         for (const port of detected) {
             if (port.suggestedName === null)
@@ -22,13 +26,23 @@ export class AutoNamer {
             const key = `${port.port}:${port.pid}`;
             if (this.#attempted.has(key))
                 continue;
+            const streak = (this.#streaks.get(key) ?? 0) + 1;
+            streaks.set(key, streak);
+            if (streak < stableScans)
+                continue;
             this.#attempted.add(key);
             if (await this.#nameOne(port.port, port.suggestedName))
                 named += 1;
         }
+        // A port missing from this scan starts counting again when it comes back.
+        this.#streaks = streaks;
         return named;
     }
     async #nameOne(port, suggested) {
+        // The scan is a few seconds old; portless may have registered the port since.
+        const { routes } = await this.#registry.readSnapshot();
+        if (routes.some((route) => route.port === port))
+            return false;
         let lastError = "";
         // The second name keeps two servers of the same project apart: `web.acme-4321`.
         for (const candidate of [suggested, `${suggested}-${port}`]) {

package/dist/server/application/container-source.js

@@ -0,0 +1,19 @@
+import { isContainerName } from "../../core/ports/docker-container.js";
+import { err, ok } from "../../core/result.js";
+import { appError } from "./app-error.js";
+/**
+ * Stops a container from its row. Only a container the last `docker ps` listed can be stopped, so
+ * the endpoint cannot be used to stop anything else.
+ */
+export async function stopContainer(name, source) {
+    if (!isContainerName(name)) {
+        return err(appError("invalid_request", "That is not a Docker container name."));
+    }
+    const reading = await source.read();
+    const listed = reading.state === "ok" && reading.containers.some((item) => item.name === name);
+    if (!listed) {
+        return err(appError("process_not_allowed", `Container ${name} is not one Studio shows; it may have stopped.`));
+    }
+    const stopped = await source.stop(name);
+    return stopped.ok ? ok({ name }) : stopped;
+}

package/dist/server/application/doctor.js

@@ -9,11 +9,14 @@ export function diagnose(facts) {
         pushIf(checks, proxyOwnerCheck(facts));
         pushIf(checks, proxyCountCheck(facts));
         pushIf(checks, httpsTrustCheck(facts));
+        pushIf(checks, routesFileCheck(facts));
+        pushIf(checks, shorterUrlsCheck(facts));
     }
     checks.push(studioPortCheck(facts));
     pushIf(checks, loginServiceCheck(facts));
     pushIf(checks, safariCheck(facts));
     pushIf(checks, notificationsCheck(facts));
+    pushIf(checks, dockerCheck(facts));
     return checks;
 }
 export function createDoctorService(deps) {
@@ -41,15 +44,59 @@ async function runAction(action, facts, deps) {
         return deps.controlProxy("start");
     if (action === "restart-proxy")
         return deps.controlProxy("restart");
-    const saved = await deps.updateConfig({ ...facts.config, proxyPort: 1355, proxyHttps: false });
+    if (action === "use-short-urls")
+        return turnOnShortUrls(facts, deps);
+    const http = { ...facts.config, proxyPort: 1355, proxyHttps: false };
+    return applyProxyConfig(http, "HTTP on port 1355", facts, deps);
+}
+/**
+ * Turns `shortUrls` on and checks that Studio really listens on port 80. The proxy keeps its
+ * port and keeps running; when the listen fails, the previous config comes back.
+ */
+async function turnOnShortUrls(facts, deps) {
+    const config = { ...facts.config, shortUrls: true };
+    const saved = await deps.updateConfig(config);
     if (!saved.ok)
         return saved;
-    if (!facts.proxy.running)
-        return deps.controlProxy("start");
-    if (facts.proxyOwner === "you")
-        return deps.controlProxy("restart");
-    return ok(`Saved HTTP on port 1355. Stop the current proxy with \`${stopProxyAsAdminCommand(facts.platform)}\` ` +
-        `${adminWords(facts.platform)}, then start the new one from the proxy menu.`);
+    const status = await deps.syncShortUrls(config);
+    if (status.state === "listening") {
+        return ok("Names now open as http://name.localhost: Studio forwards port " +
+            `${status.port} to the proxy on port ${status.target}.`);
+    }
+    await deps.updateConfig(facts.config);
+    await deps.syncShortUrls(facts.config);
+    const why = status.state === "failed" ? `${status.message} ` : "";
+    const code = status.state === "failed" && status.reason === "in-use" ? "port_in_use" : "command_failed";
+    return err(appError(code, `${why}Studio kept the previous settings, so names still open with ` +
+        `:${facts.config.proxyPort}.`));
+}
+/**
+ * Saves the proxy settings, then starts or restarts the proxy with them when Studio may. When
+ * that start fails, the previous settings come back and a proxy that was running starts again on
+ * them, so names keep working.
+ */
+async function applyProxyConfig(config, what, facts, deps) {
+    const saved = await deps.updateConfig(config);
+    if (!saved.ok)
+        return saved;
+    if (facts.proxy.running && facts.proxyOwner !== "you") {
+        return ok(`Saved ${what}. Stop the current proxy with \`${stopProxyAsAdminCommand(facts.platform)}\` ` +
+            `${adminWords(facts.platform)}, then start the new one from the proxy menu.`);
+    }
+    const started = await deps.controlProxy(facts.proxy.running ? "restart" : "start");
+    if (started.ok)
+        return started;
+    await deps.updateConfig(facts.config);
+    let back = "Studio went back to the previous settings.";
+    if (facts.proxy.running) {
+        const again = await deps.controlProxy("start");
+        if (again.ok) {
+            back =
+                "Studio went back to the previous settings and started the proxy on port " +
+                    `${facts.config.proxyPort} again.`;
+        }
+    }
+    return err({ ...started.error, message: `${started.error.message} ${back}` });
 }
 function portlessCheck({ portless }) {
     if (portless.installed) {
@@ -105,8 +152,9 @@ function proxyRunningCheck(facts) {
         status: "warn",
         title: "The proxy is not running",
         detail: needsSudo
-            ? `Names do not open until it runs. Port ${config.proxyPort} needs sudo, so Studio cannot ` +
-                "start it; HTTP on port 1355 needs nothing."
+            ? `Names do not open until it runs. portless asks for sudo below port 1024, so Studio ` +
+                `cannot start it on port ${config.proxyPort}; HTTP on port 1355 needs nothing, and short ` +
+                "URLs drop the port from names."
             : "Names do not open until it runs.",
         fix: needsSudo
             ? { label: "Use HTTP on port 1355", action: "use-http-1355" }
@@ -145,6 +193,31 @@ function proxyOwnerCheck({ proxy, proxyPid, proxyOwner, platform, }) {
         },
     };
 }
+/** portless is before 1.0 and may change its state files; Studio says so instead of hiding routes. */
+function routesFileCheck({ routesFile, portless }) {
+    if (!routesFile)
+        return null;
+    const version = portless.version ? `portless ${portless.version}` : "This portless";
+    const advice = "Update portless-studio, or report it with the portless version.";
+    if (routesFile.state === "unexpected") {
+        return {
+            id: "routes-file",
+            status: "warn",
+            title: "Studio cannot read routes.json",
+            detail: `${version} saved it in a format this version of Studio does not know, so no route is ` +
+                `shown. ${advice}`,
+        };
+    }
+    if (routesFile.state !== "ok" || routesFile.unreadable === 0)
+        return null;
+    return {
+        id: "routes-file",
+        status: "warn",
+        title: `Studio cannot read ${routesFile.unreadable} of the ${routesFile.entries} routes portless saved`,
+        detail: `${version} may have changed the format of routes.json, so those routes are not shown. ` +
+            advice,
+    };
+}
 function proxyCountCheck({ proxyProcesses, platform }) {
     if (proxyProcesses === null || proxyProcesses.length < 2)
         return null;
@@ -301,6 +374,149 @@ function notificationsCheck({ config, systemNotifier }) {
         fix: { label: "Install notify-send", command: "sudo apt install libnotify-bin" },
     };
 }
+const UNPRIVILEGED_PORT_SETTING = "net.ipv4.ip_unprivileged_port_start=80";
+/**
+ * Short URLs drop the port number from every name (`http://name.localhost`). Studio itself listens
+ * on port 80 and forwards to the proxy, only when a test bind shows this user may listen there
+ * without sudo; it never changes the system.
+ */
+function shorterUrlsCheck(facts) {
+    const { proxy, config, platform, port80, shortUrls } = facts;
+    const https = proxy.running ? proxy.https : config.proxyHttps;
+    if (https) {
+        if (!config.shortUrls)
+            return null;
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Short URLs work over HTTP only",
+            detail: "The proxy serves HTTPS, so names keep their port. Switch the proxy to HTTP to open " +
+                "them as http://name.localhost.",
+        };
+    }
+    const port = (proxy.running ? proxy.port : null) ?? config.proxyPort;
+    if (port === 80) {
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Names open without a port number",
+            detail: "The proxy uses port 80, so names open as http://name.localhost.",
+        };
+    }
+    if (shortUrls?.state === "listening") {
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Names open without a port number",
+            detail: `Studio listens on port ${shortUrls.port} and forwards to the proxy on port ` +
+                `${shortUrls.target}, so names open as http://name.localhost.`,
+        };
+    }
+    const now = `Names open as http://name.localhost:${port}`;
+    if (config.shortUrls)
+        return failedShortUrlsCheck(facts, now);
+    if (port80 === undefined)
+        return null;
+    if (port80 === "free") {
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Shorter URLs: port 80 is available",
+            detail: `${now}. This user can listen on port 80 without sudo, so Studio can listen there and ` +
+                `forward to the proxy, and names open as http://name.localhost. The proxy stays on ` +
+                `port ${port}.`,
+            fix: { label: "Use short URLs", action: "use-short-urls" },
+        };
+    }
+    if (port80 === "in-use") {
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Port 80 is taken by another program",
+            detail: `${now}. Stop the program on port 80 to drop the port number from names.`,
+        };
+    }
+    if (platform !== "linux") {
+        return {
+            id: "shorter-urls",
+            status: "ok",
+            title: "Shorter URLs: this system does not allow port 80",
+            detail: `${now}. This user cannot listen on port 80 here, so names keep the port.`,
+        };
+    }
+    return {
+        id: "shorter-urls",
+        status: "ok",
+        title: "Shorter URLs need a one-time system setting",
+        detail: `${now}. ${SYSCTL_ADVICE} Then run the checks again and choose Use short URLs.`,
+        fix: SYSCTL_FIX,
+    };
+}
+/** `shortUrls` is on and Studio does not listen: names still work, with the port. */
+function failedShortUrlsCheck(facts, now) {
+    const { platform, port80, shortUrls } = facts;
+    const reason = shortUrls?.state === "failed" ? shortUrls.reason : port80;
+    const retry = port80 === "free"
+        ? { fix: { label: "Try port 80 again", action: "use-short-urls" } }
+        : {};
+    if (reason === "in-use") {
+        return {
+            id: "shorter-urls",
+            status: "warn",
+            title: "Short URLs are on, but port 80 is taken by another program",
+            detail: `${now}. Stop the program on port 80, then run the checks again.`,
+            ...retry,
+        };
+    }
+    if (reason === "denied" && platform === "linux" && port80 !== "free") {
+        return {
+            id: "shorter-urls",
+            status: "warn",
+            title: "Short URLs are on, but Linux does not let this user listen on port 80",
+            detail: `${now}. ${SYSCTL_ADVICE} Then run the checks again and choose Try port 80 again.`,
+            fix: SYSCTL_FIX,
+        };
+    }
+    return {
+        id: "shorter-urls",
+        status: "warn",
+        title: "Short URLs are on, but Studio does not listen on port 80",
+        detail: shortUrls?.state === "failed"
+            ? `${now}. Studio could not listen there: ${shortUrls.message}`
+            : `${now}. Studio is not running, or has not tried port 80 yet.`,
+        ...retry,
+    };
+}
+const SYSCTL_ADVICE = "Linux lets only root listen on ports below 1024. The command lets every user on this machine " +
+    "listen on port 80 and up until the next restart; Studio never runs it. To keep it after a " +
+    `restart, also run \`echo '${UNPRIVILEGED_PORT_SETTING}' | sudo tee ` +
+    "/etc/sysctl.d/99-portless-studio.conf`.";
+const SYSCTL_FIX = {
+    label: "Allow port 80 until the next restart",
+    command: `sudo sysctl -w ${UNPRIVILEGED_PORT_SETTING}`,
+};
+/** Information only: without Docker, container ports simply do not show. */
+function dockerCheck({ docker }) {
+    if (docker === undefined || docker.state === "missing")
+        return null;
+    if (docker.state === "ok") {
+        const count = docker.containers === 1 ? "1 running container" : `${docker.containers} running containers`;
+        return {
+            id: "docker",
+            status: "ok",
+            title: "Studio reads Docker containers",
+            detail: `docker ps lists ${count}; the ports they publish show under Detected.`,
+        };
+    }
+    return {
+        id: "docker",
+        status: "ok",
+        title: "Studio cannot read Docker containers",
+        detail: "The docker command is installed, but docker ps did not answer: Docker is not running, " +
+            "or this user may not use it (on Linux, the docker group). Ports of containers do not " +
+            "show under Detected until it answers.",
+    };
+}
 function startCommand(config) {
     const tls = config.proxyHttps ? "--https" : "--no-tls";
     return `portless proxy start --port ${config.proxyPort} ${tls}`;

package/dist/server/application/port-discovery.js

@@ -1,4 +1,5 @@
 import { projectOf, suggestName, } from "../../core/ports/detected-port.js";
+import { containerProjectInfo } from "../../core/ports/docker-container.js";
 /**
  * Listening ports a person would want to name: they answer HTTP, have no portless route, and are
  * not Studio, the proxy or something the config ignores. Sorted by port.
@@ -10,17 +11,59 @@ export async function discoverPorts(scanner, projects, context) {
         ...context.config.ignoredPorts,
     ]);
     const ignored = context.config.ignoredProcesses.map((name) => name.toLowerCase());
+    const published = containerPorts(context.containers ?? [], skippedPorts, ignored);
     // A port whose process we cannot read belongs to another user or the system (printing, DNS),
-    // never to a dev server this person started.
+    // never to a dev server this person started. A container's port is shown as the container.
     const candidates = (await scanner.scan()).filter((port) => port.pid !== null &&
         !skippedPorts.has(port.port) &&
+        !published.has(port.port) &&
         !isIgnoredProcess(port.processName, ignored));
+    const fromContainers = [...published];
     // Probes run in parallel; a port that never answers costs its timeout once, not per port.
-    const answers = await Promise.all(candidates.map((port) => scanner.answersHttp(port.port)));
-    return candidates
-        .filter((port, index) => answers[index] && isDevServer(port, projects))
-        .map((port) => toDetected(port, projects, context.config.nameTemplate))
-        .sort((a, b) => a.port - b.port);
+    const [answers, containerAnswers] = await Promise.all([
+        Promise.all(candidates.map((port) => scanner.answersHttp(port.port))),
+        Promise.all(fromContainers.map(([port]) => scanner.answersHttp(port))),
+    ]);
+    const template = context.config.nameTemplate;
+    return [
+        ...candidates
+            .filter((port, index) => answers[index] && isDevServer(port, projects))
+            .map((port) => toDetected(port, projects, template)),
+        ...fromContainers
+            .filter((_, index) => containerAnswers[index])
+            .map(([port, container]) => containerDetected(port, container, template)),
+    ].sort((a, b) => a.port - b.port);
+}
+/** Published port -> container, without the ports the filters skip. */
+function containerPorts(containers, skippedPorts, ignored) {
+    const ports = new Map();
+    if (isIgnoredProcess(CONTAINER_PROCESS, ignored))
+        return ports;
+    for (const container of containers) {
+        for (const port of container.ports) {
+            if (!skippedPorts.has(port) && !ports.has(port))
+                ports.set(port, container);
+        }
+    }
+    return ports;
+}
+/** What a container's row shows as its process, and what `ignoredProcesses` matches. */
+const CONTAINER_PROCESS = "docker";
+function containerDetected(port, container, nameTemplate) {
+    const project = container.composeProject;
+    return {
+        port,
+        pid: null,
+        processName: CONTAINER_PROCESS,
+        cwd: null,
+        suggestedName: suggestName(containerProjectInfo(container), nameTemplate, port),
+        ...(project === null ? {} : { project: { name: project, worktree: null } }),
+        container: {
+            name: container.name,
+            image: container.image,
+            composeProject: project,
+        },
+    };
 }
 // Interpreters dev servers run on. Anything else counts only when it was built inside the
 // project, like `target/debug/api`, so editors, chat apps and background tools stay out.

package/dist/server/application/proxy-start-check.js

@@ -0,0 +1,83 @@
+import { err, ok } from "../../core/result.js";
+import { appError } from "./app-error.js";
+const DEFAULT_ATTEMPTS = 12;
+const DEFAULT_INTERVAL_MS = 250;
+/**
+ * The same registry, but a proxy start counts only once the proxy portless recorded is alive and
+ * the port listens. `portless proxy start` can exit 0 while another proxy, with another state
+ * directory, already holds the port; without this check Studio would report a start that never
+ * happened.
+ */
+export function confirmProxyStarts(registry, deps) {
+    return {
+        readSnapshot: () => registry.readSnapshot(),
+        watch: (onChange) => registry.watch(onChange),
+        createAlias: (name, port, force) => registry.createAlias(name, port, force),
+        removeAlias: (name) => registry.removeAlias(name),
+        installPortless: () => registry.installPortless(),
+        stopProxy: () => registry.stopProxy(),
+        proxyPid: () => registry.proxyPid(),
+        startProxy: (port, https) => startConfirmed(registry, deps, port, https),
+    };
+}
+async function startConfirmed(registry, deps, port, https) {
+    const ownPid = await registry.proxyPid().catch(() => null);
+    const before = await holderOf(deps, port);
+    // Our own proxy may still hold the port for a moment after a stop, during a restart.
+    if (before !== null && before !== "unknown" && (before.pid === null || before.pid !== ownPid)) {
+        return err(await inUse(deps, port, before));
+    }
+    const started = await registry.startProxy(port, https);
+    if (!started.ok)
+        return started;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const attempts = deps.attempts ?? DEFAULT_ATTEMPTS;
+    let holder = null;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (attempt > 0)
+            await sleep(deps.intervalMs ?? DEFAULT_INTERVAL_MS);
+        holder = await holderOf(deps, port);
+        const { proxy } = await registry.readSnapshot();
+        if (!proxy.running)
+            continue;
+        // Without a port list, a live recorded pid is all there is to go on.
+        if (holder === "unknown")
+            return ok(undefined);
+        if (holder !== null && (await isOurs(registry, deps, holder)))
+            return ok(undefined);
+    }
+    if (holder !== null && holder !== "unknown")
+        return err(await inUse(deps, port, holder));
+    return err(appError("command_failed", `portless reported a start, but no proxy listens on port ${port}. Run \`portless proxy ` +
+        "start` in a terminal to see why."));
+}
+/** The listener is the proxy portless recorded, or a portless proxy it forked. */
+async function isOurs(registry, deps, holder) {
+    if (holder.pid === null)
+        return true;
+    if (holder.pid === (await registry.proxyPid().catch(() => null)))
+        return true;
+    return (await proxyPidsAmong(deps, [holder.pid])).has(holder.pid);
+}
+async function holderOf(deps, port) {
+    try {
+        return (await deps.scan()).find((item) => item.port === port) ?? null;
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function inUse(deps, port, holder) {
+    const { pid } = holder;
+    if (pid !== null && (await proxyPidsAmong(deps, [pid])).has(pid)) {
+        return appError("port_in_use", `port ${port} is already used by another portless proxy (pid ${pid}) that keeps its state ` +
+            "in a different folder. Stop that proxy, or set proxyPort to a free port.");
+    }
+    const who = [holder.processName, pid === null ? "" : `pid ${pid}`].filter(Boolean).join(", ");
+    return appError("port_in_use", `port ${port} is in use by another process${who === "" ? "" : ` (${who})`}.`);
+}
+async function proxyPidsAmong(deps, pids) {
+    if (!deps.proxyPids)
+        return new Set();
+    return deps.proxyPids(pids).catch(() => new Set());
+}