movehat 0.2.3 → 0.2.5

package/src/helpers/setup.ts

@@ -1,54 +0,0 @@
-import {
-  Account,
-  Aptos,
-  AptosConfig,
-  Ed25519PrivateKey,
-  Network,
-} from "@aptos-labs/ts-sdk";
-import { loadUserConfig, resolveNetworkConfig } from "../core/config.js";
-import { MovehatConfig } from "../types/config.js";
-import { AccountManager } from "../core/AccountManager.js";
-import { logger } from "../ui/index.js";
-
-export interface TestEnvironment {
-  aptos: Aptos;
-  account: Account;
-  config: MovehatConfig;
-}
-
-export async function setupTestEnvironment(networkName?: string): Promise<TestEnvironment> {
-  // Load and resolve config for selected network
-  const userConfig = await loadUserConfig();
-  const network = networkName || process.env.MH_CLI_NETWORK;
-  const config = await resolveNetworkConfig(userConfig, network);
-
-  // Movement Network uses custom chain IDs, so we need to use Network.CUSTOM
-  // and let the SDK fetch the actual chainId from the node
-  const aptosConfig = new AptosConfig({
-    network: Network.CUSTOM,
-    fullnode: config.rpc,
-  });
-
-  const aptos = new Aptos(aptosConfig);
-
-  // Load account using AccountManager
-  const account = AccountManager.loadAccountFromPrivateKey(config.privateKey);
-
-  logger.success("Test environment ready");
-  logger.plain(`   Account: ${account.accountAddress.toString()}`);
-  logger.plain(`   Network: ${config.network}`);
-  logger.plain(`   RPC: ${config.rpc}`);
-  logger.newline();
-
-  return {
-    aptos,
-    account,
-    config,
-  }
-}
-
-export function createTestAccount(): Account {
-    return AccountManager.createAccount();
-}
-
-

package/src/helpers/setupLocalTesting.ts

