movehat 0.1.8 → 0.2.0

package/src/helpers/setupLocalTesting.ts

@@ -6,11 +6,34 @@ import { ForkManager } from "../fork/manager.js";
 import { ForkServer } from "../fork/server.js";
 import { LocalNodeManager } from "../node/LocalNodeManager.js";
 import { AccountManager } from "../core/AccountManager.js";
+import { logger } from "../ui/index.js";
 import type { LocalTestOptions } from "../types/config.js";
 
-let currentForkServer: ForkServer | null = null;
-let currentForkManager: ForkManager | null = null;
-let currentLocalNode: LocalNodeManager | null = null;
+/**
+ * Context returned by {@link setupLocalTesting}.
+ *
+ * Replaces the module-scoped singletons that previously tracked the
+ * "current" local node / fork server / fork manager. Each invocation now
+ * owns its own handles, so two parallel `setupLocalTesting` calls in the
+ * same process do not trample each other.
+ *
+ * @public The `runtime` and `teardown` fields are the supported surface.
+ *         `localNode`, `forkServer`, and `forkManager` are exposed for
+ *         escape hatches (e.g. mid-test `forkManager.resetState()`) but
+ *         their concrete shapes are considered `@internal` until the M5
+ *         TypeDoc pass formalizes the public API.
+ */
+export interface LocalTestingContext {
+  runtime: MovehatRuntime;
+  /** @internal */
+  localNode?: LocalNodeManager;
+  /** @internal */
+  forkServer?: ForkServer;
+  /** @internal */
+  forkManager?: ForkManager;
+  /** Stop the local node and/or fork server owned by this context. */
+  teardown: () => Promise<void>;
+}
 
 /**
  * Setup a local testing environment with either a local node or fork server
@@ -31,42 +54,65 @@ let currentLocalNode: LocalNodeManager | null = null;
  * 5. Returns runtime for reading data
  *
  * @param options Configuration options for local testing
- * @returns MovehatRuntime configured for local testing
+ * @returns LocalTestingContext with runtime and a teardown closure
  *
  * @example
  * ```typescript
  * // Local node mode (default) - Full blockchain, can deploy
- * const mh = await setupLocalTesting({
+ * const ctx = await setupLocalTesting({
  *   mode: 'local-node',
  *   accountLabels: ['alice', 'bob'],
- *   autoDeploy: ['counter'],  // ✅ Works!
- * });
- *
- * // Fork mode - Fast, read-only
- * const mh = await setupLocalTesting({
- *   mode: 'fork',
- *   accountLabels: ['alice', 'bob'],
- *   autoDeploy: ['counter'],  // ❌ Won't work (fork can't deploy)
+ *   autoDeploy: ['counter'],  // works
  * });
+ * // ...use ctx.runtime...
+ * await ctx.teardown();
  * ```
  */
 export async function setupLocalTesting(
   options: LocalTestOptions = {}
-): Promise<MovehatRuntime> {
-  // Default options
-  const mode = options.mode || 'local-node';  // Default to local node
-  const autoFund = options.autoFund !== false; // default true
-  const defaultBalance = options.defaultBalance || 100_000_000; // 100 APT
+): Promise<LocalTestingContext> {
+  const mode = options.mode || 'local-node';
+  const autoFund = options.autoFund !== false;
+  const defaultBalance = options.defaultBalance || 100_000_000;
   const accountLabels = options.accountLabels || ["deployer", "alice", "bob"];
 
-  console.log(`\n🔧 Setting up local testing environment...`);
-  console.log(`   Mode: ${mode}`);
-  console.log(`   Accounts: ${accountLabels.join(", ")}\n`);
+  logger.newline();
+  logger.step("Setting up local testing environment...");
+  logger.plain(`   Mode: ${mode}`);
+  logger.plain(`   Accounts: ${accountLabels.join(", ")}`);
+  logger.newline();
 
   if (mode === 'local-node') {
-    return await setupWithLocalNode(options, accountLabels, autoFund, defaultBalance);
+    const { runtime, localNode } = await setupWithLocalNode(
+      options, accountLabels, autoFund, defaultBalance
+    );
+    return {
+      runtime,
+      localNode,
+      teardown: async () => {
+        logger.newline();
+        logger.step("Stopping local testing environment...");
+        await localNode.stop();
+        logger.success("Environment stopped");
+        logger.newline();
+      },
+    };
   } else {
-    return await setupWithFork(options, accountLabels, autoFund, defaultBalance);
+    const { runtime, forkServer, forkManager } = await setupWithFork(
+      options, accountLabels, autoFund, defaultBalance
+    );
+    return {
+      runtime,
+      forkServer,
+      forkManager,
+      teardown: async () => {
+        logger.newline();
+        logger.step("Stopping local testing environment...");
+        await forkServer.stop();
+        logger.success("Environment stopped");
+        logger.newline();
+      },
+    };
   }
 }
 
