@hardkas/node-runner 0.2.2-alpha → 0.3.0-alpha

package/dist/index.d.ts

@@ -12,6 +12,7 @@ interface DockerKaspadOptions {
     readonly ports?: Partial<KaspadPorts>;
     readonly dataDir?: string;
     readonly detach?: boolean;
+    readonly allowFloatingImage?: boolean;
 }
 interface KaspadNodeStatus {
     readonly containerName: string;
@@ -21,9 +22,27 @@ interface KaspadNodeStatus {
     readonly statusText?: string;
     readonly ports: KaspadPorts;
     readonly dataDir: string;
+    readonly rpcUrl: string;
+    readonly rpcReady: boolean;
+    readonly transports: {
+        readonly grpc: {
+            readonly port: number;
+            readonly ready: boolean;
+        };
+        readonly borsh: {
+            readonly port: number;
+            readonly ready: boolean;
+        };
+        readonly json: {
+            readonly port: number;
+            readonly ready: boolean;
+            readonly url: string;
+        };
+    };
+    readonly lastError?: string | null;
 }
 
-declare const DEFAULT_IMAGE = "kaspanet/rusty-kaspad:latest";
+declare const DEFAULT_IMAGE = "kaspanet/rusty-kaspad:v1.1.0";
 declare const DEFAULT_CONTAINER_NAME = "hardkas-kaspad-simnet";
 declare const DEFAULT_NETWORK = "simnet";
 declare const DEFAULT_PORTS: KaspadPorts;
@@ -31,11 +50,19 @@ declare class DockerKaspadRunner {
     private readonly options;
     constructor(options?: DockerKaspadOptions);
     start(): Promise<KaspadNodeStatus>;
+    private ensurePortsAvailable;
+    private isPortAvailable;
     stop(): Promise<KaspadNodeStatus>;
+    private checkTransportReady;
     status(): Promise<KaspadNodeStatus>;
+    restart(): Promise<KaspadNodeStatus>;
+    reset(options?: {
+        removeData?: boolean;
+    }): Promise<KaspadNodeStatus>;
     logs(options?: {
         tail?: number;
-    }): Promise<string>;
+        follow?: boolean;
+    }): Promise<string | void>;
 }
 
 export { DEFAULT_CONTAINER_NAME, DEFAULT_IMAGE, DEFAULT_NETWORK, DEFAULT_PORTS, type DockerKaspadOptions, DockerKaspadRunner, type KaspadNetwork, type KaspadNodeStatus, type KaspadPorts };

package/dist/index.js

@@ -3,7 +3,12 @@ import { execa } from "execa";
 import fs from "fs/promises";
 import path from "path";
 import { existsSync } from "fs";