@@ -1,387 +0,0 @@
-import { join } from "path";
-import { existsSync } from "fs";
-import { initRuntime } from "../runtime.js";
-import type { MovehatRuntime } from "../types/runtime.js";
-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";
-
-const BUILTIN_FORK_RPCS: Record<string, string> = {
-  testnet: "https://testnet.movementnetwork.xyz/v1",
-  mainnet: "https://mainnet.movementnetwork.xyz/v1",
-};
-
-function resolveForkRpcUrl(
-  network: string,
-  override: string | undefined
-): string {
-  if (override !== undefined) return override;
-  const builtin = BUILTIN_FORK_RPCS[network];
-  if (builtin !== undefined) return builtin;
-  throw new Error(
-    `Cannot fork unknown network "${network}" without a forkRpcUrl. ` +
-      `Either pass forkRpcUrl in LocalTestOptions or use one of: ` +
-      `${Object.keys(BUILTIN_FORK_RPCS).join(", ")}.`
-  );
-}
-
-/**
- * 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 `@internal`.
- */
-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
- *
- * This function provides a complete local testing setup similar to Hardhat:
- *
- * **Local Node Mode** (default, recommended):
- * 1. Starts a full Movement node locally
- * 2. Generates and funds test accounts from local faucet
- * 3. Auto-deploys modules (works because node can process transactions)
- * 4. Returns runtime ready to use
- *
- * **Fork Mode** (faster, read-only):
- * 1. Creates/loads a fork of testnet
- * 2. Starts a fork server
- * 3. Generates and funds accounts (in fork state only)
- * 4. Cannot auto-deploy (fork is read-only)
- * 5. Returns runtime for reading data
- *
- * @param options Configuration options for local testing
- * @returns LocalTestingContext with runtime and a teardown closure
- *
- * @example
- * ```typescript
- * // Local node mode (default) - Full blockchain, can deploy
- * const ctx = await setupLocalTesting({
- *   mode: 'local-node',
- *   accountLabels: ['alice', 'bob'],
- *   autoDeploy: ['counter'],  // works
- * });
- * // ...use ctx.runtime...
- * await ctx.teardown();
- * ```
- */
-export async function setupLocalTesting(
-  options: LocalTestOptions = {}
-): 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"];
-
-  logger.newline();
-  logger.phase("Setting up local testing environment");
-  logger.kv("Mode", mode, 2);
-  logger.kv("Accounts", accountLabels.join(", "), 2);
-  logger.newline();
-
-  if (mode === 'local-node') {
-    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 {
-    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();
-      },
-    };
-  }
-}
-
-/**
- * Setup using local Movement node (full blockchain)
- */
-async function setupWithLocalNode(
-  options: LocalTestOptions,
-  accountLabels: readonly string[],
-  autoFund: boolean,
-  defaultBalance: number
-): Promise<{ runtime: MovehatRuntime; localNode: LocalNodeManager }> {
-  const nodeTestDir = options.nodeTestDir || join(process.cwd(), ".movehat", "local-node");
-  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;
-
-  const localNode = new LocalNodeManager({
-    testDir: nodeTestDir,
-    forceRestart: nodeForceRestart,
-    faucetPort: nodeFaucetPort,
-    apiPort: nodeApiPort,
-    readyPort: nodeReadyPort,
-    silent: nodeSilent,
-  });
-
-  const nodeInfo = await localNode.start();
-
-  // 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();
-
-    if (autoFund) {
-      const accountsList = Object.values(accounts);
-      await localNode.fundAccounts(accountsList, defaultBalance);
-    }
-
-    logger.step("Initializing runtime for local network...");
-
-    const deployerPrivateKey = AccountManager.exportPrivateKeys(["deployer"]).deployer;
-
-    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",
-          },
-        },
-        accounts: [deployerPrivateKey],
-      },
-    });
-
-    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;
-        }
-      }
-
-      logger.newline();
-    }
-
-    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;
-  }
-}
-
-/**
- * Setup using fork server (read-only)
- */
-async function setupWithFork(
-  options: LocalTestOptions,
-  accountLabels: readonly string[],
-  autoFund: boolean,
-  defaultBalance: number
-): 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;
-
-  logger.plain(`   Fork network: ${forkNetwork}`);
-  logger.plain(`   Fork name: ${forkName}`);
-  logger.plain(`   Server port: ${forkPort}`);
-  logger.newline();
-
-  if (options.autoDeploy && options.autoDeploy.length > 0) {
-    logger.warning("Auto-deploy doesn't work in fork mode (read-only).");
-    logger.plain("   Switch to 'local-node' mode for deployment support.");
-    logger.newline();
-  }
-
-  const forkPath = join(process.cwd(), ".movehat", "forks", forkName);
-  const forkManager = new ForkManager(forkPath);
-
-  const forkExists = existsSync(join(forkPath, "metadata.json"));
-
-  if (!forkExists) {
-    logger.step(`Creating fork from ${forkNetwork}...`);
-    const rpcUrl = resolveForkRpcUrl(forkNetwork, options.forkRpcUrl);
-    await forkManager.initialize(rpcUrl, forkNetwork, options.forkApiKey);
-    logger.success(`Fork created at ${forkPath}`);
-    logger.newline();
-  } else {
-    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();
-
-    // Guard against the audit-f1 follow-up case: the default forkName
-    // ("test-local") doesn't encode the network, so a fork created for
-    // testnet would silently serve mainnet requests. Refuse to load
-    // when the saved metadata's network doesn't match what the caller
-    // asked for — the user must either pass a network-specific
-    // `forkName` or delete the stale directory.
-    const savedNetwork = forkManager.getMetadata().network;
-    if (savedNetwork !== forkNetwork) {
-      throw new Error(
-        `Fork at ${forkPath} was created for network "${savedNetwork}" but ` +
-          `you requested "${forkNetwork}". Use a different forkName ` +
-          `(e.g. "${forkNetwork}-local") or delete ${forkPath} to recreate.`
-      );
-    }
-
-    if (forkResetState) {
-      logger.step("Resetting fork state...");
-      await forkManager.resetState();
-    }
-
-    logger.newline();
-  }
-
-  logger.step(`Starting fork server on port ${forkPort}...`);
-  const forkServer = new ForkServer(forkPath, forkPort);
-
-  await forkServer.start();
-  logger.success(`Fork server running at http://localhost:${forkPort}`);
-  logger.newline();
-
-  // 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));
-
-    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();
-
-    if (autoFund) {
-      const addresses = Object.values(accounts).map((acc) =>
-        acc.accountAddress.toString()
-      );
-      await forkManager.fundMultipleAccounts(addresses, defaultBalance);
-    }
-
-    logger.step("Initializing runtime for local network...");
-
-    const deployerPrivateKey = AccountManager.exportPrivateKeys(["deployer"]).deployer;
-
-    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",
-          },
-        },
-        accounts: [deployerPrivateKey],
-      },
-    });
-
-    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;
-  }
-}