@@ -78,15 +124,14 @@ async function setupWithLocalNode(
   accountLabels: readonly string[],
   autoFund: boolean,
   defaultBalance: number
-): Promise<MovehatRuntime> {
+): Promise<{ runtime: MovehatRuntime; localNode: LocalNodeManager }> {
   const nodeTestDir = options.nodeTestDir || join(process.cwd(), ".movehat", "local-node");
-  const nodeForceRestart = options.nodeForceRestart !== false; // default true
+  const nodeForceRestart = options.nodeForceRestart !== false;
   const nodeFaucetPort = options.nodeFaucetPort || 8081;
   const nodeApiPort = options.nodeApiPort || 8080;
   const nodeReadyPort = options.nodeReadyPort || 8070;
   const nodeSilent = options.nodeSilent ?? false;
 
-  // 1. Start local node
   const localNode = new LocalNodeManager({
     testDir: nodeTestDir,
     forceRestart: nodeForceRestart,
@@ -96,88 +141,96 @@ async function setupWithLocalNode(
     silent: nodeSilent,
   });
 
-  currentLocalNode = localNode;
-
   const nodeInfo = await localNode.start();
 
-  // 2. Generate accounts with AccountManager
-  console.log(`👥 Generating ${accountLabels.length} test accounts...`);
-  const accounts = AccountManager.createBatch(accountLabels);
-
-  for (const [label, account] of Object.entries(accounts)) {
-    console.log(`   ${label}: ${account.accountAddress.toString()}`);
-  }
-  console.log();
+  // Once the node is up, every later step (account creation, funding,
+  // runtime init, autoDeploy) is fallible. If any of them throws we
+  // must stop the node we just started — otherwise the child process
+  // leaks and port 8080 stays bound until the OS reaps it (manifests as
+  // "Movement command failed" on the next test:example run).
+  try {
+    logger.step(`Generating ${accountLabels.length} test accounts...`);
+    const accounts = AccountManager.createBatch(accountLabels);
+
+    for (const [label, account] of Object.entries(accounts)) {
+      logger.plain(`   ${label}: ${account.accountAddress.toString()}`);
+    }
+    logger.newline();
 
-  // 3. Fund accounts from local faucet
-  if (autoFund) {
-    const accountsList = Object.values(accounts);
-    await localNode.fundAccounts(accountsList, defaultBalance);
-  }
+    if (autoFund) {
+      const accountsList = Object.values(accounts);
+      await localNode.fundAccounts(accountsList, defaultBalance);
+    }
 
-  // 4. Initialize runtime pointing to local node
-  console.log(`⚙️  Initializing runtime for local network...`);
+    logger.step("Initializing runtime for local network...");
 
-  const deployerPrivateKey = AccountManager.exportPrivateKeys(["deployer"]).deployer;
+    const deployerPrivateKey = AccountManager.exportPrivateKeys(["deployer"]).deployer;
 
-  if (!deployerPrivateKey) {
-    throw new Error("Failed to get deployer private key");
-  }
+    if (!deployerPrivateKey) {
+      throw new Error("Failed to get deployer private key");
+    }
 
-  const runtime = await initRuntime({
-    network: "local",
-    configOverride: {
-      networks: {
-        local: {
-          url: `${nodeInfo.rpcUrl}/v1`,
-          chainId: "local",
+    const runtime = await initRuntime({
+      network: "local",
+      configOverride: {
+        networks: {
+          local: {
+            url: `${nodeInfo.rpcUrl}/v1`,
+            chainId: "local",
+          },
         },
+        accounts: [deployerPrivateKey],
       },
-      accounts: [deployerPrivateKey],
-    },
-  });
-
-  console.log(`✓ Runtime initialized\n`);
-
-  // 5. Auto-deploy modules if specified
-  if (options.autoDeploy && options.autoDeploy.length > 0) {
-    console.log(`📦 Auto-deploying ${options.autoDeploy.length} module(s)...`);
-
-    // Force redeploy in local-node mode (for testing)
-    const previousRedeploy = process.env.MH_CLI_REDEPLOY;
-    process.env.MH_CLI_REDEPLOY = 'true';
-
-    try {
-      for (const moduleName of options.autoDeploy) {
-        try {
-          console.log(`   Deploying ${moduleName}...`);
-          await runtime.deployContract(moduleName);
-          console.log(`   ✓ ${moduleName} deployed`);
-        } catch (error: any) {
-          console.error(`   ✗ Failed to deploy ${moduleName}: ${error.message}`);
-          throw error;
+    });
+
+    logger.success("Runtime initialized");
+    logger.newline();
+
+    if (options.autoDeploy && options.autoDeploy.length > 0) {
+      logger.step(`Auto-deploying ${options.autoDeploy.length} module(s)...`);
+
+      const previousRedeploy = process.env.MH_CLI_REDEPLOY;
+      process.env.MH_CLI_REDEPLOY = 'true';
+
+      try {
+        for (const moduleName of options.autoDeploy) {
+          try {
+            logger.plain(`   Deploying ${moduleName}...`);
+            await runtime.deployContract(moduleName);
+            logger.success(`${moduleName} deployed`, 2);
+          } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            logger.error(`Failed to deploy ${moduleName}: ${msg}`, 2);
+            throw error;
+          }
+        }
+      } finally {
+        if (previousRedeploy === undefined) {
+          delete process.env.MH_CLI_REDEPLOY;
+        } else {
+          process.env.MH_CLI_REDEPLOY = previousRedeploy;
         }
       }
-    } finally {
-      // Restore previous value
-      if (previousRedeploy === undefined) {
-        delete process.env.MH_CLI_REDEPLOY;
-      } else {
-        process.env.MH_CLI_REDEPLOY = previousRedeploy;
-      }
+
+      logger.newline();
     }
 
-    console.log();
+    logger.success("Local testing environment ready!");
+    logger.newline();
+    logger.plain(`   Mode: local-node`);
+    logger.plain(`   RPC: ${nodeInfo.rpcUrl}/v1`);
+    logger.plain(`   Faucet: ${nodeInfo.faucetUrl}`);
+    logger.plain(`   Accounts: ${Array.from(accountLabels).join(", ")}`);
+    logger.plain(`   Balance per account: ${defaultBalance / 100_000_000} APT`);
+    logger.newline();
+
+    return { runtime, localNode };
+  } catch (error) {
+    // Best-effort cleanup. Swallow the stop() error so the original
+    // setup failure surfaces unchanged.
+    await localNode.stop().catch(() => {});
+    throw error;
   }
-
-  console.log(`✅ Local testing environment ready!\n`);
-  console.log(`   Mode: local-node`);
-  console.log(`   RPC: ${nodeInfo.rpcUrl}/v1`);
-  console.log(`   Faucet: ${nodeInfo.faucetUrl}`);
-  console.log(`   Accounts: ${Array.from(accountLabels).join(", ")}`);
-  console.log(`   Balance per account: ${defaultBalance / 100_000_000} APT\n`);
-
-  return runtime;
 }
 
 /**
@@ -188,148 +241,114 @@ async function setupWithFork(
   accountLabels: readonly string[],
   autoFund: boolean,
   defaultBalance: number
-): Promise<MovehatRuntime> {
+): Promise<{ runtime: MovehatRuntime; forkServer: ForkServer; forkManager: ForkManager }> {
   const forkNetwork = options.forkNetwork || "testnet";
   const forkName = options.forkName || "test-local";
   const forkPort = options.forkPort || 8080;
-  const forkResetState = options.forkResetState !== false; // default true
+  const forkResetState = options.forkResetState !== false;
 
-  console.log(`   Fork network: ${forkNetwork}`);
-  console.log(`   Fork name: ${forkName}`);
-  console.log(`   Server port: ${forkPort}\n`);
+  logger.plain(`   Fork network: ${forkNetwork}`);
+  logger.plain(`   Fork name: ${forkName}`);
+  logger.plain(`   Server port: ${forkPort}`);
+  logger.newline();
 
-  // Warn about auto-deploy in fork mode
   if (options.autoDeploy && options.autoDeploy.length > 0) {
-    console.warn(`⚠️  WARNING: Auto-deploy doesn't work in fork mode (read-only).`);
-    console.warn(`   Switch to 'local-node' mode for deployment support.\n`);
+    logger.warning("Auto-deploy doesn't work in fork mode (read-only).");
+    logger.plain("   Switch to 'local-node' mode for deployment support.");
+    logger.newline();
   }
 
-  // 1. Setup fork
   const forkPath = join(process.cwd(), ".movehat", "forks", forkName);
   const forkManager = new ForkManager(forkPath);
-  currentForkManager = forkManager;
 
   const forkExists = existsSync(join(forkPath, "metadata.json"));
 
   if (!forkExists) {
-    console.log(`📸 Creating fork from ${forkNetwork}...`);
+    logger.step(`Creating fork from ${forkNetwork}...`);
     const testnetRpc = "https://testnet.movementnetwork.xyz/v1";
-    await forkManager.initialize(testnetRpc, forkNetwork);
-    console.log(`✓ Fork created at ${forkPath}\n`);
+    await forkManager.initialize(testnetRpc, forkNetwork, options.forkApiKey);
+    logger.success(`Fork created at ${forkPath}`);
+    logger.newline();
   } else {
-    console.log(`✓ Loading existing fork from ${forkPath}`);
+    logger.success(`Loading existing fork from ${forkPath}`);
+    // setApiKey BEFORE load() so the reconstructed MovementApiClient
+    // picks up the header. load() rebuilds the client using current
+    // apiKey state.
+    if (options.forkApiKey !== undefined) {
+      forkManager.setApiKey(options.forkApiKey);
+    }
     forkManager.load();
 
     if (forkResetState) {
-      console.log(`🔄 Resetting fork state...`);
+      logger.step("Resetting fork state...");
       await forkManager.resetState();
     }
 
-    console.log();
+    logger.newline();
   }
 
-  // 2. Start fork server
-  console.log(`🚀 Starting fork server on port ${forkPort}...`);
+  logger.step(`Starting fork server on port ${forkPort}...`);
   const forkServer = new ForkServer(forkPath, forkPort);
-  currentForkServer = forkServer;
 
   await forkServer.start();
-  console.log(`✓ Fork server running at http://localhost:${forkPort}\n`);
+  logger.success(`Fork server running at http://localhost:${forkPort}`);
+  logger.newline();
 
-  await new Promise((resolve) => setTimeout(resolve, 500));
+  // Same cleanup-on-failure pattern as setupWithLocalNode: once the
+  // fork server is listening, any later throw must stop the server or
+  // we leak the listener.
+  try {
+    await new Promise((resolve) => setTimeout(resolve, 500));
 
-  // 3. Generate accounts
-  console.log(`👥 Generating ${accountLabels.length} test accounts...`);
-  const accounts = AccountManager.createBatch(accountLabels);
+    logger.step(`Generating ${accountLabels.length} test accounts...`);
+    const accounts = AccountManager.createBatch(accountLabels);
 
-  for (const [label, account] of Object.entries(accounts)) {
-    console.log(`   ${label}: ${account.accountAddress.toString()}`);
-  }
-  console.log();
+    for (const [label, account] of Object.entries(accounts)) {
+      logger.plain(`   ${label}: ${account.accountAddress.toString()}`);
+    }
+    logger.newline();
 
-  // 4. Fund accounts in fork
-  if (autoFund) {
-    const addresses = Object.values(accounts).map((acc) =>
-      acc.accountAddress.toString()
-    );
-    await forkManager.fundMultipleAccounts(addresses, defaultBalance);
-  }
+    if (autoFund) {
+      const addresses = Object.values(accounts).map((acc) =>
+        acc.accountAddress.toString()
+      );
+      await forkManager.fundMultipleAccounts(addresses, defaultBalance);
+    }
 
-  // 5. Initialize runtime pointing to fork
-  console.log(`⚙️  Initializing runtime for local network...`);
+    logger.step("Initializing runtime for local network...");
 
-  const deployerPrivateKey = AccountManager.exportPrivateKeys(["deployer"]).deployer;
+    const deployerPrivateKey = AccountManager.exportPrivateKeys(["deployer"]).deployer;
 
-  if (!deployerPrivateKey) {
-    throw new Error("Failed to get deployer private key");
-  }
+    if (!deployerPrivateKey) {
+      throw new Error("Failed to get deployer private key");
+    }
 
-  const runtime = await initRuntime({
-    network: "local",
-    configOverride: {
-      networks: {
-        local: {
-          url: `http://localhost:${forkPort}/v1`,
-          chainId: "local",
+    const runtime = await initRuntime({
+      network: "local",
+      configOverride: {
+        networks: {
+          local: {
+            url: `http://localhost:${forkPort}/v1`,
+            chainId: "local",
+          },
         },
+        accounts: [deployerPrivateKey],
       },
-      accounts: [deployerPrivateKey],
-    },
-  });
-
-  console.log(`✓ Runtime initialized\n`);
-  console.log(`✅ Local testing environment ready!\n`);
-  console.log(`   Mode: fork (read-only)`);
-  console.log(`   RPC: http://localhost:${forkPort}/v1`);
-  console.log(`   Accounts: ${Array.from(accountLabels).join(", ")}`);
-  console.log(`   Balance per account: ${defaultBalance / 100_000_000} APT\n`);
-
-  return runtime;
-}
-
-/**
- * Stop the local testing environment (cleanup)
- */
-export async function stopLocalTesting(): Promise<void> {
-  console.log(`\n🛑 Stopping local testing environment...`);
-
-  // Stop local node if running
-  if (currentLocalNode) {
-    await currentLocalNode.stop();
-    currentLocalNode = null;
-  }
-
-  // Stop fork server if running
-  if (currentForkServer) {
-    await currentForkServer.stop();
-    currentForkServer = null;
-    currentForkManager = null;
-  }
-
-  console.log(`✓ Environment stopped\n`);
-}
-
-/**
- * Get the current fork manager (if fork mode is active)
- */
-export function getCurrentForkManager(): ForkManager | null {
-  return currentForkManager;
-}
-
-/**
- * Get the current local node (if local node mode is active)
- */
-export function getCurrentLocalNode(): LocalNodeManager | null {
-  return currentLocalNode;
-}
-
-/**
- * Reset fork state to initial snapshot (fork mode only)
- */
-export async function resetForkState(): Promise<void> {
-  if (currentForkManager) {
-    await currentForkManager.resetState();
-  } else {
-    console.warn("Warning: No active fork manager to reset");
+    });
+
+    logger.success("Runtime initialized");
+    logger.newline();
+    logger.success("Local testing environment ready!");
+    logger.newline();
+    logger.plain(`   Mode: fork (read-only)`);
+    logger.plain(`   RPC: http://localhost:${forkPort}/v1`);
+    logger.plain(`   Accounts: ${Array.from(accountLabels).join(", ")}`);
+    logger.plain(`   Balance per account: ${defaultBalance / 100_000_000} APT`);
+    logger.newline();
+
+    return { runtime, forkServer, forkManager };
+  } catch (error) {
+    await forkServer.stop().catch(() => {});
+    throw error;
   }
 }