moonwall 1.0.0-dev.0

package/dist/services/network/RpcPortDiscoveryService.js

@@ -0,0 +1,136 @@
+import { Command, Socket } from "@effect/platform";
+import * as NodeCommandExecutor from "@effect/platform-node/NodeCommandExecutor";
+import * as NodeContext from "@effect/platform-node/NodeContext";
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
+import * as NodeSocket from "@effect/platform-node/NodeSocket";
+import { createLogger } from "../../util/index.js";
+import { Context, Deferred, Effect, Layer, Option, Schedule } from "effect";
+import { PortDiscoveryError } from "../errors.js";
+const logger = createLogger({ name: "RpcPortDiscoveryService" });
+const debug = logger.debug.bind(logger);
+/**
+ * Service for discovering RPC ports by testing actual connectivity
+ */
+export class RpcPortDiscoveryService extends Context.Tag("RpcPortDiscoveryService")() {
+}
+/**
+ * Parse ports from lsof output
+ */
+const parsePortsFromLsof = (stdout) => {
+    const regex = /(?:.+):(\d+)/;
+    return stdout.split("\n").flatMap((line) => {
+        const match = line.match(regex);
+        return match ? [Number.parseInt(match[1], 10)] : [];
+    });
+};
+/**
+ * Get all listening ports for a process
+ */
+const getAllPorts = (pid) => Command.make("lsof", "-p", `${pid}`, "-n", "-P").pipe(Command.pipeTo(Command.make("grep", "LISTEN")), Command.string, Effect.map(parsePortsFromLsof), Effect.flatMap((ports) => ports.length === 0
+    ? Effect.fail(new PortDiscoveryError({
+        cause: new Error("No listening ports found"),
+        pid,
+        attempts: 1,
+    }))
+    : Effect.succeed(ports)), Effect.catchAll((cause) => Effect.fail(new PortDiscoveryError({
+    cause,
+    pid,
+    attempts: 1,
+}))));
+/**
+ * Test a single RPC method on a socket
+ */
+const testRpcMethod = (method) => Effect.flatMap(Deferred.make(), (responseDeferred) => Effect.flatMap(Socket.Socket, (socket) => Effect.flatMap(socket.writer, (writer) => {
+    const request = new TextEncoder().encode(JSON.stringify({
+        jsonrpc: "2.0",
+        id: Math.floor(Math.random() * 10000),
+        method,
+        params: [],
+    }));
+    const handleMessages = socket.runRaw((data) => Effect.try(() => {
+        const message = typeof data === "string" ? data : new TextDecoder().decode(data);
+        const response = JSON.parse(message);
+        return response.jsonrpc === "2.0" && !response.error;
+    }).pipe(Effect.orElseSucceed(() => false), Effect.flatMap((shouldSucceed) => shouldSucceed ? Deferred.succeed(responseDeferred, true) : Effect.void)));
+    return Effect.all([
+        Effect.fork(handleMessages),
+        Effect.flatMap(writer(request), () => Effect.void),
+        Deferred.await(responseDeferred).pipe(Effect.timeoutOption("3 seconds"), Effect.map((opt) => (opt._tag === "Some" ? opt.value : false))),
+    ]).pipe(Effect.map(([_, __, result]) => result), Effect.catchAll((cause) => Effect.fail(new PortDiscoveryError({
+        cause,
+        pid: 0,
+        attempts: 1,
+    }))));
+})));
+/**
+ * Test if a port responds to RPC calls using Effect Socket
+ */
+const testRpcPort = (port, isEthereumChain) => Effect.scoped(Effect.provide(Effect.flatMap(testRpcMethod("system_chain"), (success) => {
+    if (success) {
+        debug(`Port ${port} responded to system_chain`);
+        return Effect.succeed(port);
+    }
+    if (!isEthereumChain) {
+        return Effect.fail(new PortDiscoveryError({
+            cause: new Error(`Port ${port} did not respond to system_chain`),
+            pid: 0,
+            attempts: 1,
+        }));
+    }
+    // If Ethereum chain, try eth_chainId
+    return Effect.flatMap(testRpcMethod("eth_chainId"), (ethSuccess) => {
+        if (ethSuccess) {
+            debug(`Port ${port} responded to eth_chainId`);
+            return Effect.succeed(port);
+        }
+        return Effect.fail(new PortDiscoveryError({
+            cause: new Error(`Port ${port} did not respond to eth_chainId`),
+            pid: 0,
+            attempts: 1,
+        }));
+    });
+}), NodeSocket.layerWebSocket(`ws://localhost:${port}`))).pipe(Effect.timeoutOption("7 seconds"), Effect.flatMap((opt) => Option.match(opt, {
+    onNone: () => Effect.fail(new PortDiscoveryError({
+        cause: new Error(`Port ${port} connection timeout`),
+        pid: 0,
+        attempts: 1,
+    })),
+    onSome: (val) => Effect.succeed(val),
+})));
+/**
+ * Discover RPC port by racing tests on all candidate ports
+ */
+const discoverRpcPortWithRace = (config) => {
+    const maxAttempts = config.maxAttempts || 2400;
+    return getAllPorts(config.pid).pipe(Effect.flatMap((allPorts) => {
+        debug(`Discovered ports: ${allPorts.join(", ")}`);
+        const candidatePorts = allPorts.filter((p) => p >= 1024 && p <= 65535 && p !== 30333 && p !== 9615 // Exclude p2p & metrics port
+        );
+        if (candidatePorts.length === 0) {
+            return Effect.fail(new PortDiscoveryError({
+                cause: new Error(`No candidate RPC ports found in: ${allPorts.join(", ")}`),
+                pid: config.pid,
+                attempts: 1,
+            }));
+        }
+        debug(`Testing candidate ports: ${candidatePorts.join(", ")}`);
+        // Race all port tests - first one to respond wins
+        return Effect.raceAll(candidatePorts.map((port) => testRpcPort(port, config.isEthereumChain))).pipe(Effect.catchAll((_error) => Effect.fail(new PortDiscoveryError({
+            cause: new Error(`All candidate ports failed RPC test: ${candidatePorts.join(", ")}`),
+            pid: config.pid,
+            attempts: 1,
+        }))));
+    }), 
+    // Retry the entire discovery process
+    Effect.retry(Schedule.fixed("50 millis").pipe(Schedule.compose(Schedule.recurs(maxAttempts - 1)))), Effect.catchAll((error) => Effect.fail(new PortDiscoveryError({
+        cause: error,
+        pid: config.pid,
+        attempts: maxAttempts,
+    }))), Effect.provide(NodeCommandExecutor.layer.pipe(Layer.provide(NodeContext.layer), Layer.provide(NodeFileSystem.layer))));
+};
+/**
+ * Live implementation of RpcPortDiscoveryService
+ */
+export const RpcPortDiscoveryServiceLive = Layer.succeed(RpcPortDiscoveryService, {
+    discoverRpcPort: discoverRpcPortWithRace,
+});

