@harperfast/integration-testing 0.5.0 → 0.5.2

package/dist/loopbackAddressPool.d.ts

@@ -0,0 +1,50 @@
+/**
+ * This method attempts to validate all loopback addresses in the pool by trying to
+ * bind to each one. It returns an object containing arrays of successfully bound
+ * loopback addresses and those that failed along with their errors.
+ *
+ * It will check all loopback addresses from 127.0.0.2 to 127.0.0.33 (by default).
+ *
+ * Use the HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT environment variable to
+ * adjust the number of loopback addresses to validate (up to 254).
+ */
+export declare function validateLoopbackAddressPool(): Promise<{
+    successful: string[];
+    failed: {
+        loopbackAddress: string;
+        error: Error;
+    }[];
+}>;
+/**
+ * Retrieves the next available loopback address from the pool using a file-based
+ * locking mechanism to safely allocate addresses across concurrent test processes.
+ *
+ * **How it works:**
+ * 1. Acquires a file-based lock to prevent race conditions with other processes
+ * 2. Reads the pool state (a JSON array of process IDs, with null for available slots)
+ * 3. Finds the first available (null) slot and assigns the current process PID to it
+ * 4. Writes the updated pool back to disk and releases the lock
+ * 5. Validates that the allocated address can actually be bound to
+ * 6. Returns the loopback address (e.g., "127.0.0.2")
+ *
+ * If no addresses are available, waits and retries until one becomes available.
+ *
+ * **Pool file location:** `${tmpdir()}/harper-integration-test-loopback-pool.json`
+ * **Lock file location:** `${tmpdir()}/harper-integration-test-loopback-pool.lock`
+ *
+ * @returns A promise that resolves with an allocated loopback address
+ * @throws {LoopbackAddressValidationError} If the allocated address cannot be bound to
+ */
+export declare function getNextAvailableLoopbackAddress(): Promise<string>;
+/**
+ * Releases a loopback address back to the pool, making it available for other processes.
+ *
+ * @param address The loopback address to release (e.g., "127.0.0.2")
+ * @throws InvalidLoopbackAddressError if the address format is invalid
+ */
+export declare function releaseLoopbackAddress(address: string): Promise<void>;
+/**
+ * Releases all loopback addresses assigned to the current process.
+ * Useful for cleanup during graceful shutdown.
+ */
+export declare function releaseAllLoopbackAddressesForCurrentProcess(): Promise<void>;

package/dist/loopbackAddressPool.js

