@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/system/node/src/node-command-runner.js

@@ -0,0 +1,143 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { spawn } from "node:child_process";
+import { closeSync, openSync, writeSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { signalProcessGroup } from "./process-group.js";
+const GROUPS = process.platform !== "win32";
+export class NodeCommandRunner {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    run(request) {
+        if (!Number.isFinite(request.timeoutMs) || request.timeoutMs <= 0)
+            return Promise.reject(new Error(`${request.command}: a positive timeoutMs is required`));
+        const limit = request.maxOutputBytes ?? this.options.maxOutputBytes ?? 16 * 1024 * 1024;
+        if (!Number.isFinite(limit) || limit <= 0)
+            return Promise.reject(new Error(`${request.command}: a positive maxOutputBytes is required`));
+        if (request.outputFile !== undefined && !isAbsolute(request.outputFile))
+            return Promise.reject(new Error(`${request.command}: outputFile must be absolute`));
+        const drainMs = this.options.drainMs ?? 2_000;
+        const env = { ...(this.options.environment ?? process.env) };
+        for (const [name, value] of Object.entries(request.env ?? {})) {
+            if (value === undefined)
+                delete env[name];
+            else
+                env[name] = value;
+        }
+        const label = [request.command, ...request.args].join(" ");
+        return new Promise((resolve, reject) => {
+            if (request.signal?.aborted) {
+                reject(new Error(`${label}: aborted before it started`));
+                return;
+            }
+            let outputFd;
+            try {
+                if (request.outputFile !== undefined)
+                    outputFd = openSync(request.outputFile, "a", 0o600);
+            }
+            catch (error) {
+                reject(error);
+                return;
+            }
+            let child;
+            try {
+                child = spawn(request.command, [...request.args], { cwd: request.cwd, env, stdio: ["pipe", "pipe", "pipe"], detached: GROUPS });
+            }
+            catch (error) {
+                if (outputFd !== undefined)
+                    closeSync(outputFd);
+                reject(error);
+                return;
+            }
+            const out = [];
+            const err = [];
+            let outBytes = 0;
+            let errBytes = 0;
+            let failure;
+            let exited = false;
+            let closed = false;
+            let drain;
+            const kill = () => {
+                if (child.pid === undefined)
+                    return;
+                if (GROUPS)
+                    try {
+                        if (signalProcessGroup(child.pid, "SIGKILL"))
+                            return;
+                    }
+                    catch {
+                    }
+                if (!exited)
+                    child.kill("SIGKILL");
+            };
+            const stop = (error) => {
+                failure ??= error;
+                kill();
+            };
+            const timer = setTimeout(() => stop(new Error(`${label}: timed out after ${request.timeoutMs} ms`)), request.timeoutMs);
+            const onAbort = () => stop(new Error(`${label}: aborted`));
+            request.signal?.addEventListener("abort", onAbort, { once: true });
+            const collect = (into, stream) => (chunk) => {
+                if (outputFd !== undefined) {
+                    try {
+                        for (let offset = 0; offset < chunk.length;) {
+                            const written = writeSync(outputFd, chunk, offset, chunk.length - offset);
+                            if (written <= 0)
+                                throw new Error(`${label}: outputFile accepted no bytes`);
+                            offset += written;
+                        }
+                    }
+                    catch (error) {
+                        stop(error);
+                    }
+                    return;
+                }
+                if (stream === "stdout")
+                    outBytes += chunk.length;
+                else
+                    errBytes += chunk.length;
+                if (outBytes > limit || errBytes > limit)
+                    stop(new Error(`${label}: ${stream} exceeded ${limit} bytes`));
+                else
+                    into.push(chunk);
+            };
+            child.stdout.on("data", collect(out, "stdout"));
+            child.stderr.on("data", collect(err, "stderr"));
+            child.stdin.on("error", () => { });
+            child.stdin.end(request.input ?? "");
+            child.once("error", (error) => stop(error));
+            child.once("exit", (code, signal) => {
+                exited = true;
+                drain = setTimeout(() => setImmediate(() => {
+                    if (closed)
+                        return;
+                    failure ??= new Error(`${label}: exited with ${code === null ? `signal ${signal}` : `code ${code}`}, but its output was still open ${drainMs} ms later (a descendant holds it); its process group was killed`);
+                    kill();
+                    child.stdout.destroy();
+                    child.stderr.destroy();
+                }), drainMs);
+            });
+            child.once("close", (code, signal) => {
+                closed = true;
+                if (outputFd !== undefined)
+                    try {
+                        closeSync(outputFd);
+                    }
+                    catch (error) {
+                        failure ??= error;
+                    }
+                clearTimeout(timer);
+                clearTimeout(drain);
+                request.signal?.removeEventListener("abort", onAbort);
+                if (failure)
+                    reject(failure);
+                else if (code === null)
+                    reject(new Error(`${label}: ended by ${signal}`));
+                else
+                    resolve({ code, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8") });
+            });
+        });
+    }
+}

package/adapters/system/node/src/node-conditioned-links.d.ts

@@ -0,0 +1,4 @@
+import type { ConditionedLink, ConditionedLinkRequest, ConditionedLinks } from "@parity/product-lab/ports/system";
+export declare class NodeConditionedLinks implements ConditionedLinks {
+    open({ port, target }: ConditionedLinkRequest): Promise<ConditionedLink>;
+}

package/adapters/system/node/src/node-conditioned-links.js

@@ -0,0 +1,140 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createServer, connect } from "node:net";
+import { LoopbackUrl } from "@parity/product-lab/domain";
+import { ConditionedWire, ONLINE } from "@parity/product-lab/domain/conditions";
+import { RequestHead } from "./request-head.js";
+const DEFAULT_PORT = { "ws:": 80, "http:": 80, "wss:": 443, "https:": 443 };
+export class NodeConditionedLinks {
+    async open({ port, target }) {
+        const parsed = URL.canParse(target) ? new URL(target) : undefined;
+        if (!parsed || !(parsed.protocol in DEFAULT_PORT))
+            throw new Error(`A conditioned link carries to a ws, wss, http or https endpoint, not ${target}`);
+        if (!LoopbackUrl.isLoopbackHost(parsed.hostname))
+            throw new Error(`A conditioned link carries to a local endpoint; ${parsed.origin} is not loopback, and a public endpoint is never proxied`);
+        const link = new NodeConditionedLink(target, parsed, port, { host: parsed.hostname.replace(/^\[|\]$/g, ""), port: Number(parsed.port || DEFAULT_PORT[parsed.protocol]) });
+        await link.listen();
+        return link;
+    }
+}
+class NodeConditionedLink {
+    port;
+    upstream;
+    url;
+    origin;
+    condition = ONLINE;
+    connections = new Set();
+    server;
+    plain;
+    constructor(text, target, port, upstream) {
+        this.port = port;
+        this.upstream = upstream;
+        this.plain = target.protocol === "http:" || target.protocol === "ws:";
+        this.origin = `${target.protocol}//127.0.0.1:${port}`;
+        this.url = this.origin + (text.startsWith(target.origin) ? text.slice(target.origin.length) : target.pathname + target.search + target.hash);
+        this.server = createServer({ allowHalfOpen: true }, (client) => this.accept(client));
+    }
+    listen() {
+        return new Promise((resolve, reject) => {
+            this.server.once("error", reject);
+            this.server.listen(this.port, "127.0.0.1", () => {
+                this.server.off("error", reject);
+                resolve();
+            });
+        });
+    }
+    network(condition) {
+        this.condition = condition;
+        if (condition.kind === "offline")
+            for (const cut of [...this.connections])
+                cut();
+    }
+    close() {
+        for (const cut of [...this.connections])
+            cut();
+        return new Promise((resolve) => this.server.close(() => resolve()));
+    }
+    accept(client) {
+        if (this.condition.kind === "offline") {
+            client.destroy();
+            return;
+        }
+        const server = connect({ ...this.upstream, allowHalfOpen: true });
+        const up = new LinkWire("up", () => this.condition);
+        const down = new LinkWire("down", () => this.condition);
+        const cut = () => {
+            this.connections.delete(cut);
+            up.stop();
+            down.stop();
+            client.destroy();
+            server.destroy();
+        };
+        this.connections.add(cut);
+        const carry = (from, to, wire) => {
+            from.on("data", (chunk) => {
+                if (!wire.push(chunk.byteLength, () => to.write(chunk)))
+                    cut();
+            });
+            from.on("end", () => {
+                if (!wire.push(0, () => to.end()))
+                    cut();
+            });
+        };
+        if (this.plain) {
+            const head = new RequestHead(`${this.upstream.host.includes(":") ? `[${this.upstream.host}]` : this.upstream.host}:${this.upstream.port}`);
+            client.on("data", (chunk) => {
+                const rewritten = head.take(chunk);
+                if (rewritten.byteLength && !up.push(rewritten.byteLength, () => server.write(rewritten)))
+                    cut();
+            });
+            client.on("end", () => {
+                if (!up.push(0, () => server.end()))
+                    cut();
+            });
+        }
+        else
+            carry(client, server, up);
+        carry(server, client, down);
+        client.on("error", cut);
+        server.on("error", cut);
+        let closed = 0;
+        const closing = () => {
+            if (++closed === 2)
+                cut();
+        };
+        client.on("close", closing);
+        server.on("close", closing);
+    }
+}
+class LinkWire {
+    condition;
+    wire;
+    timer;
+    constructor(direction, condition) {
+        this.condition = condition;
+        this.wire = new ConditionedWire(direction);
+    }
+    push(bytes, deliver) {
+        if (!this.wire.send(this.condition(), performance.now(), bytes, deliver))
+            return false;
+        this.drain();
+        return true;
+    }
+    stop() {
+        this.wire.clear();
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    drain() {
+        const now = performance.now();
+        for (const deliver of this.wire.due(now))
+            deliver();
+        const next = this.wire.next();
+        if (next === undefined || this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.drain();
+        }, next - now);
+    }
+}

package/adapters/system/node/src/node-document-headers.d.ts

@@ -0,0 +1,28 @@
+import { type FramingDocument } from "@parity/product-lab/domain";
+import type { DocumentHeadersReader } from "@parity/product-lab/ports/system";
+export declare const DOCUMENT_HEADERS_TIMEOUT_MS = 3000;
+/** The adapter's injectable request seam; only status, headers and body cancellation are used. */
+export type DocumentHeaderFetch = (url: string, options: {
+    signal: AbortSignal;
+    redirect: "manual";
+    headers: {
+        accept: string;
+    };
+}) => Promise<{
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    readonly body?: {
+        cancel(): Promise<void>;
+    } | null;
+}>;
+/** One bounded header read; no document body is consumed and no nonlocal redirect is contacted. */
+export declare class NodeDocumentHeaders implements DocumentHeadersReader {
+    private readonly request;
+    constructor(request?: DocumentHeaderFetch);
+    read(url: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<FramingDocument>;
+    private headers;
+}

package/adapters/system/node/src/node-document-headers.js

@@ -0,0 +1,38 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { LoopbackUrl, framingHeaders } from "@parity/product-lab/domain";
+export const DOCUMENT_HEADERS_TIMEOUT_MS = 3_000;
+const MAX_REDIRECTS = 5;
+export class NodeDocumentHeaders {
+    request;
+    constructor(request = fetch) {
+        this.request = request;
+    }
+    async read(url, options = {}) {
+        const deadline = AbortSignal.timeout(DOCUMENT_HEADERS_TIMEOUT_MS);
+        const signal = options.signal ? AbortSignal.any([deadline, options.signal]) : deadline;
+        signal.throwIfAborted();
+        return new Promise((resolve, reject) => {
+            const aborted = () => reject(signal.reason);
+            signal.addEventListener("abort", aborted, { once: true });
+            void this.headers(url, signal).then(resolve, reject).finally(() => signal.removeEventListener("abort", aborted));
+        });
+    }
+    async headers(url, signal) {
+        let current = url;
+        for (let hop = 0;; hop++) {
+            signal.throwIfAborted();
+            if (!LoopbackUrl.test(current, { protocols: ["http:", "https:"] }))
+                throw new Error(`The app's document redirects to ${new URL(current).origin}, which is not a loopback address: not asked`);
+            const response = await this.request(current, { signal, redirect: "manual", headers: { accept: "text/html" } });
+            await response.body?.cancel().catch(() => undefined);
+            signal.throwIfAborted();
+            const location = response.status >= 300 && response.status < 400 ? response.headers.get("location") : null;
+            if (!location)
+                return { url: current, headers: framingHeaders((name) => response.headers.get(name)) ?? {} };
+            if (hop >= MAX_REDIRECTS)
+                throw new Error(`The app's document redirected more than ${MAX_REDIRECTS} times`);
+            current = new URL(location, current).href;
+        }
+    }
+}

package/adapters/system/node/src/node-http-probe.d.ts

@@ -0,0 +1,21 @@
+import type { HttpProbe, HttpProbeResult } from "@parity/product-lab/ports/system";
+/** The adapter's injectable request seam; only the status and body cancellation are used. */
+export type HttpProbeFetch = (url: string, options: {
+    signal: AbortSignal;
+    method: "HEAD";
+    redirect: "manual";
+}) => Promise<{
+    readonly status: number;
+    readonly body?: {
+        cancel(): Promise<void>;
+    } | null;
+}>;
+/** One HEAD request per probe, bounded by `timeoutMs`; a redirect is an answer and is not followed. */
+export declare class NodeHttpProbe implements HttpProbe {
+    private readonly request;
+    constructor(request?: HttpProbeFetch);
+    probe(url: string, options: {
+        readonly timeoutMs: number;
+        readonly signal?: AbortSignal;
+    }): Promise<HttpProbeResult>;
+}

package/adapters/system/node/src/node-http-probe.js

@@ -0,0 +1,39 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+function why(error, timedOut, timeoutMs) {
+    if (timedOut)
+        return `no answer within ${timeoutMs} ms`;
+    const cause = error instanceof Error && error.cause && typeof error.cause === "object" ? error.cause : undefined;
+    const code = typeof cause?.code === "string" ? cause.code : undefined;
+    if (code === "ECONNREFUSED")
+        return "connection refused";
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN")
+        return "host not found";
+    if (code === "ECONNRESET")
+        return "connection reset";
+    if (typeof cause?.message === "string")
+        return cause.message;
+    return error instanceof Error ? error.message : String(error);
+}
+export class NodeHttpProbe {
+    request;
+    constructor(request = fetch) {
+        this.request = request;
+    }
+    async probe(url, options) {
+        const deadline = AbortSignal.timeout(options.timeoutMs);
+        const signal = options.signal ? AbortSignal.any([deadline, options.signal]) : deadline;
+        const started = performance.now();
+        const ms = () => Math.round(performance.now() - started);
+        try {
+            const response = await this.request(url, { signal, method: "HEAD", redirect: "manual" });
+            await response.body?.cancel().catch(() => undefined);
+            return { status: response.status, ms: ms() };
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason;
+            return { error: why(error, deadline.aborted, options.timeoutMs), ms: ms() };
+        }
+    }
+}

package/adapters/system/node/src/node-machine-metrics.d.ts

@@ -0,0 +1,61 @@
+import type { MachineMetrics, MachineSample, MemoryPressure } from "@parity/product-lab/ports/system";
+/** The CPUs' idle and total time so far, summed over all of them (milliseconds). */
+export interface CpuTimes {
+    readonly idle: number;
+    readonly total: number;
+}
+export interface NodeMachineMetricsOptions {
+    /** The platform (`process.platform`): only macOS reports a memory pressure level. */
+    readonly platform?: NodeJS.Platform;
+    /** The CPUs' times so far (`os.cpus()` summed). */
+    readonly cpuTimes?: () => CpuTimes;
+    /** macOS's pressure level as `sysctl -n kern.memorystatus_vm_pressure_level` prints it (1, 2 or 4). */
+    readonly readPressure?: () => Promise<string>;
+    /** The lab process's event loop: watched unless false (a test's fake loop numbers come from `loop`). */
+    readonly loop?: false | (() => {
+        readonly delayMaxMs?: number;
+        readonly utilization?: number;
+    });
+    /** Milliseconds on a monotonic clock (`performance.now()`). */
+    readonly now?: () => number;
+}
+/** How often macOS's pressure level is read, at most: a sample reports the last one read. */
+export declare const PRESSURE_READ_MS = 10000;
+/**
+ * The shortest window the CPUs' idle share and the loop are measured over (as the media driver's seconds). A recording
+ * also samples as a step starts and ends, often milliseconds after the last sample: over so short a window the loop
+ * reads busy (the sampling itself is all it did) and the idle share is noise. Such a sample leaves them out, and the
+ * next one covers the longer window.
+ */
+export declare const MIN_WINDOW_MS = 1000;
+/**
+ * The machine through Node's `os` module, and this process's resident memory (Windows reports a load of 0). Since
+ * backlog 241: the CPUs' idle share and this process's event-loop delay and utilization, each since the previous
+ * sample, and macOS's memory pressure level. Nothing here keeps the process alive: the delay histogram's timer is
+ * Node's own, unreferenced, and the pressure read is a short child process, unreferenced, whose answer the next sample
+ * reports.
+ */
+export declare class NodeMachineMetrics implements MachineMetrics {
+    private readonly platform;
+    private readonly cpuTimes;
+    private readonly readPressure;
+    private readonly loopReader;
+    private readonly now;
+    private cpuBefore;
+    private windowStart;
+    private pressure;
+    private pressureReadAt;
+    private pressureReading;
+    constructor(options?: NodeMachineMetricsOptions);
+    sample(): MachineSample;
+    /** The CPUs' idle share and the loop since the window began, when it is at least `MIN_WINDOW_MS` long; then a new one. */
+    private window;
+    /** On macOS, read the pressure level in the background when the last read is older than `PRESSURE_READ_MS`. */
+    private refreshPressure;
+    /** Bytes available to this user on the file system holding `path`. */
+    freeDiskBytes(path: string): number;
+    /** The bytes a directory tree's files hold (links counted as themselves, never followed). */
+    directoryBytes(path: string): number;
+}
+/** macOS's `kern.memorystatus_vm_pressure_level`: 1 normal, 2 warn, 4 critical; anything else is no level. */
+export declare function pressureLevel(text: string): MemoryPressure | undefined;

package/adapters/system/node/src/node-machine-metrics.js

@@ -0,0 +1,109 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { execFile } from "node:child_process";
+import { lstatSync, readdirSync, statfsSync } from "node:fs";
+import { availableParallelism, cpus, freemem, loadavg, totalmem } from "node:os";
+import { join } from "node:path";
+import { monitorEventLoopDelay, performance } from "node:perf_hooks";
+export const PRESSURE_READ_MS = 10_000;
+export const MIN_WINDOW_MS = 1_000;
+const LOOP_RESOLUTION_MS = 20;
+export class NodeMachineMetrics {
+    platform;
+    cpuTimes;
+    readPressure;
+    loopReader;
+    now;
+    cpuBefore;
+    windowStart;
+    pressure;
+    pressureReadAt = Number.NEGATIVE_INFINITY;
+    pressureReading = false;
+    constructor(options = {}) {
+        this.platform = options.platform ?? process.platform;
+        this.cpuTimes = options.cpuTimes ?? osCpuTimes;
+        this.readPressure = options.readPressure ?? sysctlPressure;
+        this.loopReader = options.loop === false ? undefined : (options.loop ?? processLoop());
+        this.now = options.now ?? (() => performance.now());
+        this.cpuBefore = this.cpuTimes();
+        this.windowStart = this.now();
+    }
+    sample() {
+        this.refreshPressure();
+        const measured = this.window();
+        return {
+            load1: loadavg()[0] ?? 0,
+            cpus: availableParallelism(),
+            freeMemoryBytes: freemem(),
+            totalMemoryBytes: totalmem(),
+            processRssBytes: process.memoryUsage.rss(),
+            ...measured,
+            ...(this.pressure ? { memoryPressure: this.pressure } : {}),
+        };
+    }
+    window() {
+        const at = this.now();
+        if (at - this.windowStart < MIN_WINDOW_MS)
+            return {};
+        this.windowStart = at;
+        const now = this.cpuTimes();
+        const idle = now.idle - this.cpuBefore.idle, total = now.total - this.cpuBefore.total;
+        this.cpuBefore = now;
+        const loop = this.loopReader?.();
+        return {
+            ...(total > 0 ? { cpuIdlePercent: Math.round((idle / total) * 1000) / 10 } : {}),
+            ...(loop?.delayMaxMs !== undefined ? { loopDelayMaxMs: loop.delayMaxMs } : {}),
+            ...(loop?.utilization !== undefined ? { loopUtilization: loop.utilization } : {}),
+        };
+    }
+    refreshPressure() {
+        if (this.platform !== "darwin" || this.pressureReading || Date.now() - this.pressureReadAt < PRESSURE_READ_MS)
+            return;
+        this.pressureReading = true;
+        this.pressureReadAt = Date.now();
+        this.readPressure().then((text) => { this.pressure = pressureLevel(text); }, 
+        () => { this.pressure = undefined; }).finally(() => { this.pressureReading = false; });
+    }
+    freeDiskBytes(path) {
+        const stats = statfsSync(path);
+        return stats.bavail * stats.bsize;
+    }
+    directoryBytes(path) {
+        const entry = lstatSync(path);
+        if (!entry.isDirectory())
+            return entry.size;
+        return readdirSync(path).reduce((total, name) => total + this.directoryBytes(join(path, name)), 0);
+    }
+}
+export function pressureLevel(text) {
+    return { "1": "normal", "2": "warn", "4": "critical" }[text.trim()];
+}
+function osCpuTimes() {
+    let idle = 0, total = 0;
+    for (const { times } of cpus()) {
+        idle += times.idle;
+        total += times.user + times.nice + times.sys + times.idle + times.irq;
+    }
+    return { idle, total };
+}
+function processLoop() {
+    const delay = monitorEventLoopDelay({ resolution: LOOP_RESOLUTION_MS });
+    delay.enable();
+    let before = performance.eventLoopUtilization();
+    return () => {
+        const now = performance.eventLoopUtilization();
+        const utilization = Math.round(performance.eventLoopUtilization(now, before).utilization * 100) / 100;
+        before = now;
+        const delayMaxMs = delay.count ? Math.round(delay.max / 1e6) : undefined;
+        delay.reset();
+        return { ...(delayMaxMs !== undefined ? { delayMaxMs } : {}), utilization };
+    };
+}
+function sysctlPressure() {
+    return new Promise((resolve, reject) => {
+        const child = execFile("sysctl", ["-n", "kern.memorystatus_vm_pressure_level"], { timeout: 2_000 }, (error, stdout) => (error ? reject(error) : resolve(stdout)));
+        child.unref();
+        for (const pipe of [child.stdout, child.stderr])
+            pipe?.unref();
+    });
+}

package/adapters/system/node/src/node-os-ports.d.ts

@@ -0,0 +1,24 @@
+import type { CommandRunner, FileSystem, OsPorts, PortRange } from "@parity/product-lab/ports/system";
+export interface NodeOsPortsDependencies {
+    readonly commands: CommandRunner;
+    readonly files: Pick<FileSystem, "readText">;
+    /** `process.platform` unless given (tests). */
+    readonly platform?: NodeJS.Platform;
+}
+export declare class NodeOsPorts implements OsPorts {
+    private readonly dependencies;
+    private readonly platform;
+    private range;
+    constructor(dependencies: NodeOsPortsDependencies);
+    /** Read once: the range is a kernel setting, not something that moves while the lab runs. */
+    ephemeralRange(): Promise<PortRange | undefined>;
+    holder(port: number): Promise<string | undefined>;
+    private readRange;
+    private output;
+}
+/** Two port numbers (sysctl's two lines, or /proc's "32768\t60999"); undefined unless they make a range. */
+export declare function parseRange(text: string): PortRange | undefined;
+/** `netstat -anv -p tcp` (macOS): the row whose local address ends in `.port`, a listener first, by its process:pid. */
+export declare function netstatHolder(output: string, port: number): string | undefined;
+/** `ss -Htanp` (Linux): the row whose local address ends in `:port`, a listener first, by its users:(("name",pid=N,…)). */
+export declare function ssHolder(output: string, port: number): string | undefined;