modelmux-cli 0.0.1 → 0.3.0

package/dist/docker.js

@@ -0,0 +1,294 @@
+/**
+ * The ONLY module that runs other programs: the `docker` CLI.
+ *
+ * - Commands are argument lists, never shell strings.
+ * - Every call has a timeout.
+ * - Docker's raw output is shown only with --verbose (and redacted there);
+ *   failures become `DockerError`s with a plain message and a next step.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import path from "node:path";
+import { DockerError, Interrupted, Timeout } from "./errors.js";
+import { interruptSignal } from "./interrupt.js";
+import { shellJoin } from "./text.js";
+export const DEFAULT_TIMEOUT = 60.0;
+export const PULL_TIMEOUT = 1800.0;
+export class Result {
+    args;
+    returncode;
+    stdout;
+    stderr;
+    constructor(args, returncode, stdout, stderr) {
+        this.args = args;
+        this.returncode = returncode;
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+    get ok() {
+        return this.returncode === 0;
+    }
+}
+function startDockerHint(platform) {
+    if (platform === "darwin" || platform === "win32") {
+        return "Start Docker Desktop and wait until it says it is running, then try again.";
+    }
+    return "Start the Docker service (for example: sudo systemctl start docker), then try again.";
+}
+function installHint(platform) {
+    if (platform === "darwin" || platform === "win32") {
+        return "Install Docker Desktop: https://docs.docker.com/desktop/";
+    }
+    return "Install Docker Engine: https://docs.docker.com/engine/install/";
+}
+// [pattern in Docker's stderr, message, hint factory]
+const CLASSIFIERS = [
+    [
+        /permission denied while trying to connect/i,
+        "Your user is not allowed to use Docker.",
+        () => "Add yourself to the docker group (sudo usermod -aG docker $USER), " +
+            "then log out and back in.",
+    ],
+    [
+        /cannot connect to the docker daemon|is the docker daemon running|error during connect|docker_engine.*(cannot find|not found)|failed to connect to the docker API/i,
+        "Docker is installed but not running.",
+        startDockerHint,
+    ],
+    [
+        /'compose' is not a docker command|unknown command.*compose|unknown shorthand flag: 'f' in -f/i,
+        "Docker Compose v2 is not available.",
+        () => "Install the Docker Compose plugin: https://docs.docker.com/compose/install/",
+    ],
+    [
+        /port is already allocated|address already in use|bind: .*in use/i,
+        "A port ModelMux needs is already in use.",
+        () => "Run 'modelmux doctor' to see which port, or choose another with --port.",
+    ],
+    [
+        /manifest unknown|manifest for .* not found|not found: manifest|failed to resolve reference .*: not found/i,
+        "The ModelMux image for this version was not found.",
+        () => "Check for a newer modelmux-cli (npm install -g modelmux-cli@latest), or run 'modelmux doctor'.",
+    ],
+    [
+        // GHCR answers a bare "denied" for images that do not exist or are private.
+        /pull access denied|unauthorized|error from registry: denied|denied: /i,
+        "The image registry refused access (the image may not exist or may be private).",
+        () => "Check that you can reach ghcr.io and are not logged in with expired " +
+            "credentials (docker logout ghcr.io).",
+    ],
+    [
+        /tls handshake timeout|i\/o timeout|no such host|dial tcp|network is unreachable|proxyconnect|connection refused|temporary failure in name resolution/i,
+        "Docker could not reach the internet.",
+        () => "Check your connection or proxy (HTTPS_PROXY, and Docker Desktop's proxy " +
+            "settings), then try again.",
+    ],
+    [
+        /no space left on device/i,
+        "Docker has run out of disk space.",
+        () => "Free space with 'docker system prune' (it removes unused images), then retry.",
+    ],
+];
+export function classify(stderr, command, platform = process.platform) {
+    for (const [pattern, message, hint] of CLASSIFIERS) {
+        if (pattern.test(stderr))
+            return new DockerError(message, { hint: hint(platform) });
+    }
+    return new DockerError(`Docker command failed: docker ${command}.`, {
+        hint: "Run again with --verbose to see Docker's output.",
+    });
+}
+/** Python's `shutil.which()`: the first executable `name` on PATH, or null. */
+export function which(name, env = process.env, platform = process.platform) {
+    const dirs = (env.PATH ?? env.Path ?? "").split(platform === "win32" ? ";" : ":");
+    const exts = platform === "win32"
+        ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+        : [""];
+    for (const dir of dirs) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = path.join(dir, name + ext);
+            try {
+                if (!statSync(candidate).isFile())
+                    continue;
+                if (platform !== "win32")
+                    accessSync(candidate, constants.X_OK);
+                return candidate;
+            }
+            catch {
+                // not here
+            }
+        }
+    }
+    return null;
+}
+/** Kill a child that is still running. */
+function stop(child) {
+    if (child.exitCode === null && child.signalCode === null)
+        child.kill("SIGTERM");
+}
+/** Exit code like Python's subprocess: -N when killed by signal N. */
+function exitCode(code, signal) {
+    if (code !== null)
+        return code;
+    const numbers = { SIGHUP: 1, SIGINT: 2, SIGKILL: 9, SIGTERM: 15 };
+    return signal ? -(numbers[signal] ?? 1) : -1;
+}
+export class Docker {
+    console;
+    platform;
+    spawnFn;
+    whichFn;
+    found = null;
+    constructor(console, options = {}) {
+        this.console = console;
+        this.spawnFn = options.spawn ?? nodeSpawn;
+        this.whichFn = options.which ?? ((name) => which(name));
+        this.platform = options.platform ?? process.platform;
+    }
+    get binary() {
+        if (this.found === null) {
+            const found = this.whichFn("docker");
+            if (found === null) {
+                throw new DockerError("Docker is not installed.", { hint: installHint(this.platform) });
+            }
+            this.found = found;
+        }
+        return this.found;
+    }
+    argv(args) {
+        for (const arg of args) {
+            if (typeof arg !== "string" || arg.includes("\x00")) {
+                throw new DockerError("Internal error: invalid docker argument.");
+            }
+        }
+        return [this.binary, ...args];
+    }
+    spawnError(error, file) {
+        if (error.code === "ENOENT") {
+            return new DockerError("Docker is not installed.", { hint: installHint(this.platform) });
+        }
+        if (error.code === "EACCES" || error.code === "EPERM") {
+            return new DockerError("The docker command cannot be executed.", {
+                hint: `Check permissions of ${file}.`,
+            });
+        }
+        return new DockerError(`The docker command could not be started (${error.code ?? error.message}).`);
+    }
+    /**
+     * Start `docker <args>` and settle when it exits, times out (`onTimeout`)
+     * or is interrupted (`Interrupted`); the child is stopped in both cases.
+     */
+    supervise(child, file, timeout, onTimeout) {
+        const signal = interruptSignal();
+        return new Promise((resolve, reject) => {
+            let timer;
+            const cleanup = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                signal.removeEventListener("abort", onAbort);
+            };
+            const onAbort = () => {
+                cleanup();
+                stop(child);
+                reject(new Interrupted());
+            };
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener("abort", onAbort, { once: true });
+            if (timeout !== null) {
+                timer = setTimeout(() => {
+                    cleanup();
+                    stop(child);
+                    reject(onTimeout());
+                }, timeout * 1000);
+            }
+            child.once("error", (error) => {
+                cleanup();
+                reject(this.spawnError(error, file));
+            });
+            child.once("close", (code, sig) => {
+                cleanup();
+                resolve(exitCode(code, sig));
+            });
+        });
+    }
+    /** Run `docker <args>` and capture its output. */
+    async run(args, options = {}) {
+        const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        const check = options.check ?? true;
+        const inputText = options.inputText ?? null;
+        const [file, ...rest] = this.argv(args);
+        this.console.detail("$ docker " + shellJoin(args));
+        const child = this.spawnFn(file, rest, {
+            stdio: [inputText === null ? "ignore" : "pipe", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        const out = [];
+        const err = [];
+        child.stdout?.on("data", (chunk) => out.push(chunk));
+        child.stderr?.on("data", (chunk) => err.push(chunk));
+        if (inputText !== null && child.stdin) {
+            child.stdin.on("error", () => undefined); // the program may exit before reading
+            child.stdin.end(inputText, "utf8");
+        }
+        const returncode = await this.supervise(child, file, timeout, () => new DockerError(`Docker did not finish 'docker ${args[0] ?? ""}' in time.`, {
+            hint: "Docker may be busy or stuck; check Docker is healthy and try again.",
+        }));
+        const result = new Result([...args], returncode, Buffer.concat(out).toString("utf8"), Buffer.concat(err).toString("utf8"));
+        if (result.stdout.trim())
+            this.console.detail(result.stdout.trimEnd());
+        if (result.stderr.trim())
+            this.console.detail(result.stderr.trimEnd());
+        if (check && !result.ok)
+            throw classify(result.stderr, args[0] ?? "", this.platform);
+        return result;
+    }
+    /**
+     * Run `docker <args>` attached to this terminal (logs -f, interactive login).
+     *
+     * Output is not captured, so it is the user's own Docker output.
+     */
+    async passthrough(args, options = {}) {
+        const [file, ...rest] = this.argv(args);
+        this.console.detail("$ docker " + shellJoin(args));
+        const child = this.spawnFn(file, rest, { stdio: "inherit" });
+        return this.supervise(child, file, options.timeout ?? null, () => new DockerError("Docker did not finish in time.", { hint: "Try again." }));
+    }
+    /**
+     * POSIX: run `docker <args>` (which include `-it`) with our terminal as its
+     * input, and relay its output.
+     *
+     * Docker itself puts the terminal in raw mode and gives the program a
+     * terminal, so keystrokes go straight from the user to the program without
+     * passing through this process. Only the output passes here: it is written
+     * to our terminal unchanged and never stored. `onOutput` sees each chunk
+     * and may return extra bytes to display (for example "opened your
+     * browser"). Rejects with `Timeout` after `timeout` seconds.
+     */
+    async runTty(args, options) {
+        const [file, ...rest] = this.argv(args);
+        this.console.detail("$ docker " + shellJoin(args));
+        const sink = options.stdout ?? process.stdout;
+        const child = this.spawnFn(file, rest, { stdio: ["inherit", "pipe", "inherit"] });
+        child.stdout?.on("data", (chunk) => {
+            sink.write(chunk);
+            void Promise.resolve(options.onOutput(chunk)).then((extra) => {
+                if (extra)
+                    sink.write(extra);
+            });
+        });
+        return this.supervise(child, file, options.timeout, () => new Timeout());
+    }
+    compose(project, file, args, options = {}) {
+        return this.run(["compose", "-p", project, "-f", file, ...args], options);
+    }
+    /** Docker is installed, running, and has Compose v2. Returns the server version. */
+    async checkAvailable() {
+        const server = (await this.run(["version", "--format", "{{.Server.Version}}"])).stdout.trim();
+        await this.run(["compose", "version", "--short"]);
+        return server;
+    }
+}

package/dist/errors.js

@@ -0,0 +1,49 @@
+/**
+ * Errors the CLI reports to the user.
+ *
+ * Every failure is a `CliError`: a plain message saying what went wrong, an
+ * optional hint saying what to do next, and an exit code. `main` is the only
+ * place that prints them.
+ */
+export const EXIT_OK = 0;
+export const EXIT_FAILURE = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_DOCKER = 3;
+export const EXIT_INTERRUPTED = 130;
+export class CliError extends Error {
+    hint;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = new.target.name;
+        this.hint = options.hint ?? null;
+    }
+    get exitCode() {
+        return EXIT_FAILURE;
+    }
+}
+/** The command was used incorrectly. */
+export class UsageError extends CliError {
+    get exitCode() {
+        return EXIT_USAGE;
+    }
+}
+/** Docker is missing, stopped, or a Docker command failed. */
+export class DockerError extends CliError {
+    get exitCode() {
+        return EXIT_DOCKER;
+    }
+}
+/** Ctrl+C, SIGTERM or a closed terminal (Python's KeyboardInterrupt). */
+export class Interrupted extends Error {
+    constructor() {
+        super("interrupted");
+        this.name = "Interrupted";
+    }
+}
+/** A deadline passed (Python's TimeoutError). */
+export class Timeout extends Error {
+    constructor() {
+        super("timed out");
+        this.name = "Timeout";
+    }
+}

package/dist/files.js

@@ -0,0 +1,45 @@
+/** Small, safe file writes: atomic, and private (0600) from the first byte. */
+import { randomBytes } from "node:crypto";
+import { chmodSync, closeSync, fsyncSync, openSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
+import path from "node:path";
+export const PRIVATE_MODE = 0o600;
+/**
+ * Atomically replace `file` with `data`, created with mode 0600.
+ *
+ * The temporary file is created with 0600 (never readable by others, even
+ * briefly) in the same directory, then renamed over the target.
+ */
+export function writePrivate(file, data) {
+    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${randomBytes(6).toString("hex")}.tmp`);
+    const fd = openSync(tmp, "wx", PRIVATE_MODE);
+    try {
+        try {
+            writeSync(fd, Buffer.from(data, "utf8"));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, file);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // already gone
+        }
+        throw error;
+    }
+}
+/** Make an existing file 0600 on POSIX. Returns true if it had to change. */
+export function tighten(file) {
+    if (process.platform === "win32")
+        return false;
+    const mode = statSync(file).mode & 0o777;
+    if (mode !== PRIVATE_MODE) {
+        chmodSync(file, PRIVATE_MODE);
+        return true;
+    }
+    return false;
+}

package/dist/health.js

@@ -0,0 +1,78 @@
+/** Talk to a running ModelMux server over HTTP (localhost only). */
+import http from "node:http";
+import { interruptible, throwIfInterrupted } from "./interrupt.js";
+export const LOCALHOST = "127.0.0.1";
+export function baseUrl(port) {
+    return `http://${LOCALHOST}:${port}`;
+}
+/** GET `path` on the local server. Resolves to [status, body]; status 0 if unreachable. */
+export function getJson(port, urlPath, options = {}) {
+    return interruptible(request(port, urlPath, options));
+}
+function request(port, urlPath, options = {}) {
+    const timeout = options.timeout ?? 3.0;
+    const headers = {};
+    if (options.apiKey != null)
+        headers.Authorization = `Bearer ${options.apiKey}`;
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (value) => {
+            if (!settled) {
+                settled = true;
+                resolve(value);
+            }
+        };
+        const request = http.get({ host: LOCALHOST, port, path: urlPath, headers, agent: false }, (response) => {
+            const chunks = [];
+            response.on("data", (chunk) => chunks.push(chunk));
+            response.on("error", () => done([0, null]));
+            response.on("end", () => {
+                const status = response.statusCode ?? 0;
+                const text = Buffer.concat(chunks).toString("utf8");
+                let body = null;
+                try {
+                    body = text ? JSON.parse(text) : null;
+                }
+                catch {
+                    // urllib: a 2xx with a broken body is "unreachable"; an error status keeps its code.
+                    done(status >= 200 && status < 300 ? [0, null] : [status, null]);
+                    return;
+                }
+                done([status, body]);
+            });
+        });
+        request.setTimeout(timeout * 1000, () => request.destroy(new Error("timeout")));
+        request.on("error", () => done([0, null]));
+    });
+}
+async function isReady(port) {
+    const [status, body] = await server.getJson(port, "/health/ready");
+    return (status === 200 &&
+        typeof body === "object" &&
+        body !== null &&
+        !Array.isArray(body) &&
+        body.status === "ready");
+}
+/** Sleep; Ctrl+C ends it early with `Interrupted`. */
+/** The calls commands make to a running server. Replaceable in tests. */
+export const server = {
+    getJson,
+    ready: isReady,
+};
+export const sleep = (seconds) => interruptible(new Promise((resolve) => setTimeout(resolve, seconds * 1000)));
+/** Poll `check` until it is true (true), `shouldStop` is true or time runs out (false). */
+export async function waitUntil(check, options) {
+    const interval = options.interval ?? 1.0;
+    const shouldStop = options.shouldStop ?? (() => false);
+    const pause = options.sleep ?? sleep;
+    const clock = options.clock ?? (() => performance.now() / 1000);
+    const deadline = clock() + options.timeout;
+    for (;;) {
+        throwIfInterrupted();
+        if (await check())
+            return true;
+        if ((await shouldStop()) || clock() >= deadline)
+            return false;
+        await pause(interval);
+    }
+}