@@ -0,0 +1,421 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { open, readFile, stat, unlink, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
+// Configuration constants
+// The pool starts at 127.0.0.2 by default (rather than 127.0.0.1) to avoid conflicting
+// with other servers commonly bound to localhost. Override via the
+// HARPER_INTEGRATION_TEST_LOOPBACK_POOL_START environment variable.
+const HARPER_LOOPBACK_POOL_START = process.env.HARPER_INTEGRATION_TEST_LOOPBACK_POOL_START
+    ? parseInt(process.env.HARPER_INTEGRATION_TEST_LOOPBACK_POOL_START, 10)
+    : 2;
+if (HARPER_LOOPBACK_POOL_START < 1 || HARPER_LOOPBACK_POOL_START > 255) {
+    throw new Error('HARPER_INTEGRATION_TEST_LOOPBACK_POOL_START must be between 1 and 255');
+}
+const HARPER_LOOPBACK_POOL_COUNT = process.env.HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT
+    ? parseInt(process.env.HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT, 10)
+    : 32;
+const HARPER_LOOPBACK_POOL_MAX = 256 - HARPER_LOOPBACK_POOL_START;
+if (HARPER_LOOPBACK_POOL_COUNT < 1 || HARPER_LOOPBACK_POOL_COUNT > HARPER_LOOPBACK_POOL_MAX) {
+    throw new Error(`HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT must be between 1 and ${HARPER_LOOPBACK_POOL_MAX}`);
+}
+const HARPER_LOOPBACK_POOL_PATH = join(tmpdir(), 'harper-integration-test-loopback-pool.json');
+const HARPER_LOOPBACK_POOL_LOCK_PATH = join(tmpdir(), 'harper-integration-test-loopback-pool.lock');
+// Constants for timeouts and retries
+const LOCK_STALE_TIMEOUT_MS = 10000;
+const RETRY_DELAY_MS = 1000;
+// Port used as a conflict canary when allocating an address. This MUST be a port that
+// Harper binds WITHOUT SO_REUSEPORT (the operations API — `OPERATIONS_API_PORT` in
+// harperLifecycle.ts — does exactly that, main-thread-only). Because that port is
+// exclusive, a stale/overlapping Harper node still holding the address makes a plain
+// (non-reusePort) bind here fail with EADDRINUSE — which is precisely the signal we
+// need. Without this check, SO_REUSEPORT on the shared HTTP/replication ports would let
+// a freshly-assigned node silently co-bind an address another node still owns, corrupting
+// both suites. Override via HARPER_INTEGRATION_TEST_CONFLICT_PROBE_PORT if the operations
+// port ever changes. (Hardcoded rather than imported from harperLifecycle to avoid a
+// circular import between these two modules.)
+const CONFLICT_PROBE_PORT = (() => {
+    const parsed = parseInt(process.env.HARPER_INTEGRATION_TEST_CONFLICT_PROBE_PORT || '', 10);
+    // Fall back to the default if unset/non-numeric/out-of-range, so an invalid override
+    // can't turn into a `server.listen(NaN)` crash during allocation.
+    return Number.isNaN(parsed) || parsed < 0 || parsed > 65535 ? 9925 : parsed;
+})();
+// Custom error classes
+class LoopbackAddressValidationError extends Error {
+    constructor(address, cause) {
+        super(`Failed to validate loopback address ${address}. This likely means your system does not have the required loopback addresses configured/enabled. Refer to the Harper Integration Test documentation (integrationTests/README.md) for more information.`);
+        this.name = 'LoopbackAddressValidationError';
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+class InvalidLoopbackAddressError extends Error {
+    constructor(address) {
+        super(`Invalid loopback address format: ${address}. Expected format: 127.0.0.X where X is between ${HARPER_LOOPBACK_POOL_START} and ${HARPER_LOOPBACK_POOL_START + HARPER_LOOPBACK_POOL_COUNT - 1}`);
+        this.name = 'InvalidLoopbackAddressError';
+    }
+}
+/**
+ * Acquires a file-based lock by creating the lock file. This enables safe concurrent
+ * access to the loopback pool across multiple test processes.
+ *
+ * Uses the 'wx' file flag which atomically fails if the file already exists, providing
+ * a simple but effective cross-process mutex. Handles stale locks by removing lock files
+ * older than LOCK_STALE_TIMEOUT_MS (10 seconds).
+ *
+ * @returns A promise that resolves when the lock is acquired
+ */
+async function acquireLock() {
+    while (true) {
+        try {
+            // The 'wx' flag causes the open to fail if the file already exists
+            const lockFileHandle = await open(HARPER_LOOPBACK_POOL_LOCK_PATH, 'wx');
+            // We have the lock - close the handle as we don't intend to write to it
+            await lockFileHandle.close();
+            return;
+        }
+        catch (error) {
+            // If the lock file already exists, it's either stale or we wait for it to be released
+            if (error.code === 'EEXIST') {
+                try {
+                    const lockFileStat = await stat(HARPER_LOOPBACK_POOL_LOCK_PATH);
+                    // If the lock file is older than the timeout, consider it stale and remove it
+                    if (Date.now() - lockFileStat.mtimeMs > LOCK_STALE_TIMEOUT_MS) {
+                        await unlink(HARPER_LOOPBACK_POOL_LOCK_PATH);
+                    }
+                }
+                catch {
+                    // Lock file may have been removed by another process, continue
+                }
+                await sleep(RETRY_DELAY_MS);
+                continue;
+            }
+            // Rethrow other errors
+            throw error;
+        }
+    }
+}
+/**
+ * Releases the file-based lock by deleting the lock file.
+ */
+async function releaseLock() {
+    try {
+        await unlink(HARPER_LOOPBACK_POOL_LOCK_PATH);
+    }
+    catch {
+        // Ignore errors if lock file is already gone
+    }
+}
+/**
+ * Executes a callback function while holding the lock. Automatically acquires
+ * and releases the lock, ensuring the lock is always released even if the callback
+ * throws an error.
+ *
+ * @param callback The async function to execute while holding the lock
+ * @returns The result of the callback function
+ */
+async function withLock(callback) {
+    await acquireLock();
+    try {
+        return await callback();
+    }
+    finally {
+        await releaseLock();
+    }
+}
+/**
+ * Reads the loopback pool from the pool file. The pool is a JSON array where each
+ * index represents a loopback address (127.0.0.2, 127.0.0.3, etc.) and the value
+ * is either null (available) or a process PID (in use).
+ *
+ * If the file doesn't exist, creates and returns a new empty pool with all addresses
+ * marked as available (null).
+ *
+ * @returns The loopback pool array
+ */
+async function readPoolFile() {
+    try {
+        const content = await readFile(HARPER_LOOPBACK_POOL_PATH, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            // If the pool file doesn't exist yet, create it with null entries
+            return Array(HARPER_LOOPBACK_POOL_COUNT).fill(null);
+        }
+        throw error;
+    }
+}
+/**
+ * Writes the loopback pool to the pool file as JSON.
+ *
+ * @param pool The loopback pool array to persist
+ */
+async function writePoolFile(pool) {
+    await writeFile(HARPER_LOOPBACK_POOL_PATH, JSON.stringify(pool));
+}
+/**
+ * Validates the format of a loopback address and extracts the pool index.
+ *
+ * Expects addresses in the format "127.0.0.X" where X is between the pool start
+ * (127.0.0.2) and the pool start + pool count - 1. The returned index is 0-based
+ * (e.g., "127.0.0.2" returns index 0).
+ *
+ * @param address The loopback address to parse (e.g., "127.0.0.2")
+ * @returns The 0-based pool index for this address
+ * @throws {InvalidLoopbackAddressError} If the address format is invalid or out of range
+ */
+function parseLoopbackAddress(address) {
+    const parts = address.split('.');
+    if (parts.length !== 4 || parts[0] !== '127' || parts[1] !== '0' || parts[2] !== '0') {
+        throw new InvalidLoopbackAddressError(address);
+    }
+    const index = parseInt(parts[3], 10) - HARPER_LOOPBACK_POOL_START;
+    if (isNaN(index) || index < 0 || index >= HARPER_LOOPBACK_POOL_COUNT) {
+        throw new InvalidLoopbackAddressError(address);
+    }
+    return index;
+}
+/**
+ * Validates that a given loopback address can be bound to by creating a temporary
+ * TCP server on that address. This ensures the loopback address is actually configured
+ * and available on the system before allocating it to a test process.
+ *
+ * The server is bound to port 0 (random port) just to verify the address exists,
+ * then immediately closed.
+ *
+ * @param loopbackAddress The loopback IP address to validate (e.g., "127.0.0.2")
+ * @returns A promise that resolves with the address if valid
+ * @throws An error with the loopbackAddress property if binding fails
+ */
+function validateLoopbackAddress(loopbackAddress) {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', (error) => {
+            const enhancedError = error;
+            enhancedError.loopbackAddress = loopbackAddress;
+            reject(enhancedError);
+        });
+        server.listen(0, loopbackAddress, () => {
+            server.close(() => {
+                resolve(loopbackAddress);
+            });
+        });
+    });
+}
+/**
+ * Conflict canary: detects whether a Harper node is already bound to `loopbackAddress`
+ * by attempting an exclusive (non-SO_REUSEPORT) bind on the operations-API port. Node's
+ * `net` server does not set SO_REUSEPORT, so if a stale/overlapping Harper node still
+ * owns the address's operations port, this bind fails with EADDRINUSE.
+ *
+ * Returns `true` if the address appears in use (EADDRINUSE), `false` if it is free.
+ * Re-throws any other bind error (e.g. EADDRNOTAVAIL) — that's a real configuration
+ * problem the caller should surface, not a transient conflict to skip.
+ *
+ * @param loopbackAddress The loopback IP address to probe (e.g., "127.0.0.2")
+ */
+function isLoopbackAddressInUse(loopbackAddress) {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        const onError = (error) => {
+            if (error.code === 'EADDRINUSE') {
+                resolve(true);
+                return;
+            }
+            const enhancedError = error;
+            enhancedError.loopbackAddress = loopbackAddress;
+            reject(enhancedError);
+        };
+        server.once('error', onError);
+        server.listen(CONFLICT_PROBE_PORT, loopbackAddress, () => {
+            // Bind succeeded — the address is free. Drop the error listener so a stray
+            // post-bind socket error during close() can't flip the resolved verdict.
+            server.off('error', onError);
+            server.close(() => {
+                resolve(false);
+            });
+        });
+    });
+}
+/**
+ * This method attempts to validate all loopback addresses in the pool by trying to
+ * bind to each one. It returns an object containing arrays of successfully bound
+ * loopback addresses and those that failed along with their errors.
+ *
+ * It will check all loopback addresses from 127.0.0.2 to 127.0.0.33 (by default).
+ *
+ * Use the HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT environment variable to
+ * adjust the number of loopback addresses to validate (up to 254).
+ */
+export async function validateLoopbackAddressPool() {
+    return Promise.allSettled(Array.from({ length: HARPER_LOOPBACK_POOL_COUNT }, (_, i) => validateLoopbackAddress(`127.0.0.${i + HARPER_LOOPBACK_POOL_START}`))).then((results) => results.reduce((acc, result) => {
+        if (result.status === 'fulfilled') {
+            acc.successful.push(result.value);
+        }
+        else {
+            const error = result.reason;
+            acc.failed.push({ loopbackAddress: error.loopbackAddress, error });
+        }
+        return acc;
+    }, { successful: [], failed: [] }));
+}
+/**
+ * Retrieves the next available loopback address from the pool using a file-based
+ * locking mechanism to safely allocate addresses across concurrent test processes.
+ *
+ * **How it works:**
+ * 1. Acquires a file-based lock to prevent race conditions with other processes
+ * 2. Reads the pool state (a JSON array of process IDs, with null for available slots)
+ * 3. Finds the first available (null) slot and assigns the current process PID to it
+ * 4. Writes the updated pool back to disk and releases the lock
+ * 5. Validates that the allocated address can actually be bound to
+ * 6. Returns the loopback address (e.g., "127.0.0.2")
+ *
+ * If no addresses are available, waits and retries until one becomes available.
+ *
+ * **Pool file location:** `${tmpdir()}/harper-integration-test-loopback-pool.json`
+ * **Lock file location:** `${tmpdir()}/harper-integration-test-loopback-pool.lock`
+ *
+ * @returns A promise that resolves with an allocated loopback address
+ * @throws {LoopbackAddressValidationError} If the allocated address cannot be bound to
+ */
+export async function getNextAvailableLoopbackAddress() {
+    // Each index maps to a different loopback address (index 0 -> 127.0.0.2, index 1 -> 127.0.0.3, etc.)
+    // So if the first test process number is 42, it would be assigned to index 0 associated with address 127.0.0.2
+    // [42, null, null, ...];
+    // Then the next process (call is 43) gets the next available, so index 1 -> 127.0.0.3
+    // [42, 43, null, ...];
+    // And so on...
+    // As processes exit and release their loopback addresses, those addresses become available for new processes to use
+    // [42, null, 44, ...];
+    // Next process (45) gets index 1 again ->
+    // [42, 45, 44, ...];
+    // This continues until all loopback addresses are used, at which point new processes will wait until an address becomes available
+    // Since multiple processes may be trying to get a loopback address at the same time, we need to implement a simple file-based locking mechanism to prevent race conditions
+    // Indices found in-use by the conflict canary during THIS call. Tracked locally (not by
+    // parking them in the shared pool) so we never deadlock ourselves: if we parked every
+    // poisoned slot under our own live PID, the pool could fill with our PID, the free-slot search
+    // would find nothing, removeDeadProcessesFromPool couldn't reclaim them (we're alive), and we'd
+    // spin forever. Instead we release poisoned slots back to the pool and just avoid re-trying
+    // them within this attempt; the set is cleared before each wait so they can be re-probed once
+    // the lingering node has had time to exit.
+    const triedIndices = new Set();
+    while (true) {
+        const assignedIndex = await withLock(async () => {
+            // Read the pool file
+            const loopbackPool = await readPoolFile();
+            // Find the first available index we haven't already found in-use this attempt
+            let index = null;
+            for (let i = 0; i < loopbackPool.length; i++) {
+                if (loopbackPool[i] === null && !triedIndices.has(i)) {
+                    index = i;
+                    break;
+                }
+            }
+            if (index === null) {
+                // Nothing available - remove any dead processes from the pool and wait for one to become available
+                removeDeadProcessesFromPool(loopbackPool);
+            }
+            else {
+                // Assign the process PID to that index to mark it as used
+                loopbackPool[index] = process.pid;
+            }
+            // Write the updated pool back to the file
+            await writePoolFile(loopbackPool);
+            return index;
+        });
+        // If we got an index, validate and return the address
+        if (assignedIndex !== null) {
+            const loopbackAddress = `127.0.0.${assignedIndex + HARPER_LOOPBACK_POOL_START}`;
+            try {
+                await validateLoopbackAddress(loopbackAddress);
+            }
+            catch (error) {
+                // Validation failed - throw a proper error instead of breaking
+                throw new LoopbackAddressValidationError(loopbackAddress, error);
+            }
+            // Conflict canary: a stale or still-running Harper node from an overlapping
+            // suite may already hold this address (e.g. the pool slot was freed while its
+            // node lingered). SO_REUSEPORT on Harper's shared HTTP/replication ports would
+            // otherwise let our node silently co-bind it, splitting connections between two
+            // nodes and corrupting both suites. Detect that here via the exclusive
+            // operations port and skip the poisoned address.
+            let inUse;
+            try {
+                inUse = await isLoopbackAddressInUse(loopbackAddress);
+            }
+            catch (error) {
+                throw new LoopbackAddressValidationError(loopbackAddress, error);
+            }
+            if (!inUse) {
+                return loopbackAddress;
+            }
+            // Release the slot back to the pool (so it isn't leaked under our PID) and remember
+            // not to re-try it this attempt; loop to claim the next available one.
+            await releaseLoopbackAddress(loopbackAddress);
+            triedIndices.add(assignedIndex);
+            console.warn(`[loopback-pool] ${loopbackAddress} is still in use by another Harper node (operations port ${CONFLICT_PROBE_PORT} bound); skipping to avoid an SO_REUSEPORT co-bind.`);
+            continue;
+        }
+        // No available addresses; clear the per-attempt skip set so poisoned addresses can be
+        // re-probed (their lingering node may have exited during the wait), then wait and retry.
+        triedIndices.clear();
+        await sleep(RETRY_DELAY_MS);
+    }
+}
+/**
+ * Removes any dead processes from the loopback pool.
+ * @param loopbackPool
+ */
+function removeDeadProcessesFromPool(loopbackPool) {
+    loopbackPool.forEach((pid, index) => {
+        if (pid === null)
+            return;
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            loopbackPool[index] = null;
+        }
+    });
+}
+/**
+ * Releases a loopback address back to the pool, making it available for other processes.
+ *
+ * @param address The loopback address to release (e.g., "127.0.0.2")
+ * @throws InvalidLoopbackAddressError if the address format is invalid
+ */
+export async function releaseLoopbackAddress(address) {
+    // Validate and parse the address
+    const index = parseLoopbackAddress(address);
+    await withLock(async () => {
+        // Read the pool file
+        const loopbackPool = await readPoolFile();
+        // Release the address by setting it to null
+        loopbackPool[index] = null;
+        // Write the updated pool back to the file
+        await writePoolFile(loopbackPool);
+    });
+}
+/**
+ * Releases all loopback addresses assigned to the current process.
+ * Useful for cleanup during graceful shutdown.
+ */
+export async function releaseAllLoopbackAddressesForCurrentProcess() {
+    await withLock(async () => {
+        // Read the pool file
+        const loopbackPool = await readPoolFile();
+        // Find and release all addresses assigned to this process
+        for (let i = 0; i < loopbackPool.length; i++) {
+            if (loopbackPool[i] === process.pid) {
+                loopbackPool[i] = null;
+            }
+        }
+        // Write the updated pool back to the file
+        await writePoolFile(loopbackPool);
+    });
+}
+//# sourceMappingURL=loopbackAddressPool.js.map