package/dist/services/network/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./NodeReadinessService.js";
+export * from "./PortDiscoveryService.js";
+export * from "./RpcPortDiscoveryService.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/services/network/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/network/index.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,0CAA0C;AAC1C,6CAA6C"}

package/dist/services/network/index.js

@@ -0,0 +1,3 @@
+export * from "./NodeReadinessService.js";
+export * from "./PortDiscoveryService.js";
+export * from "./RpcPortDiscoveryService.js";

package/dist/services/process/ProcessManagerService.d.ts

@@ -0,0 +1,49 @@
+import { Context, Effect, Layer } from "effect";
+import { type ChildProcess } from "node:child_process";
+import { NodeLaunchError, ProcessError } from "../errors.js";
+/**
+ * Extended ChildProcess with Moonwall metadata
+ */
+export interface MoonwallProcess extends ChildProcess {
+    isMoonwallTerminating?: boolean;
+    moonwallTerminationReason?: string;
+    effectCleanup?: () => Promise<void>;
+}
+/**
+ * Configuration for launching a process
+ */
+export interface ProcessConfig {
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+    readonly name: string;
+    readonly logDirectory?: string;
+}
+/**
+ * Result of launching a process
+ */
+export interface ProcessLaunchResult {
+    readonly process: MoonwallProcess;
+    readonly logPath: string;
+}
+declare const ProcessManagerService_base: Context.TagClass<ProcessManagerService, "ProcessManagerService", {
+    /**
+     * Launch a process with manual cleanup function
+     * @param config Process configuration
+     * @returns Object containing the process launch result and a cleanup effect to be called manually
+     */
+    readonly launch: (config: ProcessConfig) => Effect.Effect<{
+        result: ProcessLaunchResult;
+        cleanup: Effect.Effect<void, ProcessError>;
+    }, NodeLaunchError | ProcessError>;
+}>;
+/**
+ * Service for managing process lifecycle with manual cleanup
+ */
+export declare class ProcessManagerService extends ProcessManagerService_base {
+}
+/**
+ * Live implementation of ProcessManagerService
+ */
+export declare const ProcessManagerServiceLive: Layer.Layer<ProcessManagerService, never, never>;
+export {};
+//# sourceMappingURL=ProcessManagerService.d.ts.map