package/dist/interrupt.js

@@ -0,0 +1,43 @@
+/**
+ * Ctrl+C and friends, as one signal every long-running step can watch.
+ *
+ * Python turns Ctrl+C into KeyboardInterrupt wherever the program is; Node
+ * delivers it as an event. `main` installs the SIGINT handler, and running
+ * commands, waits and HTTP polls reject with `Interrupted` when it fires, so
+ * cleanup (`finally`, removing the login helper) runs and the user sees
+ * "Cancelled.".
+ */
+import { Interrupted } from "./errors.js";
+let controller = new AbortController();
+export function interruptSignal() {
+    return controller.signal;
+}
+/** Fire the interrupt (SIGINT; SIGTERM/SIGHUP while logging in). */
+export function interrupt() {
+    controller.abort(new Interrupted());
+}
+/** Start over with a fresh signal (tests). */
+export function resetInterrupt() {
+    controller = new AbortController();
+}
+export function throwIfInterrupted() {
+    if (controller.signal.aborted)
+        throw new Interrupted();
+}
+/** Run `fn`; if the interrupt fires first, reject with `Interrupted`. */
+export function interruptible(promise) {
+    const signal = controller.signal;
+    if (signal.aborted)
+        return Promise.reject(new Interrupted());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new Interrupted());
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}