package/dist/loopbackAddressPool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopbackAddressPool.js","sourceRoot":"","sources":["../src/loopbackAddressPool.ts"],"names":[],"mappings":"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"}

package/dist/portUtils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Checks whether a TCP port can be bound on a given host (i.e. the port is free).
+ *
+ * Attempts to bind a throwaway server to `host:port`; resolves `true` if the bind
+ * succeeds (the server is closed immediately) and `false` if it fails (e.g. the port
+ * is still held by another process or socket).
+ *
+ * @param host The host/address to bind on (e.g. "127.0.0.2")
+ * @param port The port to test
+ * @returns A promise resolving to `true` if the port is free, `false` otherwise
+ */
+export declare function isPortFree(host: string, port: number): Promise<boolean>;
+/**
+ * Polls until every `host:port` in `ports` is free, or `timeoutMs` elapses.
+ *
+ * Unlike binding to an ephemeral port (which only proves the *address* is usable), this
+ * verifies the specific fixed ports a Harper instance binds are actually released, which
+ * is what the next test suite needs before it can reuse the address.
+ *
+ * @param host The host/address the ports are bound on (e.g. "127.0.0.2")
+ * @param ports The fixed ports to wait on
+ * @param timeoutMs Maximum time to wait for all ports to become free
+ * @param pollIntervalMs Delay between polls (default 100ms)
+ * @returns `true` if all ports became free within the timeout, `false` if it gave up
+ */
+export declare function waitForPortsFree(host: string, ports: number[], timeoutMs: number, pollIntervalMs?: number): Promise<boolean>;