package/dist/services/process/ProcessManagerService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessManagerService.d.ts","sourceRoot":"","sources":["../../../src/services/process/ProcessManagerService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAQ,MAAM,QAAQ,CAAC;AAGtD,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG9D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,qBAAqB;AAK7D;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;;IAQG;;;;OAIG;qBACc,CACf,MAAM,EAAE,aAAa,KAClB,MAAM,CAAC,MAAM,CAChB;QAAE,MAAM,EAAE,mBAAmB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;KAAE,EAC3E,eAAe,GAAG,YAAY,CAC/B;;AAhBL;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,0BAexC;CAAG;AAmON;;GAEG;AACH,eAAO,MAAM,yBAAyB,kDAEpC,CAAC"}

package/dist/services/process/ProcessManagerService.js

@@ -0,0 +1,162 @@
+import { Context, Effect, Layer, pipe } from "effect";
+import { Path } from "@effect/platform";
+import { NodePath } from "@effect/platform-node";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import { NodeLaunchError, ProcessError } from "../errors.js";
+import { createLogger } from "../../util/index.js";
+const logger = createLogger({ name: "ProcessManagerService" });
+/**
+ * Service for managing process lifecycle with manual cleanup
+ */
+export class ProcessManagerService extends Context.Tag("ProcessManagerService")() {
+}
+/**
+ * Generate log file path for a process using Effect Path
+ */
+const getLogPath = (config, pid) => pipe(Effect.all([Path.Path, Effect.sync(() => process.cwd())]), Effect.map(([pathService, cwd]) => {
+    const dirPath = config.logDirectory || pathService.join(cwd, "tmp", "node_logs");
+    const portArg = config.args.find((a) => a.includes("port"));
+    const port = portArg?.split("=")[1] || "unknown";
+    const baseName = pathService.basename(config.command);
+    return pathService
+        .join(dirPath, `${baseName}_node_${port}_${pid}.log`)
+        .replace(/node_node_undefined/g, "chopsticks");
+}), Effect.provide(NodePath.layer), Effect.mapError((cause) => new ProcessError({
+    cause,
+    operation: "spawn",
+})));
+/**
+ * Ensure log directory exists - using fs.promises for test compatibility
+ */
+const ensureLogDirectory = (dirPath) => Effect.tryPromise({
+    try: async () => {
+        try {
+            await fs.promises.access(dirPath);
+        }
+        catch {
+            await fs.promises.mkdir(dirPath, { recursive: true });
+        }
+    },
+    catch: (cause) => new ProcessError({
+        cause,
+        operation: "spawn",
+    }),
+});
+/**
+ * Spawn a child process - using node:child_process for test compatibility
+ */
+const spawnProcess = (config) => Effect.try({
+    try: () => {
+        const child = spawn(config.command, [...config.args]);
+        // Check for immediate spawn errors
+        child.on("error", (error) => {
+            logger.error(`Process spawn error: ${error}`);
+        });
+        return child;
+    },
+    catch: (cause) => new NodeLaunchError({
+        cause,
+        command: config.command,
+        args: [...config.args],
+    }),
+});
+const createLogStream = (logPath) => Effect.try({
+    try: () => fs.createWriteStream(logPath, { flags: "a" }),
+    catch: (cause) => new ProcessError({
+        cause,
+        operation: "spawn",
+    }),
+});
+/**
+ * Setup log handlers for process stdout/stderr using native WriteStream
+ */
+const setupLogHandlers = (process, logStream) => Effect.sync(() => {
+    const logHandler = (chunk) => {
+        logStream.write(chunk);
+    };
+    process.stdout?.on("data", logHandler);
+    process.stderr?.on("data", logHandler);
+});
+/**
+ * Helper to construct exit message based on exit context
+ */
+const constructExitMessage = (process, code, signal) => {
+    const timestamp = new Date().toISOString();
+    if (process.isMoonwallTerminating) {
+        return `${timestamp} [moonwall] process killed. reason: ${process.moonwallTerminationReason || "unknown"}\n`;
+    }
+    if (code !== null) {
+        return `${timestamp} [moonwall] process closed with status code ${code}\n`;
+    }
+    if (signal !== null) {
+        return `${timestamp} [moonwall] process terminated by signal ${signal}\n`;
+    }
+    return `${timestamp} [moonwall] process closed unexpectedly\n`;
+};
+/**
+ * Setup exit handler using native WriteStream
+ * The stream naturally survives Effect runtime shutdown
+ */
+const setupExitHandler = (process, logStream) => Effect.sync(() => {
+    process.once("close", (code, signal) => {
+        const message = constructExitMessage(process, code, signal);
+        logStream.end(message);
+    });
+});
+/**
+ * Kill a process gracefully with timeout
+ */
+const killProcess = (process, logStream, reason) => Effect.sync(() => {
+    process.isMoonwallTerminating = true;
+    process.moonwallTerminationReason = reason;
+}).pipe(Effect.flatMap(() => process.pid
+    ? Effect.try({
+        try: () => {
+            process.kill("SIGTERM");
+            // Give process time to exit and trigger close handler
+            // Close handler will write final message and close stream
+        },
+        catch: (cause) => new ProcessError({
+            cause,
+            pid: process.pid,
+            operation: "kill",
+        }),
+    })
+    : Effect.sync(() => logStream.end())));
+/**
+ * Launch a process with manual cleanup function
+ *
+ * This function spawns the process and returns both the process info and a cleanup effect.
+ * The cleanup effect should be executed manually when the process needs to be terminated.
+ * This allows the process to outlive the Effect scope and remain running for the test suite duration.
+ */
+const launchProcess = (config) => pipe(Effect.all([Path.Path, Effect.sync(() => config.logDirectory || undefined)]), Effect.flatMap(([pathService, customLogDir]) => {
+    const dirPath = customLogDir || pathService.join(process.cwd(), "tmp", "node_logs");
+    return pipe(ensureLogDirectory(dirPath), Effect.flatMap(() => spawnProcess(config)), Effect.flatMap((childProcess) => {
+        // Ensure PID is available before proceeding
+        if (childProcess.pid === undefined) {
+            return Effect.fail(new ProcessError({
+                cause: new Error("Process PID is undefined after spawn"),
+                operation: "spawn",
+            }));
+        }
+        return pipe(getLogPath(config, childProcess.pid), Effect.flatMap((logPath) => pipe(createLogStream(logPath), Effect.flatMap((logStream) => pipe(setupLogHandlers(childProcess, logStream), Effect.flatMap(() => setupExitHandler(childProcess, logStream)), Effect.map(() => {
+            const processInfo = {
+                process: childProcess,
+                logPath,
+            };
+            // Create cleanup effect that can be called manually later
+            const cleanup = pipe(killProcess(childProcess, logStream, "Manual cleanup requested"), Effect.catchAll((error) => Effect.sync(() => {
+                logger.error(`Failed to cleanly kill process: ${error}`);
+            })));
+            return { result: processInfo, cleanup };
+        }))))));
+    }));
+}), Effect.provide(NodePath.layer));
+/**
+ * Live implementation of ProcessManagerService
+ */
+export const ProcessManagerServiceLive = Layer.succeed(ProcessManagerService, {
+    launch: launchProcess,
+});