package/dist/main.js

@@ -0,0 +1,85 @@
+/**
+ * `modelmux`: set up, log in to and run ModelMux.
+ *
+ * This module only parses arguments and reports errors. Each command lives in
+ * `commands/`.
+ */
+import { ParserError, ParserExit } from "./args.js";
+import { asArgs, buildParser } from "./cli.js";
+import * as basic from "./commands/basic.js";
+import * as configCmd from "./commands/configCmd.js";
+import * as doctor from "./commands/doctor.js";
+import * as login from "./commands/login.js";
+import * as logout from "./commands/logout.js";
+import * as up from "./commands/up.js";
+import * as upgrade from "./commands/upgrade.js";
+import { Console } from "./console.js";
+import { CliError, EXIT_FAILURE, EXIT_INTERRUPTED, Interrupted } from "./errors.js";
+import { interrupt } from "./interrupt.js";
+const HANDLERS = {
+    up: up.run,
+    down: basic.down,
+    logs: basic.logs,
+    status: basic.status,
+    login: login.run,
+    logout: logout.run,
+    config: configCmd.config,
+    doctor: doctor.run,
+    upgrade: upgrade.run,
+    "key show": configCmd.keyShow,
+};
+export async function main(argv = process.argv.slice(2), streams = {}) {
+    const raw = [...argv];
+    const out = streams.out ?? process.stdout;
+    const err = streams.err ?? process.stderr;
+    // Until arguments are parsed, honour --verbose from the raw command line.
+    let console = new Console({ out, err, verbose: raw.includes("-v") || raw.includes("--verbose") });
+    try {
+        let args;
+        try {
+            args = asArgs(buildParser().parse(raw));
+        }
+        catch (error) {
+            if (error instanceof ParserExit) {
+                out.write(error.text);
+                return error.status;
+            }
+            if (error instanceof ParserError) {
+                err.write(error.text);
+                return error.status;
+            }
+            throw error;
+        }
+        console = new Console({ out, err, verbose: args.verbose, color: args.no_color ? false : null });
+        const key = args.command === "key" ? `key ${args.key_command}` : args.command;
+        const handler = HANDLERS[key];
+        if (handler === undefined)
+            throw new Error(`no handler for ${key}`);
+        return await handler(args, console);
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            console.error(error.message, error.hint);
+            return error.exitCode;
+        }
+        if (error instanceof Interrupted) {
+            console.error("Cancelled.");
+            return EXIT_INTERRUPTED;
+        }
+        console.error("Something unexpected went wrong.", "Run again with --verbose for details, and please report it if it keeps happening.");
+        if (console.verbose)
+            console.detail(error instanceof Error ? (error.stack ?? String(error)) : String(error));
+        return EXIT_FAILURE;
+    }
+}
+/** Run as the `modelmux` command. */
+export async function cli() {
+    let interrupted = false;
+    process.on("SIGINT", () => {
+        if (interrupted)
+            process.exit(EXIT_INTERRUPTED); // a second Ctrl+C: stop now
+        interrupted = true;
+        interrupt();
+    });
+    process.exitCode = await main();
+}