package/src/helpers/testFixtures.ts

@@ -1,210 +0,0 @@
-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 } from "./setupLocalTesting.js";
-import { logger } from "../ui/index.js";
-import type { LocalTestOptions } from "../types/config.js";
-
-/**
- * Test fixture with pre-configured accounts and contracts
- *
- * @template TModules - Union type of module names for type-safe contract access
- */
-export interface TestFixture<TModules extends string = string> {
-  /** Movehat runtime instance */
-  mh: MovehatRuntime;
-
-  /** Named accounts (deployer, alice, bob, etc.) */
-  accounts: {
-    deployer: Account;
-    alice: Account;
-    bob: Account;
-    [key: string]: Account;
-  };
-
-  /** 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>;
-}
-
-/**
- * Setup a complete test fixture with local fork, accounts, and deployed contracts
- *
- * This is the recommended way to setup tests in movehat. It provides:
- * - Local fork server (no testnet required)
- * - Pre-funded labeled accounts
- * - Auto-deployment of specified modules
- * - Contract instances ready to use
- *
- * @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, contracts, and a teardown closure
- *
- * @example
- * ```typescript
- * import { setupTestFixture, type TestFixture } from "movehat/helpers";
- *
- * describe("Counter Contract", () => {
- *   let fixture: TestFixture<"counter">;
- *
- *   before(async function () {
- *     this.timeout(60000);
- *     fixture = await setupTestFixture(['counter'] as const, ['alice', 'bob']);
- *   });
- *
- *   after(async () => {
- *     await fixture.teardown();
- *   });
- *
- *   it("alice can increment", async () => {
- *     const tx = await fixture.contracts.counter.call(
- *       fixture.accounts.alice, "increment", []
- *     );
- *     expect(tx.success).to.be.true;
- *   });
- * });
- * ```
- */
-export async function setupTestFixture<TModules extends readonly string[]>(
-  modules: TModules,
-  accountLabels: string[] = ["alice", "bob"],
-  options: Partial<LocalTestOptions> = {}
-): Promise<TestFixture<TModules[number]>> {
-  logger.newline();
-  logger.step("Setting up test fixture...");
-  logger.plain(`   Modules to deploy: ${modules.join(", ")}`);
-  logger.plain(`   Account labels: deployer, ${accountLabels.join(", ")}`);
-  logger.newline();
-
-  const allLabels = ["deployer", ...accountLabels.filter((l) => l !== "deployer")];
-
-  const setupOptions: LocalTestOptions = {
-    ...options,
-    accountLabels: allLabels,
-    autoDeploy: modules,
-  };
-
-  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);
-    }
-
-    const contracts = {} as Record<TModules[number], MoveContract>;
-
-    for (const moduleName of modules) {
-      const deploymentAddress = mh.getDeploymentAddress(moduleName);
-
-      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);
-    }
-
-    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;
-  }
-}
-
-/**
- * Create a minimal test fixture without auto-deployment
- * Useful when you want to deploy contracts manually in tests
- *
- * @param accountLabels Account labels to create (defaults to ['alice', 'bob'])
- * @param options Optional LocalTestOptions
- * @returns Partial TestFixture (without contracts) plus a teardown closure
- */
-export async function setupMinimalFixture(
-  accountLabels: string[] = ["alice", "bob"],
-  options: Partial<LocalTestOptions> = {}
-): Promise<Omit<TestFixture, "contracts">> {
-  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: [],
-  };
-
-  const ctx = await setupLocalTesting(setupOptions);
-
-  // Same teardown-on-assembly-failure pattern as setupTestFixture.
-  try {
-    const mh = ctx.runtime;
-
-    const labeledAccounts = AccountManager.getLabeledAccounts();
-
-    // 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!,
-    };
-
-    for (const label of accountLabels) {
-      accounts[label] = labeledAccounts[label] || AccountManager.getOrCreateLabeled(label);
-    }
-
-    logger.newline();
-    logger.success("Minimal fixture ready!");
-    logger.newline();
-
-    return {
-      mh,
-      accounts,
-      teardown: ctx.teardown,
-    };
-  } catch (error) {
-    await ctx.teardown().catch(() => {});
-    throw error;
-  }
-}