package/dist/services/process/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./ProcessManagerService.js";
+export * from "./launchNodeEffect.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/services/process/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/process/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,sCAAsC"}

package/dist/services/process/index.js

@@ -0,0 +1,2 @@
+export * from "./ProcessManagerService.js";
+export * from "./launchNodeEffect.js";

package/dist/services/process/launchNodeEffect.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Simplified Effect-based node launcher for integration with existing code
+ */
+import type { DevLaunchSpec } from "../../api/types/index.js";
+import type { ChildProcess } from "node:child_process";
+/**
+ * Configuration for launching a node
+ */
+export interface LaunchNodeConfig {
+    readonly command: string;
+    readonly args: string[];
+    readonly name: string;
+    readonly launchSpec?: DevLaunchSpec;
+    readonly isEthereumChain: boolean;
+}
+/**
+ * Result from launching a node
+ */
+export interface LaunchNodeResult {
+    readonly runningNode: ChildProcess;
+    readonly port: number;
+    readonly logPath: string;
+}
+/**
+ * Launch a blockchain node with Effect-based lifecycle management
+ *
+ * This function provides automatic resource management:
+ * - Process spawning with port 0 (OS assigns available port)
+ * - Port discovery via lsof
+ * - WebSocket readiness check
+ * - Automatic cleanup on scope closure
+ *
+ * @param config Node launch configuration
+ * @returns Promise resolving to node info and cleanup function
+ */
+export declare function launchNodeEffect(config: LaunchNodeConfig): Promise<{
+    result: LaunchNodeResult;
+    cleanup: () => Promise<void>;
+}>;
+//# sourceMappingURL=launchNodeEffect.d.ts.map

