movehat 0.1.8 → 0.2.0

package/src/helpers/testFixtures.ts

@@ -2,7 +2,8 @@ import type { Account } from "@aptos-labs/ts-sdk";
 import type { MovehatRuntime } from "../types/runtime.js";
 import type { MoveContract } from "../core/contract.js";
 import { AccountManager } from "../core/AccountManager.js";
-import { setupLocalTesting, stopLocalTesting } from "./setupLocalTesting.js";
+import { setupLocalTesting } from "./setupLocalTesting.js";
+import { logger } from "../ui/index.js";
 import type { LocalTestOptions } from "../types/config.js";
 
 /**
@@ -24,6 +25,16 @@ export interface TestFixture<TModules extends string = string> {
 
   /** Deployed contracts by module name - type-safe based on modules parameter */
   contracts: Record<TModules, MoveContract>;
+
+  /**
+   * Stop the local node / fork server this fixture started.
+   *
+   * Does **not** clear the shared `AccountManager` pool — clearing it
+   * would break parallel `setupTestFixture` invocations that share the
+   * pool. The pool grows for the lifetime of the process; the process
+   * exit reclaims it.
+   */
+  teardown: () => Promise<void>;
 }
 
 /**
@@ -38,43 +49,30 @@ export interface TestFixture<TModules extends string = string> {
  * @param modules Array of module names to auto-deploy
  * @param accountLabels Optional array of account labels (defaults to ['alice', 'bob'])
  * @param options Optional LocalTestOptions for advanced configuration
- * @returns TestFixture with runtime, accounts, and contracts
+ * @returns TestFixture with runtime, accounts, contracts, and a teardown closure
  *
  * @example
  * ```typescript
- * import { setupTestFixture } from "movehat/helpers";
+ * import { setupTestFixture, type TestFixture } from "movehat/helpers";
  *
  * describe("Counter Contract", () => {
- *   let fixture: TestFixture;
+ *   let fixture: TestFixture<"counter">;
  *
  *   before(async function () {
- *     this.timeout(60000); // Allow time for fork + deployment
- *
- *     fixture = await setupTestFixture(['counter'], ['alice', 'bob']);
+ *     this.timeout(60000);
+ *     fixture = await setupTestFixture(['counter'] as const, ['alice', 'bob']);
  *   });
  *
- *   it("should initialize with value 0", async () => {
- *     const counter = fixture.contracts.counter;
- *     const value = await counter.view<number>("get", [
- *       fixture.accounts.deployer.accountAddress.toString()
- *     ]);
- *
- *     expect(value).to.equal(0);
+ *   after(async () => {
+ *     await fixture.teardown();
  *   });
  *
- *   it("alice can increment counter", async () => {
+ *   it("alice can increment", async () => {
  *     const tx = await fixture.contracts.counter.call(
- *       fixture.accounts.alice,
- *       "increment",
- *       []
+ *       fixture.accounts.alice, "increment", []
  *     );
- *
  *     expect(tx.success).to.be.true;
  *   });
- *
- *   after(async () => {
- *     await teardownTestFixture();
- *   });
  * });
  * ```
  */