package/dist/paths.js

@@ -0,0 +1,51 @@
+/**
+ * Where the CLI keeps its own files.
+ *
+ * | OS      | Directory                                          |
+ * |---------|----------------------------------------------------|
+ * | Linux   | `$XDG_CONFIG_HOME/modelmux` (`~/.config/modelmux`) |
+ * | macOS   | `~/Library/Application Support/modelmux`           |
+ * | Windows | `%APPDATA%\modelmux`                               |
+ *
+ * `MODELMUX_CLI_HOME` overrides it (tests, portable setups). The directory
+ * holds only small files: `config.json`, `secrets.env` (mode 0600) and the
+ * generated `compose.yaml`. Logins never live here: they stay in Docker
+ * volumes. The same directory as the Python CLI, so both share one setup.
+ */
+import { chmodSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+export const APP_NAME = "modelmux";
+export const OVERRIDE_ENV = "MODELMUX_CLI_HOME";
+function expandUser(value, home) {
+    if (value === "~")
+        return home;
+    if (value.startsWith("~/") || value.startsWith("~\\"))
+        return path.join(home, value.slice(2));
+    return value;
+}
+export function configDir(env = process.env, platform = process.platform, home = homedir()) {
+    const override = env[OVERRIDE_ENV];
+    if (override)
+        return expandUser(override, home);
+    const p = platform === "win32" ? path.win32 : path.posix;
+    let base;
+    if (platform === "win32") {
+        base = env.APPDATA ? env.APPDATA : p.join(home, "AppData", "Roaming");
+    }
+    else if (platform === "darwin") {
+        base = p.join(home, "Library", "Application Support");
+    }
+    else {
+        const xdg = env.XDG_CONFIG_HOME;
+        base = xdg && path.posix.isAbsolute(xdg) ? xdg : p.join(home, ".config");
+    }
+    return p.join(base, APP_NAME);
+}
+/** Create `dir` if needed; on POSIX make it accessible to the owner only. */
+export function ensurePrivateDir(dir) {
+    mkdirSync(dir, { recursive: true });
+    if (process.platform !== "win32")
+        chmodSync(dir, 0o700);
+    return dir;
+}

package/dist/ports.js

@@ -0,0 +1,25 @@
+/** Is a local port free? (Checked with a socket bind: no extra processes.) */
+import net from "node:net";
+import { LOCALHOST } from "./health.js";
+/**
+ * True unless another program is listening on `host:port`.
+ *
+ * Ports in TIME_WAIT (for example right after `modelmux down`) count as free,
+ * as they do for Docker: on POSIX Node binds with `SO_REUSEADDR`, which
+ * ignores TIME_WAIT but still fails against a live listener. On Windows Node
+ * binds exclusively, so a port in use is never "stolen".
+ */
+function isFree(port, host = LOCALHOST) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.unref();
+        server.once("error", () => resolve(false));
+        server.listen({ host, port, exclusive: true }, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+/** Replaceable in tests. */
+export const ports = {
+    portFree: isFree,
+};