package/dist/portUtils.js

@@ -0,0 +1,47 @@
+import { createServer } from 'node:net';
+import { setTimeout as sleep } from 'node:timers/promises';
+/**
+ * Checks whether a TCP port can be bound on a given host (i.e. the port is free).
+ *
+ * Attempts to bind a throwaway server to `host:port`; resolves `true` if the bind
+ * succeeds (the server is closed immediately) and `false` if it fails (e.g. the port
+ * is still held by another process or socket).
+ *
+ * @param host The host/address to bind on (e.g. "127.0.0.2")
+ * @param port The port to test
+ * @returns A promise resolving to `true` if the port is free, `false` otherwise
+ */
+export function isPortFree(host, port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.listen(port, host, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+/**
+ * Polls until every `host:port` in `ports` is free, or `timeoutMs` elapses.
+ *
+ * Unlike binding to an ephemeral port (which only proves the *address* is usable), this
+ * verifies the specific fixed ports a Harper instance binds are actually released, which
+ * is what the next test suite needs before it can reuse the address.
+ *
+ * @param host The host/address the ports are bound on (e.g. "127.0.0.2")
+ * @param ports The fixed ports to wait on
+ * @param timeoutMs Maximum time to wait for all ports to become free
+ * @param pollIntervalMs Delay between polls (default 100ms)
+ * @returns `true` if all ports became free within the timeout, `false` if it gave up
+ */
+export async function waitForPortsFree(host, ports, timeoutMs, pollIntervalMs = 100) {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        const results = await Promise.all(ports.map((port) => isPortFree(host, port)));
+        if (results.every(Boolean))
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await sleep(pollIntervalMs);
+    }
+}
+//# sourceMappingURL=portUtils.js.map

package/dist/portUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portUtils.js","sourceRoot":"","sources":["../src/portUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAY;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC9B,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE;YAC9B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,IAAY,EACZ,KAAe,EACf,SAAiB,EACjB,cAAc,GAAG,GAAG;IAEpB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,OAAO,IAAI,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QAC/E,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QACxC,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;YAAE,OAAO,KAAK,CAAC;QACzC,MAAM,KAAK,CAAC,cAAc,CAAC,CAAC;IAC7B,CAAC;AACF,CAAC"}

package/dist/run.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};