@@ -83,85 +81,76 @@ export async function setupTestFixture<TModules extends readonly string[]>(
   accountLabels: string[] = ["alice", "bob"],
   options: Partial<LocalTestOptions> = {}
 ): Promise<TestFixture<TModules[number]>> {
-  console.log(`\n🧪 Setting up test fixture...`);
-  console.log(`   Modules to deploy: ${modules.join(", ")}`);
-  console.log(`   Account labels: deployer, ${accountLabels.join(", ")}\n`);
+  logger.newline();
+  logger.step("Setting up test fixture...");
+  logger.plain(`   Modules to deploy: ${modules.join(", ")}`);
+  logger.plain(`   Account labels: deployer, ${accountLabels.join(", ")}`);
+  logger.newline();
 
-  // Ensure 'deployer' is always in the account labels
   const allLabels = ["deployer", ...accountLabels.filter((l) => l !== "deployer")];
 
-  // Setup local testing environment with auto-deploy
   const setupOptions: LocalTestOptions = {
     ...options,
     accountLabels: allLabels,
-    autoDeploy: modules, // Auto-deploy specified modules
+    autoDeploy: modules,
   };
 
-  const mh = await setupLocalTesting(setupOptions);
-
-  // Get all labeled accounts
-  const labeledAccounts = AccountManager.getLabeledAccounts();
-
-  // Build accounts object with required accounts
-  const accounts: any = {
-    deployer: labeledAccounts.deployer!,
-  };
+  const ctx = await setupLocalTesting(setupOptions);
+
+  // Assembly is fallible — a missing deployment address (autoDeploy
+  // silently failed) or any unexpected throw would leak the started
+  // infrastructure. Tear down ctx on failure; the outer caller sees
+  // the original assembly error unchanged.
+  try {
+    const mh = ctx.runtime;
+
+    const labeledAccounts = AccountManager.getLabeledAccounts();
+
+    // any: TestFixture.accounts has a structural shape with required
+    // `deployer/alice/bob` plus a `[key: string]: Account` index. The
+    // builder fills the index dynamically; typing this as the exact
+    // intersection would require a generic over `accountLabels` and
+    // produce noisy errors for the dynamic key assignment below.
+    const accounts: any = {
+      // non-null: setupLocalTesting → setupWithLocalNode/Fork unconditionally
+      // funds the deployer account via accountLabels[0]; deployer is always
+      // first by construction at L93 above.
+      deployer: labeledAccounts.deployer!,
+    };
+
+    for (const label of accountLabels) {
+      accounts[label] = labeledAccounts[label] || AccountManager.getOrCreateLabeled(label);
+    }
 
-  // Add other labeled accounts
-  for (const label of accountLabels) {
-    accounts[label] = labeledAccounts[label] || AccountManager.getOrCreateLabeled(label);
-  }
+    const contracts = {} as Record<TModules[number], MoveContract>;
 
-  // Build contracts object - TypeScript will infer the correct type
-  const contracts = {} as Record<TModules[number], MoveContract>;
+    for (const moduleName of modules) {
+      const deploymentAddress = mh.getDeploymentAddress(moduleName);
 
-  for (const moduleName of modules) {
-    // Get deployed contract instance
-    const deploymentAddress = mh.getDeploymentAddress(moduleName);
+      if (!deploymentAddress) {
+        throw new Error(
+          `Module "${moduleName}" was not deployed. Check auto-deploy logs.`
+        );
+      }
 
-    if (!deploymentAddress) {
-      throw new Error(
-        `Module "${moduleName}" was not deployed. Check auto-deploy logs.`
-      );
+      contracts[moduleName as TModules[number]] = mh.getContract(deploymentAddress, moduleName);
+      logger.success(`Contract "${moduleName}" ready at ${deploymentAddress}`, 2);
     }
 
-    contracts[moduleName as TModules[number]] = mh.getContract(deploymentAddress, moduleName);
-    console.log(`   ✓ Contract "${moduleName}" ready at ${deploymentAddress}`);
+    logger.newline();
+    logger.success("Test fixture ready!");
+    logger.newline();
+
+    return {
+      mh,
+      accounts,
+      contracts,
+      teardown: ctx.teardown,
+    } as TestFixture<TModules[number]>;
+  } catch (error) {
+    await ctx.teardown().catch(() => {});
+    throw error;
   }
-
-  console.log(`\n✅ Test fixture ready!\n`);
-
-  return {
-    mh,
-    accounts,
-    contracts,
-  } as TestFixture<TModules[number]>;
-}
-
-/**
- * Teardown test fixture and cleanup resources
- *
- * Call this in your test suite's `after` hook to properly cleanup:
- * - Stops fork server
- * - Clears account pool
- *
- * @example
- * ```typescript
- * after(async () => {
- *   await teardownTestFixture();
- * });
- * ```
- */
-export async function teardownTestFixture(): Promise<void> {
-  console.log(`\n🧹 Tearing down test fixture...`);
-
-  // Stop fork server
-  await stopLocalTesting();
-
-  // Clear account pool for test isolation
-  AccountManager.clearPool();
-
-  console.log(`✓ Teardown complete\n`);
 }
 
 /**
@@ -170,53 +159,52 @@ export async function teardownTestFixture(): Promise<void> {
  *
  * @param accountLabels Account labels to create (defaults to ['alice', 'bob'])
  * @param options Optional LocalTestOptions
- * @returns Partial TestFixture (without contracts)
- *
- * @example
- * ```typescript
- * let fixture: Partial<TestFixture>;
- *
- * before(async function () {
- *   this.timeout(30000);
- *   fixture = await setupMinimalFixture(['alice', 'bob', 'charlie']);
- * });
- *
- * it("should deploy contract manually", async () => {
- *   await fixture.mh!.deployContract("counter");
- *   // ...
- * });
- * ```
+ * @returns Partial TestFixture (without contracts) plus a teardown closure
  */
 export async function setupMinimalFixture(
   accountLabels: string[] = ["alice", "bob"],
   options: Partial<LocalTestOptions> = {}
 ): Promise<Omit<TestFixture, "contracts">> {
-  console.log(`\n🧪 Setting up minimal test fixture (no auto-deploy)...`);
+  logger.newline();
+  logger.step("Setting up minimal test fixture (no auto-deploy)...");
 
   const allLabels = ["deployer", ...accountLabels.filter((l) => l !== "deployer")];
 
   const setupOptions: LocalTestOptions = {
     ...options,
     accountLabels: allLabels,
-    autoDeploy: [], // No auto-deploy
+    autoDeploy: [],
   };
 
-  const mh = await setupLocalTesting(setupOptions);
+  const ctx = await setupLocalTesting(setupOptions);
 
-  const labeledAccounts = AccountManager.getLabeledAccounts();
+  // Same teardown-on-assembly-failure pattern as setupTestFixture.
+  try {
+    const mh = ctx.runtime;
 
-  const accounts: any = {
-    deployer: labeledAccounts.deployer!,
-  };
+    const labeledAccounts = AccountManager.getLabeledAccounts();
 
-  for (const label of accountLabels) {
-    accounts[label] = labeledAccounts[label] || AccountManager.getOrCreateLabeled(label);
-  }
+    // any: see setupTestFixture above — same dynamic-key builder pattern.
+    const accounts: any = {
+      // non-null: deployer is unconditionally added to allLabels at L156 above.
+      deployer: labeledAccounts.deployer!,
+    };
 
-  console.log(`\n✅ Minimal fixture ready!\n`);
+    for (const label of accountLabels) {
+      accounts[label] = labeledAccounts[label] || AccountManager.getOrCreateLabeled(label);
+    }
 
-  return {
-    mh,
-    accounts,
-  };
+    logger.newline();
+    logger.success("Minimal fixture ready!");
+    logger.newline();
+
+    return {
+      mh,
+      accounts,
+      teardown: ctx.teardown,
+    };
+  } catch (error) {
+    await ctx.teardown().catch(() => {});
+    throw error;
+  }
 }

package/src/index.ts

@@ -2,8 +2,10 @@
 export * from "./helpers/index.js";
 export type { MovehatConfig } from "./types/config.js";
 
-// Export Movehat Runtime Environment
-export { initRuntime, getRuntime, getMovehat, mh } from "./runtime.js";
+// Movehat Runtime Environment. `initRuntime` is a public utility but
+// external callers should prefer Harness; it's the construction primitive
+// `Harness.createLive` uses.
+export { initRuntime } from "./runtime.js";
 export type { MovehatRuntime, NetworkInfo } from "./types/runtime.js";
 
 // Export Fork system
@@ -14,4 +16,8 @@ export { ForkServer } from "./fork/server.js";
 export type { ForkMetadata, AccountState, LedgerInfo, AccountData, AccountResource } from "./types/fork.js";
 
 // Export custom errors
-export { ModuleAlreadyDeployedError } from "./errors.js";
+export { ModuleAlreadyDeployedError, PostPublishError } from "./errors.js";
+
+// Export Harness (Hardhat-style API — primary public surface from M2 onward)
+export { Harness, HarnessDisposedError } from "./harness/index.js";
+export type { HarnessMode } from "./harness/index.js";

package/src/node/LocalNodeManager.ts

@@ -1,7 +1,12 @@
-import { spawn, ChildProcess } from "child_process";
 import { existsSync, rmSync } from "fs";
 import { join } from "path";
 import { Account } from "@aptos-labs/ts-sdk";
+import {
+  defaultChildProcessAdapter,
+  type ChildProcessAdapter,
+  type SpawnedProcess,
+} from "../utils/childProcessAdapter.js";
+import { logger } from "../ui/index.js";
 
 export interface LocalNodeOptions {
   testDir?: string;           // Directory for node data (default: .movehat/local-node)
@@ -10,6 +15,11 @@ export interface LocalNodeOptions {
   apiPort?: number;           // API/RPC port (default: 8080)
   readyPort?: number;         // Ready server port (default: 8070)
   silent?: boolean;           // Suppress node output
+  /**
+   * Override the child-process adapter. Tests inject a fake adapter so
+   * the daemon spawn never reaches the real `movement` binary.
+   */
+  adapter?: ChildProcessAdapter;
 }
 
 export interface LocalNodeInfo {
@@ -29,11 +39,14 @@ export interface LocalNodeInfo {
  * - Cleanup on shutdown
  */
 export class LocalNodeManager {
-  private process: ChildProcess | null = null;
-  private options: Required<LocalNodeOptions>;
+  private spawned: SpawnedProcess | null = null;
+  private killed = false;
+  private options: Required<Omit<LocalNodeOptions, "adapter">>;
+  private readonly adapter: ChildProcessAdapter;
   private starting: boolean = false;
 
   constructor(options: LocalNodeOptions = {}) {
+    this.adapter = options.adapter ?? defaultChildProcessAdapter;
     this.options = {
       testDir: options.testDir || join(process.cwd(), ".movehat", "local-node"),
       forceRestart: options.forceRestart ?? false,
@@ -50,7 +63,7 @@ export class LocalNodeManager {
    * @returns LocalNodeInfo with connection details
    */
   async start(): Promise<LocalNodeInfo> {
-    if (this.process) {
+    if (this.spawned) {
       console.log("Local node already running");
       return this.getNodeInfo();
     }
@@ -62,15 +75,17 @@ export class LocalNodeManager {
     this.starting = true;
 
     try {
-      console.log("\n🚀 Starting local Movement node...");
-      console.log(`   Test directory: ${this.options.testDir}`);
-      console.log(`   RPC port: ${this.options.apiPort}`);
-      console.log(`   Faucet port: ${this.options.faucetPort}`);
-      console.log(`   Ready port: ${this.options.readyPort}\n`);
+      logger.newline();
+      logger.step("Starting local Movement node...");
+      logger.plain(`   Test directory: ${this.options.testDir}`);
+      logger.plain(`   RPC port: ${this.options.apiPort}`);
+      logger.plain(`   Faucet port: ${this.options.faucetPort}`);
+      logger.plain(`   Ready port: ${this.options.readyPort}`);
+      logger.newline();
 
       // Clean state if force restart
       if (this.options.forceRestart && existsSync(this.options.testDir)) {
-        console.log("🧹 Cleaning previous node state...");
+        logger.step("Cleaning previous node state...");
         rmSync(this.options.testDir, { recursive: true, force: true });
       }
 
@@ -88,22 +103,24 @@ export class LocalNodeManager {
         args.push("--force-restart");
       }
 
-      // Start the node process
-      this.process = spawn("movement", args, {
+      // Start the node process via the injectable adapter.
+      this.killed = false;
+      this.spawned = this.adapter.spawn({
+        command: "movement",
+        args,
         stdio: this.options.silent ? "ignore" : "pipe",
-        detached: false,
       });
 
       // Handle process output
-      if (!this.options.silent && this.process.stdout && this.process.stderr) {
-        this.process.stdout.on("data", (data) => {
+      if (!this.options.silent && this.spawned.stdout && this.spawned.stderr) {
+        this.spawned.stdout.on("data", (data: Buffer) => {
           const output = data.toString().trim();
           if (output) {
             console.log(`[Node] ${output}`);
           }
         });
 
-        this.process.stderr.on("data", (data) => {
+        this.spawned.stderr.on("data", (data: Buffer) => {
           const output = data.toString().trim();
           if (output && !output.includes("WARN")) {
             console.error(`[Node Error] ${output}`);
@@ -111,24 +128,23 @@ export class LocalNodeManager {
         });
       }
 
-      // Handle process exit
-      this.process.on("exit", (code) => {
-        if (code !== 0 && code !== null) {
-          console.error(`\n❌ Local node exited with code ${code}`);
+      // The adapter's `exited` promise settles on both natural exit and on
+      // spawn-time error (e.g. ENOENT). On error the code is `null` — we don't
+      // log a generic "spawn failed" message here because `waitForReady` will
+      // surface a detailed timeout-with-hints error if movement never starts.
+      void this.spawned.exited.then(({ code }) => {
+        if (code !== null && code !== 0) {
+          logger.error(`Local node exited with code ${code}`);
         }
-        this.process = null;
-      });
-
-      this.process.on("error", (error) => {
-        console.error(`\n❌ Failed to start local node: ${error.message}`);
-        this.process = null;
+        this.spawned = null;
       });
 
       // Wait for node to be ready
-      console.log("⏳ Waiting for node to be ready...");
+      logger.step("Waiting for node to be ready...");
       await this.waitForReady(60000); // 60 second timeout
 
-      console.log("✅ Local Movement node is ready!\n");
+      logger.success("Local Movement node is ready!");
+      logger.newline();
 
       this.starting = false;
       return this.getNodeInfo();
@@ -137,9 +153,10 @@ export class LocalNodeManager {
       this.starting = false;
 
       // Cleanup on failure
-      if (this.process) {
-        this.process.kill();
-        this.process = null;
+      if (this.spawned) {
+        this.killed = true;
+        this.spawned.kill();
+        this.spawned = null;
       }
 
       throw error;
@@ -150,42 +167,47 @@ export class LocalNodeManager {
    * Stop the local node
    */
   async stop(): Promise<void> {
-    if (!this.process) {
+    if (!this.spawned) {
       return;
     }
 
-    console.log("\n🛑 Stopping local Movement node...");
+    logger.newline();
+    logger.step("Stopping local Movement node...");
 
-    return new Promise((resolve) => {
-      if (!this.process) {
-        resolve();
-        return;
-      }
+    const spawned = this.spawned;
 
-      this.process.once("exit", () => {
-        console.log("✅ Local node stopped\n");
-        this.process = null;
-        resolve();
-      });
+    // Mark killed synchronously so isRunning() reflects the intent right away,
+    // mirroring node's ChildProcess.killed semantics.
+    this.killed = true;
 
-      // Send SIGTERM for graceful shutdown
-      this.process.kill("SIGTERM");
+    // Send SIGTERM for graceful shutdown
+    spawned.kill("SIGTERM");
 
-      // Force kill after 5 seconds if still running
-      setTimeout(() => {
-        if (this.process) {
-          console.log("⚠️  Force killing node...");
-          this.process.kill("SIGKILL");
-        }
-      }, 5000);
-    });
+    // Force kill after 5 seconds if still running
+    const forceTimer = setTimeout(() => {
+      if (this.spawned === spawned) {
+        logger.warning("Force killing node...");
+        spawned.kill("SIGKILL");
+      }
+    }, 5000);
+
+    try {
+      await spawned.exited;
+      logger.success("Local node stopped");
+      logger.newline();
+    } finally {
+      clearTimeout(forceTimer);
+      if (this.spawned === spawned) {
+        this.spawned = null;
+      }
+    }
   }
 
   /**
    * Check if the node is running
    */
   isRunning(): boolean {
-    return this.process !== null && !this.process.killed;
+    return this.spawned !== null && !this.killed;
   }
 
   /**
@@ -245,7 +267,7 @@ export class LocalNodeManager {
       ? account
       : account.accountAddress.toString();
 
-    // Use query parameters for Aptos/Movement faucet
+    // Use query parameters for the Movement faucet
     const faucetUrl = `http://127.0.0.1:${this.options.faucetPort}/mint?amount=${amount}&address=${address}`;
 
     try {
@@ -259,11 +281,12 @@ export class LocalNodeManager {
       }
 
       const result = await response.json();
-      console.log(`  ✓ Funded ${address} with ${amount} octas`);
+      logger.success(`Funded ${address} with ${amount} octas`, 2);
 
       return result;
-    } catch (error: any) {
-      throw new Error(`Failed to fund account: ${error.message}`);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to fund account: ${msg}`);
     }
   }
 
@@ -271,13 +294,15 @@ export class LocalNodeManager {
    * Fund multiple accounts in batch
    */
   async fundAccounts(accounts: (Account | string)[], amount: number = 100_000_000): Promise<void> {
-    console.log(`\n💰 Funding ${accounts.length} accounts from local faucet...`);
+    logger.newline();
+    logger.step(`Funding ${accounts.length} accounts from local faucet...`);
 
     for (const account of accounts) {
       await this.fundAccount(account, amount);
     }
 
-    console.log(`✓ All accounts funded successfully\n`);
+    logger.success("All accounts funded successfully");
+    logger.newline();
   }
 
   /**
@@ -289,9 +314,9 @@ export class LocalNodeManager {
     }
 
     if (existsSync(this.options.testDir)) {
-      console.log(`🧹 Cleaning node data at ${this.options.testDir}...`);
+      logger.step(`Cleaning node data at ${this.options.testDir}...`);
       rmSync(this.options.testDir, { recursive: true, force: true });
-      console.log("✓ Node data cleaned");
+      logger.success("Node data cleaned");
     }
   }
 }