package/dist/services/process/launchNodeEffect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launchNodeEffect.d.ts","sourceRoot":"","sources":["../../../src/services/process/launchNodeEffect.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,iCAAiC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYvD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAOD;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAgHrE"}

package/dist/services/process/launchNodeEffect.js

@@ -0,0 +1,86 @@
+/**
+ * Simplified Effect-based node launcher for integration with existing code
+ */
+import { Effect, Layer } from "effect";
+import { ProcessManagerService, ProcessManagerServiceLive } from "./ProcessManagerService.js";
+import { RpcPortDiscoveryService, RpcPortDiscoveryServiceLive, } from "../network/RpcPortDiscoveryService.js";
+import { ProcessError } from "../errors.js";
+import { createLogger } from "../../util/index.js";
+const logger = createLogger({ name: "launchNodeEffect" });
+const debug = logger.debug.bind(logger);
+/**
+ * Combined layer with all dependencies
+ */
+const AllServicesLive = Layer.mergeAll(ProcessManagerServiceLive, RpcPortDiscoveryServiceLive);
+/**
+ * Launch a blockchain node with Effect-based lifecycle management
+ *
+ * This function provides automatic resource management:
+ * - Process spawning with port 0 (OS assigns available port)
+ * - Port discovery via lsof
+ * - WebSocket readiness check
+ * - Automatic cleanup on scope closure
+ *
+ * @param config Node launch configuration
+ * @returns Promise resolving to node info and cleanup function
+ */
+export async function launchNodeEffect(config) {
+    const startTime = Date.now();
+    logger.debug(`[T+0ms] Starting with command: ${config.command}, name: ${config.name}`);
+    const nodeConfig = {
+        isChopsticks: config.args.some((arg) => arg.includes("chopsticks.cjs")),
+        hasRpcPort: config.args.some((arg) => arg.includes("--rpc-port")),
+        hasPort: config.args.some((arg) => arg.includes("--port")),
+    };
+    const finalArgs = !nodeConfig.isChopsticks && !nodeConfig.hasRpcPort
+        ? [
+            ...config.args,
+            // If MOONWALL_RPC_PORT was pre-allocated by LaunchCommandParser, respect it; otherwise fall back to 0.
+            process.env.MOONWALL_RPC_PORT
+                ? `--rpc-port=${process.env.MOONWALL_RPC_PORT}`
+                : "--rpc-port=0",
+        ]
+        : config.args; // Chopsticks uses YAML config, or port already configured
+    debug(`Final args: ${JSON.stringify(finalArgs)}`);
+    const program = ProcessManagerService.pipe(Effect.flatMap((processManager) => Effect.sync(() => logger.debug(`[T+${Date.now() - startTime}ms] Launching process...`)).pipe(Effect.flatMap(() => processManager.launch({
+        command: config.command,
+        args: finalArgs,
+        name: config.name,
+    })))), Effect.flatMap(({ result: processResult, cleanup: processCleanup }) => Effect.sync(() => logger.debug(`[T+${Date.now() - startTime}ms] Process launched with PID: ${processResult.process.pid}`)).pipe(Effect.flatMap(() => {
+        const pid = processResult.process.pid;
+        if (pid === undefined) {
+            return Effect.fail(new ProcessError({
+                cause: new Error("Process PID is undefined after launch"),
+                operation: "check",
+            }));
+        }
+        return RpcPortDiscoveryService.pipe(Effect.flatMap((rpcDiscovery) => Effect.sync(() => logger.debug(`[T+${Date.now() - startTime}ms] Discovering RPC port for PID ${pid}...`)).pipe(Effect.flatMap(() => rpcDiscovery.discoverRpcPort({
+            pid,
+            isEthereumChain: config.isEthereumChain,
+            maxAttempts: 600, // Match PortDiscoveryService: 600 × 200ms = 120s
+        })))), Effect.mapError((error) => new ProcessError({
+            cause: error,
+            pid,
+            operation: "check",
+        })), Effect.flatMap((port) => Effect.sync(() => logger.debug(`[T+${Date.now() - startTime}ms] Discovered and validated RPC port: ${port}`)).pipe(Effect.map(() => ({
+            processInfo: {
+                process: processResult.process,
+                port,
+                logPath: processResult.logPath,
+            },
+            cleanup: processCleanup,
+        })))));
+    })))).pipe(Effect.provide(AllServicesLive));
+    // Run without Scope - cleanup is returned as a function
+    // We can't simply use scopes because:
+    //   1) when this effect is run in beforeAll() hook, we want the node to persist during test
+    //   2) If we hoist scope to outside, we accidentally spawn it when describe block is processed during test collection
+    return Effect.runPromise(Effect.map(program, ({ processInfo, cleanup }) => ({
+        result: {
+            runningNode: processInfo.process,
+            port: processInfo.port,
+            logPath: processInfo.logPath,
+        },
+        cleanup: () => Effect.runPromise(cleanup),
+    })));
+}

package/dist/util/functions/index.d.ts

@@ -0,0 +1,3 @@
+export * from "../../api/testing/index.js";
+export * from "../../internal/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/util/functions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/util/functions/index.ts"],"names":[],"mappings":"AACA,2CAA2C;AAG3C,wCAAwC"}

package/dist/util/functions/index.js

@@ -0,0 +1,4 @@
+// Re-export testing utilities from new location
+export * from "../../api/testing/index.js";
+// Re-export internal utilities from new location
+export * from "../../internal/index.js";

package/dist/util/index.d.ts

@@ -0,0 +1,4 @@
+export type { KeyringPair } from "@polkadot/keyring/types";
+export * from "../api/constants/index.js";
+export * from "./functions/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/util/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/util/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,0CAA0C;AAC1C,qCAAqC"}

package/dist/util/index.js

@@ -0,0 +1,2 @@
+export * from "../api/constants/index.js";
+export * from "./functions/index.js";