-var DEFAULT_IMAGE = "kaspanet/rusty-kaspad:latest";
+import net from "net";
+import {
+  checkKaspaRpcHealth,
+  waitForKaspaRpcReady
+} from "@hardkas/kaspa-rpc";
+var DEFAULT_IMAGE = "kaspanet/rusty-kaspad:v1.1.0";
 var DEFAULT_CONTAINER_NAME = "hardkas-kaspad-simnet";
 var DEFAULT_NETWORK = "simnet";
 var DEFAULT_PORTS = {
@@ -25,7 +30,8 @@ var DockerKaspadRunner = class {
         ...DEFAULT_PORTS,
         ...options?.ports || {}
       },
-      detach: options?.detach ?? true
+      detach: options?.detach ?? true,
+      allowFloatingImage: options?.allowFloatingImage ?? false
     };
   }
   async start() {
@@ -38,6 +44,25 @@ var DockerKaspadRunner = class {
     } catch (e) {
       throw new Error("Docker is not available. Please install Docker to run a real Kaspa node.");
     }
+    if (this.options.image.endsWith(":latest") && !this.options.allowFloatingImage) {
+      console.warn("\n  \u26A0\uFE0F  WARNING: Using a floating Docker tag (:latest) reduces reproducibility.\n");
+    }
+    const network = this.options.network;
+    let networkFlag = "";
+    if (network === "simnet") {
+      networkFlag = "--simnet";
+    } else if (network.startsWith("testnet")) {
+      networkFlag = "--testnet";
+    } else if (network === "devnet") {
+      networkFlag = "--devnet";
+    } else if (network === "mainnet") {
+      throw new Error(
+        "Local Docker node for 'mainnet' is currently unsupported by HardKAS.\nPlease use a remote RPC provider or a manual kaspad setup for mainnet operations."
+      );
+    } else {
+      throw new Error(`Unsupported network for Docker runner: ${network}`);
+    }
+    await this.ensurePortsAvailable();
     const absoluteDataDir = path.isAbsolute(this.options.dataDir) ? this.options.dataDir : path.resolve(this.options.cwd, this.options.dataDir);
     if (!existsSync(absoluteDataDir)) {
       await fs.mkdir(absoluteDataDir, { recursive: true });
@@ -52,11 +77,11 @@ var DockerKaspadRunner = class {
       "--name",
       this.options.containerName,
       "-p",
-      `${this.options.ports.rpc}:${this.options.ports.rpc}`,
+      `127.0.0.1:${this.options.ports.rpc}:${this.options.ports.rpc}`,
       "-p",
-      `${this.options.ports.borshRpc}:${this.options.ports.borshRpc}`,
+      `127.0.0.1:${this.options.ports.borshRpc}:${this.options.ports.borshRpc}`,
       "-p",
-      `${this.options.ports.jsonRpc}:${this.options.ports.jsonRpc}`,
+      `127.0.0.1:${this.options.ports.jsonRpc}:${this.options.ports.jsonRpc}`,
       "-v",
       `${absoluteDataDir}:/app/data`,
       this.options.image,
@@ -65,14 +90,56 @@ var DockerKaspadRunner = class {
       "--nologfiles",
       "--disable-upnp",
       "--utxoindex",
-      "--simnet",
+      ...networkFlag ? [networkFlag] : [],
       `--rpclisten=0.0.0.0:${this.options.ports.rpc}`,
       `--rpclisten-borsh=0.0.0.0:${this.options.ports.borshRpc}`,
       `--rpclisten-json=0.0.0.0:${this.options.ports.jsonRpc}`
     ];
     await execa("docker", args);
+    const rpcUrl = `http://127.0.0.1:${this.options.ports.jsonRpc}`;
+    const health = await waitForKaspaRpcReady({
+      url: rpcUrl,
+      maxWaitMs: 6e4,
+      intervalMs: 1e3
+    });
+    if (!health.ready) {
+      throw new Error(
+        `Kaspad RPC failed to become ready within 60s.
+  Container: ${this.options.containerName}
+  Image: ${this.options.image}
+  RPC: ${rpcUrl}
+  Last Error: ${health.lastError || "Timeout"}
+
+  Try checking logs: hardkas node logs --tail 200`
+      );
+    }
     return this.status();
   }
+  async ensurePortsAvailable() {
+    const ports = [this.options.ports.rpc, this.options.ports.borshRpc, this.options.ports.jsonRpc];
+    for (const port of ports) {
+      const available = await this.isPortAvailable(port);
+      if (!available) {
+        throw new Error(
+          `Port ${port} is already in use on the host. Cannot start node.
+  - Stop any existing process using this port.
+  - Or change the port in hardkas.config.ts.
+  - Or run 'hardkas node reset --yes' if it's a stale container.`
+        );
+      }
+    }
+  }
+  isPortAvailable(port) {
+    return new Promise((resolve) => {
+      const server = net.createServer();
+      server.once("error", () => resolve(false));
+      server.once("listening", () => {
+        server.close();
+        resolve(true);
+      });
+      server.listen(port, "127.0.0.1");
+    });
+  }
   async stop() {
     try {
       await execa("docker", ["stop", this.options.containerName]);
@@ -81,7 +148,27 @@ var DockerKaspadRunner = class {
     }
     return this.status();
   }
+  async checkTransportReady(port) {
+    return new Promise((resolve) => {
+      const socket = new net.Socket();
+      socket.setTimeout(1e3);
+      socket.once("connect", () => {
+        socket.destroy();
+        resolve(true);
+      });
+      socket.once("timeout", () => {
+        socket.destroy();
+        resolve(false);
+      });
+      socket.once("error", () => {
+        socket.destroy();
+        resolve(false);
+      });
+      socket.connect(port, "127.0.0.1");
+    });
+  }
   async status() {
+    const rpcUrl = `http://127.0.0.1:${this.options.ports.jsonRpc}`;
     try {
       const { stdout } = await execa("docker", [
         "inspect",
@@ -90,6 +177,19 @@ var DockerKaspadRunner = class {
         this.options.containerName
       ]);
       const running = stdout.trim() === "running";
+      let jsonReady = false;
+      let grpcReady = false;
+      let borshReady = false;
+      let lastError = null;
+      if (running) {
+        const health = await checkKaspaRpcHealth({ url: rpcUrl, timeoutMs: 2e3 });
+        jsonReady = health.ready;
+        lastError = health.lastError || null;
+        [grpcReady, borshReady] = await Promise.all([
+          this.checkTransportReady(this.options.ports.rpc),
+          this.checkTransportReady(this.options.ports.borshRpc)
+        ]);
+      }
       return {
         containerName: this.options.containerName,
         image: this.options.image,
@@ -97,7 +197,16 @@ var DockerKaspadRunner = class {
         running,
         statusText: stdout.trim(),
         ports: this.options.ports,
-        dataDir: this.options.dataDir
+        dataDir: this.options.dataDir,
+        rpcUrl,
+        rpcReady: jsonReady,
+        // Unified readiness
+        transports: {
+          grpc: { port: this.options.ports.rpc, ready: grpcReady },
+          borsh: { port: this.options.ports.borshRpc, ready: borshReady },
+          json: { port: this.options.ports.jsonRpc, ready: jsonReady, url: rpcUrl }
+        },
+        lastError
       };
     } catch (e) {
       return {
@@ -107,19 +216,45 @@ var DockerKaspadRunner = class {
         running: false,
         statusText: "not-found",
         ports: this.options.ports,
-        dataDir: this.options.dataDir
+        dataDir: this.options.dataDir,
+        rpcUrl,
+        rpcReady: false,
+        transports: {
+          grpc: { port: this.options.ports.rpc, ready: false },
+          borsh: { port: this.options.ports.borshRpc, ready: false },
+          json: { port: this.options.ports.jsonRpc, ready: false, url: rpcUrl }
+        },
+        lastError: "Container not found"
       };
     }
   }
+  async restart() {
+    await this.stop();
+    return this.start();
+  }
+  async reset(options = { removeData: true }) {
+    await this.stop();
+    if (options.removeData) {
+      const absoluteDataDir = path.isAbsolute(this.options.dataDir) ? this.options.dataDir : path.resolve(this.options.cwd, this.options.dataDir);
+      if (existsSync(absoluteDataDir)) {
+        await fs.rm(absoluteDataDir, { recursive: true, force: true });
+      }
+    }
+    return this.status();
+  }
   async logs(options) {
     try {
       const tail = options?.tail || 100;
-      const { stdout } = await execa("docker", [
-        "logs",
-        "--tail",
-        tail.toString(),
-        this.options.containerName
-      ]);
+      const args = ["logs", "--tail", tail.toString()];
+      if (options?.follow) {
+        args.push("-f");
+        await execa("docker", [...args, this.options.containerName], {
+          stdout: "inherit",
+          stderr: "inherit"
+        });
+        return;
+      }
+      const { stdout } = await execa("docker", [...args, this.options.containerName]);
       return stdout;
     } catch (e) {
       throw new Error(`Could not get logs for container ${this.options.containerName}. Is it running?`);

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@hardkas/node-runner",
-  "version": "0.2.2-alpha",
+  "version": "0.3.0-alpha",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "execa": "^9.5.2"
+    "execa": "^9.5.2",
+    "@hardkas/core": "0.3.0-alpha",
+    "@hardkas/kaspa-rpc": "0.3.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
-    "@hardkas/config": "0.2.2-alpha"
+    "@hardkas/config": "0.3.0-alpha"
   },
   "license": "MIT",
   "author": "Javier Rodriguez",