@harperfast/integration-testing 0.5.0 → 0.5.1

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,348 @@
+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;
+// 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));
+}
+/**
+ * Finds the first available (null) index in the pool. This implements a simple
+ * first-available allocation strategy.
+ *
+ * @param pool The loopback pool array
+ * @returns The first available index, or null if the pool is full
+ */
+function findAvailableIndex(pool) {
+    for (let i = 0; i < pool.length; i++) {
+        if (pool[i] === null) {
+            return i;
+        }
+    }
+    return null;
+}
+/**
+ * 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);
+            });
+        });
+    });
+}
+/**
+ * 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
+    while (true) {
+        const assignedIndex = await withLock(async () => {
+            // Read the pool file
+            const loopbackPool = await readPoolFile();
+            // Find the first available index
+            const index = findAvailableIndex(loopbackPool);
+            if (index === null) {
+                // No available addresses - 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);
+                return loopbackAddress;
+            }
+            catch (error) {
+                // Validation failed - throw a proper error instead of breaking
+                throw new LoopbackAddressValidationError(loopbackAddress, error);
+            }
+        }
+        // No available addresses; wait and retry
+        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 {};

package/dist/run.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+import { run } from 'node:test';
+import { availableParallelism, tmpdir } from 'node:os';
+import { spec } from 'node:test/reporters';
+import { parseArgs } from 'node:util';
+import { validateLoopbackAddressPool } from "./loopbackAddressPool.js";
+import { LOG_DIR_MARKER_PREFIX } from "./harperLifecycle.js";
+import { mkdtemp } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { readFileSync, rmSync, existsSync } from 'node:fs';
+/**
+ * Important! This script should not be required to execute integration tests.
+
+ * Thus, it should not be responsible for any stateful management or setup/teardown logic.
+ * All such logic should be contained within the individual test suites or utility functions.
+ * Tests (individuals or multiples) should be executable directly via the Node.js Test Runner CLI and
+ * parallelization should still work.
+ *
+ * The main purpose of this script is to reduce the boilerplate required to run integration tests, or having
+ * developers manually specify CLI arguments each time.
+ *
+ * This script configures and runs the Node.js Test Runner with sensible defaults for Harper integration tests.
+ *
+ * It supports environment variables to override defaults, allowing flexibility for CI environments or specific use cases.
+ *
+ * Usage: harper-integration-test-run [options] <glob-pattern> [<glob-pattern> ...]
+ *
+ * At least one glob pattern positional argument is required.
+ */
+// Imitating the Node.js Test Runner CLI arguments for consistency except we drop the `test-` prefix
+const { values, positionals } = parseArgs({
+    options: {
+        concurrency: { type: 'string' },
+        isolation: { type: 'string' },
+        shard: { type: 'string' },
+        only: { type: 'boolean' },
+    },
+    allowPositionals: true,
+});
+if (positionals.length === 0) {
+    console.error('Error: At least one glob pattern is required.\n' +
+        'Usage: harper-integration-test-run [options] <glob-pattern> [<glob-pattern> ...]\n' +
+        'Example: harper-integration-test-run "integrationTests/**/*.test.ts"');
+    process.exit(1);
+}
+// https://nodejs.org/docs/latest-v24.x/api/cli.html#--test-concurrency
+const concurrencyOption = process.env.HARPER_INTEGRATION_TEST_CONCURRENCY || values.concurrency;
+const CONCURRENCY = concurrencyOption
+    ? parseInt(concurrencyOption, 10)
+    : Math.max(1, Math.floor(availableParallelism() / 2) + 1);
+// https://nodejs.org/docs/latest-v24.x/api/cli.html#--test-isolationmode
+const ISOLATION = process.env.HARPER_INTEGRATION_TEST_ISOLATION || values.isolation || 'process';
+// https://nodejs.org/docs/latest-v24.x/api/cli.html#--test-shard
+const [SHARD_INDEX, SHARD_TOTAL] = (process.env.HARPER_INTEGRATION_TEST_SHARD || values.shard || '1/1')
+    .split('/')
+    .map((v) => parseInt(v, 10));
+// https://nodejs.org/docs/latest-v24.x/api/cli.html#--test-only
+const ONLY = parseBoolean(process.env.HARPER_INTEGRATION_TEST_ONLY) ?? values.only ?? false;
+// Number of trailing hdb.log lines to print per failed test. 0 (or any non-positive value) prints the entire log.
+const LOG_TAIL_LINES = (() => {
+    const parsed = parseInt(process.env.HARPER_INTEGRATION_TEST_LOG_TAIL_LINES || '', 10);
+    return Number.isFinite(parsed) ? parsed : 200;
+})();
+const TEST_FILES = positionals;
+// Loopback Address Check
+if (ISOLATION !== 'none' && CONCURRENCY > 1) {
+    const result = await validateLoopbackAddressPool();
+    if (result.failed.length > 0) {
+        console.error('Failed to bind loopback address pool required for integration tests:');
+        for (const failure of result.failed) {
+            console.error(`- ${failure.loopbackAddress}: ${failure.error.message}`);
+        }
+        console.error('Run the setup script to configure loopback addresses:\n' +
+            '  harper-integration-test-setup-loopback\n' +
+            'Or run integration tests sequentially using `--isolation=none` to avoid this requirement.');
+        process.exit(1);
+    }
+}
+let createdTempLogDir;
+if (!process.env.HARPER_INTEGRATION_TEST_LOG_DIR) {
+    createdTempLogDir = await mkdtemp(join(tmpdir(), 'harper-integration-test-logs-'));
+    process.env.HARPER_INTEGRATION_TEST_LOG_DIR = createdTempLogDir;
+}
+const fileToLogDirs = new Map();
+const failedFiles = new Set();
+const runner = run({
+    concurrency: ISOLATION === 'none' ? undefined : CONCURRENCY,
+    // @ts-expect-error - ignore until we do better env var / cli arg handling/validation
+    isolation: ISOLATION,
+    globPatterns: TEST_FILES,
+    only: ONLY,
+    shard: {
+        index: SHARD_INDEX,
+        total: SHARD_TOTAL,
+    },
+});
+const logDirMarkerPattern = new RegExp(`${LOG_DIR_MARKER_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')} (.*)`);
+runner.on('test:stdout', (data) => {
+    const match = typeof data.message === 'string' && data.message.match(logDirMarkerPattern);
+    if (match && data.file) {
+        const logDir = match[1].trim();
+        const normalizedFile = resolve(data.file);
+        let dirs = fileToLogDirs.get(normalizedFile);
+        if (!dirs) {
+            dirs = new Set();
+            fileToLogDirs.set(normalizedFile, dirs);
+        }
+        dirs.add(logDir);
+    }
+});
+runner.on('test:fail', (data) => {
+    process.exitCode = 1;
+    if (data.file) {
+        failedFiles.add(resolve(data.file));
+    }
+});
+runner.compose(spec).pipe(process.stdout);
+process.on('exit', () => {
+    if (failedFiles.size > 0) {
+        console.log('\n\n' + '='.repeat(80));
+        console.log('--- TEST FAILURES DETECTED: HARPER LOGS ---');
+        console.log('='.repeat(80));
+        for (const file of failedFiles) {
+            const dirs = fileToLogDirs.get(file);
+            if (dirs && dirs.size > 0) {
+                for (const dir of dirs) {
+                    const hdbLogPath = join(dir, 'hdb.log');
+                    if (existsSync(hdbLogPath)) {
+                        try {
+                            const content = readFileSync(hdbLogPath, 'utf8');
+                            let output;
+                            let tailNote = '';
+                            if (LOG_TAIL_LINES > 0) {
+                                const lines = content.split('\n');
+                                if (lines.length > LOG_TAIL_LINES) {
+                                    output = lines.slice(-LOG_TAIL_LINES).join('\n');
+                                    tailNote = ` (last ${LOG_TAIL_LINES} of ${lines.length} lines; set HARPER_INTEGRATION_TEST_LOG_TAIL_LINES=0 for full log)`;
+                                }
+                                else {
+                                    output = content;
+                                }
+                            }
+                            else {
+                                output = content;
+                            }
+                            console.log(`\n--- Log for instance in ${file}${tailNote} ---`);
+                            console.log(`Directory: ${dir}`);
+                            console.log('-'.repeat(80));
+                            console.log(output);
+                            console.log('-'.repeat(80));
+                        }
+                        catch (e) {
+                            console.error(`Failed to read log file ${hdbLogPath}:`, e);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (createdTempLogDir) {
+        try {
+            rmSync(createdTempLogDir, { recursive: true, force: true });
+        }
+        catch (e) {
+            console.error(`Failed to clean up temporary log directory ${createdTempLogDir}:`, e);
+        }
+    }
+});
+function parseBoolean(value) {
+    if (value === undefined)
+        return undefined;
+    if (value.toLowerCase() === 'true' || value === '1')
+        return true;
+    if (value.toLowerCase() === 'false' || value === '0')
+        return false;
+    return undefined;
+}
+//# sourceMappingURL=run.js.map