movehat 0.0.1-alpha.0

package/src/fork/test.ts

@@ -0,0 +1,195 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+const execFileAsync = promisify(execFile);
+
+export interface SnapshotOptions {
+  path?: string;
+  name?: string;
+}
+
+export interface ForkInfo {
+  path: string;
+  networkVersion?: number;
+  nodeUrl?: string;
+  exists: boolean;
+}
+
+/**
+ * Create a snapshot (fork) of the current network state
+ * Useful for debugging test failures or inspecting state after tests
+ *
+ * @param options - Snapshot configuration
+ * @returns Path to the created snapshot
+ *
+ * @example
+ * ```typescript
+ * // In your test
+ * after(async () => {
+ *   const snapshotPath = await snapshot({ name: 'after-counter-test' });
+ *   console.log(`Snapshot saved to ${snapshotPath}`);
+ * });
+ * ```
+ */
+export async function snapshot(options: SnapshotOptions = {}): Promise<string> {
+  const name = options.name || `snapshot-${Date.now()}`;
+  const snapshotPath = options.path || join(process.cwd(), '.movehat', 'snapshots', name);
+
+  console.log(`📸 Creating snapshot: ${name}...`);
+
+  try {
+    // Initialize fork/snapshot using aptos CLI
+    // Use execFile with argument array to prevent command injection
+    const { stdout, stderr } = await execFileAsync('aptos', [
+      'move',
+      'sim',
+      'init',
+      '--path',
+      snapshotPath
+    ]);
+
+    if (stderr && !stderr.includes('Success')) {
+      throw new Error(stderr);
+    }
+
+    if (!existsSync(snapshotPath)) {
+      throw new Error('Snapshot directory was not created');
+    }
+
+    console.log(`   ✓ Snapshot created at ${snapshotPath}`);
+    return snapshotPath;
+  } catch (error: any) {
+    throw new Error(`Failed to create snapshot: ${error.message}`);
+  }
+}
+
+/**
+ * Get information about a fork/snapshot
+ *
+ * @param path - Path to the fork directory
+ * @returns Fork information
+ */
+export async function getForkInfo(path: string): Promise<ForkInfo> {
+  const configPath = join(path, 'config.json');
+
+  if (!existsSync(configPath)) {
+    return {
+      path,
+      exists: false
+    };
+  }
+
+  try {
+    const fs = await import('fs/promises');
+    const configContent = await fs.readFile(configPath, 'utf-8');
+    const config = JSON.parse(configContent);
+
+    return {
+      path,
+      exists: true,
+      networkVersion: config.base?.Remote?.network_version,
+      nodeUrl: config.base?.Remote?.node_url
+    };
+  } catch (error) {
+    return {
+      path,
+      exists: false
+    };
+  }
+}
+
+/**
+ * View a resource from a fork/snapshot
+ * Useful for inspecting state without modifying it
+ *
+ * @param sessionPath - Path to the fork session
+ * @param account - Account address
+ * @param resourceType - Full resource type (e.g., '0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>')
+ * @returns Resource data
+ *
+ * @example
+ * ```typescript
+ * const balance = await viewForkResource(
+ *   '.movehat/snapshots/test-snapshot',
+ *   '0x123...',
+ *   '0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>'
+ * );
+ * console.log(`Balance: ${balance.coin.value}`);
+ * ```
+ */
+export async function viewForkResource(
+  sessionPath: string,
+  account: string,
+  resourceType: string
+): Promise<any> {
+  try {
+    // Use execFile with argument array to prevent command injection
+    const { stdout } = await execFileAsync('aptos', [
+      'move',
+      'sim',
+      'view-resource',
+      '--session',
+      sessionPath,
+      '--account',
+      account,
+      '--resource',
+      resourceType
+    ]);
+
+    const result = JSON.parse(stdout);
+
+    if (result.Error) {
+      throw new Error(result.Error);
+    }
+
+    return result.Result;
+  } catch (error: any) {
+    throw new Error(`Failed to view resource: ${error.message}`);
+  }
+}
+
+/**
+ * Compare a resource between current network state and a fork
+ * Useful for verifying state changes after tests
+ *
+ * @param forkPath - Path to the fork
+ * @param account - Account address
+ * @param resourceType - Resource type to compare
+ * @param currentValue - Current value from network (pass from your test)
+ * @returns Comparison result
+ */
+export async function compareForkState(
+  forkPath: string,
+  account: string,
+  resourceType: string,
+  currentValue: any
+): Promise<{ fork: any; current: any; changed: boolean }> {
+  const forkValue = await viewForkResource(forkPath, account, resourceType);
+
+  return {
+    fork: forkValue,
+    current: currentValue,
+    changed: JSON.stringify(forkValue) !== JSON.stringify(currentValue)
+  };
+}
+
+/**
+ * List all snapshots in the project
+ * @returns Array of snapshot paths
+ */
+export async function listSnapshots(): Promise<string[]> {
+  const snapshotsDir = join(process.cwd(), '.movehat', 'snapshots');
+
+  if (!existsSync(snapshotsDir)) {
+    return [];
+  }
+
+  const fs = await import('fs/promises');
+  const entries = await fs.readdir(snapshotsDir, { withFileTypes: true });
+
+  return entries
+    .filter(entry => entry.isDirectory())
+    .map(entry => join(snapshotsDir, entry.name));
+}

package/src/helpers/assertions.ts

@@ -0,0 +1,29 @@
+import { type TransactionResult } from "../core/contract.js";
+
+/**
+ * Assert that a transaction was successful
+ */
+export function assertTransactionSuccess(result: TransactionResult): void {
+  if (!result.success) {
+    throw new Error(
+      `Transaction failed with status: ${result.vm_status}\nHash: ${result.hash}`
+    );
+  }
+}
+
+export function assertTransactionFailed(
+  result: TransactionResult,
+  expectedError?: string
+): void {
+  if (result.success) {
+    throw new Error(
+      `Transaction was expected to fail but succeeded.\nHash: ${result.hash}`
+    );
+  }
+
+  if(expectedError && !result.vm_status.includes(expectedError)) {
+    throw new Error(
+      `Transaction failed with unexpected error.\nExpected to include: ${expectedError}\nActual status: ${result.vm_status}\nHash: ${result.hash}`
+    );
+  }
+}

package/src/helpers/banner.ts

@@ -0,0 +1,47 @@
+type Rgb = [number, number, number];
+
+// Warm yellow-to-amber palette for a subtle gradient.
+const gradientPalette: Rgb[] = [
+  [255, 239, 150],
+  [255, 223, 88],
+  [255, 207, 64],
+  [255, 181, 45],
+  [255, 160, 30],
+];
+
+const bannerLines = [
+  " ███╗   ███╗ ██████╗ ██╗   ██╗███████╗██╗  ██╗ █████╗ ████████╗",
+  " ████╗ ████║██╔═══██╗██║   ██║██╔════╝██║  ██║██╔══██╗╚══██╔══╝",
+  " ██╔████╔██║██║   ██║██║   ██║█████╗  ███████║███████║   ██║   ",
+  " ██║╚██╔╝██║██║   ██║╚██╗ ██╔╝██╔══╝  ██╔══██║██╔══██║   ██║   ",
+  " ██║ ╚═╝ ██║╚██████╔╝ ╚████╔╝ ███████╗██║  ██║██║  ██║   ██║   ",
+  " ╚═╝     ╚═╝ ╚═════╝   ╚═══╝  ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ",
+];
+
+const reset = "\x1b[0m";
+
+const shouldColorize = () => process.env.NO_COLOR === undefined && Boolean(process.stdout.isTTY);
+
+const toAnsi = ([r, g, b]: Rgb) => `\x1b[38;2;${r};${g};${b}m`;
+
+const applyGradient = (line: string, offset: number) => {
+  let painted = "";
+  for (let i = 0; i < line.length; i++) {
+    const color = gradientPalette[(i + offset) % gradientPalette.length];
+    painted += `${toAnsi(color)}${line[i]}`;
+  }
+  return painted;
+};
+
+export const renderMovehatBanner = () => {
+  if (!shouldColorize()) {
+    return bannerLines.join("\n");
+  }
+
+  const coloredLines = bannerLines.map((line, idx) => applyGradient(line, idx * 2));
+  return `${coloredLines.join("\n")}${reset}`;
+};
+
+export const printMovehatBanner = () => {
+  console.log(renderMovehatBanner());
+};

package/src/helpers/index.ts

@@ -0,0 +1,26 @@
+// Re-export all helpers
+export { setupTestEnvironment, createTestAccount } from "./setup.js";
+export type { TestEnvironment } from "./setup.js";
+export { MoveContract, getContract } from "../core/contract.js";
+export type { TransactionResult } from "../core/contract.js";
+export {
+  assertTransactionSuccess,
+  assertTransactionFailed,
+} from "./assertions.js";
+export {
+  saveDeployment,
+  loadDeployment,
+  getAllDeployments,
+  getDeployedAddress,
+} from "../core/deployments.js";
+export type { DeploymentInfo } from "../core/deployments.js";
+export {
+  snapshot,
+  getForkInfo,
+  viewForkResource,
+  compareForkState,
+  listSnapshots,
+} from "../fork/test.js";
+export type { SnapshotOptions, ForkInfo } from "../fork/test.js";
+
+export type { MovehatConfig } from "../types/config.js";

package/src/helpers/setup.ts

@@ -0,0 +1,49 @@
+import {
+  Account,
+  Aptos,
+  AptosConfig,
+  Ed25519PrivateKey,
+  Network,
+} from "@aptos-labs/ts-sdk";
+import { loadUserConfig, resolveNetworkConfig } from "../core/config.js";
+import { MovehatConfig } from "../types/config.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);
+
+  const aptosConfig = new AptosConfig({
+    network: config.network as Network,
+    fullnode: config.rpc,
+  });
+
+  const aptos = new Aptos(aptosConfig);
+
+  const privateKey = new Ed25519PrivateKey(config.privateKey);
+  const account = Account.fromPrivateKey({ privateKey });
+
+  console.log(`✅ Test environment ready`);
+  console.log(`   Account: ${account.accountAddress.toString()}`);
+  console.log(`   Network: ${config.network}`);
+  console.log(`   RPC: ${config.rpc}\n`);
+
+  return {
+    aptos,
+    account,
+    config,
+  }
+}
+
+export function createTestAccount(): Account {
+    return Account.generate();
+}
+
+

package/src/index.ts

@@ -0,0 +1,17 @@
+// Export all helpers for end users
+export * from "./helpers/index.js";
+export type { MovehatConfig } from "./types/config.js";
+
+// Export Movehat Runtime Environment
+export { initRuntime, getRuntime, getMovehat, mh } from "./runtime.js";
+export type { MovehatRuntime, NetworkInfo } from "./types/runtime.js";
+
+// Export Fork system
+export { ForkManager } from "./fork/manager.js";
+export { MovementApiClient } from "./fork/api.js";
+export { ForkStorage } from "./fork/storage.js";
+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";

package/src/runtime.ts

@@ -0,0 +1,322 @@
+import {
+  Account,
+  Aptos,
+  AptosConfig,
+  Ed25519PrivateKey,
+  Network,
+} from "@aptos-labs/ts-sdk";
+import { MovehatRuntime, NetworkInfo } from "./types/runtime.js";
+import { MovehatUserConfig } from "./types/config.js";
+import { loadUserConfig, resolveNetworkConfig } from "./core/config.js";
+import { getContract, MoveContract } from "./core/contract.js";
+import {
+  saveDeployment,
+  loadDeployment,
+  getAllDeployments,
+  getDeployedAddress,
+  DeploymentInfo,
+  validateSafeName,
+} from "./core/deployments.js";
+import { ModuleAlreadyDeployedError } from "./errors.js";
+
+let cachedRuntime: MovehatRuntime | null = null;
+
+export interface InitRuntimeOptions {
+  network?: string;
+  accountIndex?: number;
+  configOverride?: Partial<MovehatUserConfig>;
+}
+
+/**
+ * Initialize the Movehat Runtime Environment
+ * This function loads the configuration and creates the runtime context
+ */
+export async function initRuntime(
+  options: InitRuntimeOptions = {}
+): Promise<MovehatRuntime> {
+  // Load user config from movehat.config.ts
+  const userConfig = await loadUserConfig();
+
+  // Apply config override if provided
+  const mergedUserConfig: MovehatUserConfig = options.configOverride
+    ? { ...userConfig, ...options.configOverride }
+    : userConfig;
+
+  // Resolve configuration for selected network
+  const config = await resolveNetworkConfig(mergedUserConfig, options.network);
+
+  // Setup Aptos client
+  const aptosConfig = new AptosConfig({
+    network: config.network as Network,
+    fullnode: config.rpc,
+  });
+  const aptos = new Aptos(aptosConfig);
+
+  // Setup accounts
+  const accountIndex = options.accountIndex || 0;
+  const accounts: Account[] = config.allAccounts.map((pk) => {
+    const privateKey = new Ed25519PrivateKey(pk);
+    return Account.fromPrivateKey({ privateKey });
+  });
+
+  // Primary account (accounts[0] or selected index)
+  const account = accounts[accountIndex];
+  if (!account) {
+    throw new Error(`Account index ${accountIndex} not found. Only ${accounts.length} accounts configured.`);
+  }
+
+  // Update config.account with derived address
+  config.account = account.accountAddress.toString();
+
+  // Network info
+  const network: NetworkInfo = {
+    name: config.network,
+    rpc: config.rpc,
+  };
+
+  // Helper functions
+  const getContractHelper = (address: string, moduleName: string): MoveContract => {
+    return getContract(aptos, address, moduleName);
+  };
+
+  const deployContract = async (
+    moduleName: string,
+    options?: {
+      packageDir?: string;
+    }
+  ): Promise<DeploymentInfo> => {
+    // Validate moduleName early
+    validateSafeName(moduleName, "module");
+
+    const { exec } = await import("child_process");
+    const { promisify } = await import("util");
+    const { existsSync, mkdirSync, writeFileSync, chmodSync } = await import("fs");
+    const { join } = await import("path");
+    const { homedir } = await import("os");
+    const yaml = await import("js-yaml");
+    const { validateAndEscapePath, validateAndEscapeProfile } = await import("./core/shell.js");
+    const execAsync = promisify(exec);
+
+    // Check if --redeploy flag was passed via CLI
+    const forceRedeploy = process.env.MH_CLI_REDEPLOY === 'true';
+
+    // Check if already deployed
+    const existingDeployment = loadDeployment(config.network, moduleName);
+    if (existingDeployment && !forceRedeploy) {
+      // Build detailed error message with all deployment info
+      const errorDetails = [
+        `Module "${moduleName}" is already deployed on ${config.network}`,
+        `Address: ${existingDeployment.address}`,
+        `Deployed at: ${new Date(existingDeployment.timestamp).toLocaleString()}`,
+        existingDeployment.txHash ? `Transaction: ${existingDeployment.txHash}` : null,
+        `\nTo redeploy, run with the --redeploy flag:`,
+        `movehat run <script> --network ${config.network} --redeploy`,
+      ].filter(Boolean).join('\n');
+
+      // Log formatted error message for user
+      const formattedMessage = [
+        `\n❌ Module "${moduleName}" is already deployed on ${config.network}`,
+        `   Address: ${existingDeployment.address}`,
+        `   Deployed at: ${new Date(existingDeployment.timestamp).toLocaleString()}`,
+        existingDeployment.txHash ? `   Transaction: ${existingDeployment.txHash}` : null,
+        `\n💡 To redeploy, run with the --redeploy flag:`,
+        `   movehat run <script> --network ${config.network} --redeploy\n`,
+      ].filter(Boolean).join('\n');
+
+      console.error(formattedMessage);
+
+      // Throw custom error with complete context for programmatic handling
+      throw new ModuleAlreadyDeployedError(
+        errorDetails,
+        moduleName,
+        config.network,
+        existingDeployment.address,
+        existingDeployment.timestamp,
+        existingDeployment.txHash
+      );
+    }
+
+    if (forceRedeploy && existingDeployment) {
+      console.log(`🔄 Redeploying module "${moduleName}" on ${config.network}...`);
+    }
+
+    const dir = options?.packageDir || config.moveDir;
+    const profile = config.profile || "default";
+
+    // Validate and escape to prevent command injection
+    const safeDir = validateAndEscapePath(dir, "package directory");
+    const safeProfile = validateAndEscapeProfile(profile);
+
+    console.log(`📦 Publishing module "${moduleName}" from ${dir}...`);
+
+    try {
+      // Ensure Movement CLI config exists
+      const aptosConfigDir = join(homedir(), ".aptos");
+      const aptosConfigPath = join(aptosConfigDir, "config.yaml");
+
+      if (!existsSync(aptosConfigPath)) {
+        console.log("⚙️  Creating Movement CLI configuration...");
+        if (!existsSync(aptosConfigDir)) {
+          mkdirSync(aptosConfigDir, { recursive: true });
+        }
+
+        // Create minimal config.yaml using js-yaml to prevent YAML injection
+        const configData = {
+          profiles: {
+            [profile]: {
+              private_key: config.privateKey,
+              public_key: account.publicKey.toString(),
+              account: account.accountAddress.toString(),
+              rest_url: config.rpc,
+            },
+          },
+        };
+        const configContent = yaml.dump(configData);
+        writeFileSync(aptosConfigPath, configContent, "utf-8");
+
+        // Restrict file permissions to owner only (600) for security
+        // This prevents other users from reading the private key
+        try {
+          chmodSync(aptosConfigPath, 0o600);
+        } catch (error) {
+          // chmod may fail on Windows, but that's okay
+          // Windows has different permission model (ACLs)
+          console.warn("⚠️  Could not set file permissions (this is normal on Windows)");
+        }
+      }
+
+      // Build first
+      console.log("🔨 Building package...");
+      const buildCmd = `movement move build --package-dir ${safeDir}`;
+      const { stdout: buildOut } = await execAsync(buildCmd);
+      if (buildOut) console.log(buildOut.trim());
+
+      // Publish
+      console.log("📤 Publishing to blockchain...");
+      const publishCmd = `movement move publish --profile ${safeProfile} --package-dir ${safeDir} --assume-yes`;
+      const { stdout: publishOut } = await execAsync(publishCmd);
+      if (publishOut) console.log(publishOut.trim());
+
+      // Extract transaction hash from output
+      // Look for patterns like "Transaction hash: 0x..." or "Txn: 0x..." or just a 64-char hex
+      // The regex tries to match with context first, then falls back to any 64-char hex
+      let txHash: string | undefined;
+      const txHashMatchWithContext = publishOut.match(/(?:transaction\s*(?:hash)?|txn\s*(?:hash)?|hash):\s*(0x[a-fA-F0-9]{64})\b/i);
+      if (txHashMatchWithContext) {
+        txHash = txHashMatchWithContext[1];
+      } else {
+        // Fallback: try to find any 64-char hex string (exactly, not more)
+        const txHashMatch = publishOut.match(/\b(0x[a-fA-F0-9]{64})\b/);
+        if (txHashMatch) {
+          txHash = txHashMatch[1];
+        }
+      }
+
+      console.log(`✅ Module published successfully!`);
+
+      // Create deployment info
+      const deployment: DeploymentInfo = {
+        address: account.accountAddress.toString(),
+        moduleName,
+        network: config.network,
+        deployer: account.accountAddress.toString(),
+        timestamp: Date.now(),
+        txHash,
+      };
+
+      // Save deployment
+      saveDeployment(deployment);
+
+      return deployment;
+    } catch (error: any) {
+      console.error(`❌ Failed to publish module: ${error.message}`);
+      throw error;
+    }
+  };
+
+  const getDeployment = (moduleName: string): DeploymentInfo | null => {
+    return loadDeployment(config.network, moduleName);
+  };
+
+  const getDeployments = (): Record<string, DeploymentInfo> => {
+    return getAllDeployments(config.network);
+  };
+
+  const getDeploymentAddress = (moduleName: string): string | null => {
+    return getDeployedAddress(config.network, moduleName);
+  };
+
+  const createAccount = (): Account => {
+    return Account.generate();
+  };
+
+  const getAccountHelper = (privateKeyHex: string): Account => {
+    const pk = new Ed25519PrivateKey(privateKeyHex);
+    return Account.fromPrivateKey({ privateKey: pk });
+  };
+
+  const getAccountByIndex = (index: number): Account => {
+    if (index < 0 || index >= accounts.length) {
+      throw new Error(`Account index ${index} out of range. Available accounts: 0-${accounts.length - 1}`);
+    }
+    return accounts[index];
+  };
+
+  const switchNetwork = async (networkName: string): Promise<void> => {
+    // Clear cache and reinitialize with new network
+    cachedRuntime = null;
+    await initRuntime({ ...options, network: networkName });
+  };
+
+  // Build runtime object
+  const runtime: MovehatRuntime = {
+    config,
+    network,
+    aptos,
+    account,
+    accounts,
+    getContract: getContractHelper,
+    deployContract,
+    getDeployment,
+    getDeployments,
+    getDeploymentAddress,
+    createAccount,
+    getAccount: getAccountHelper,
+    getAccountByIndex,
+    switchNetwork,
+  };
+
+  cachedRuntime = runtime;
+  return runtime;
+}
+
+/**
+ * Get the current Movehat Runtime Environment
+ * Throws error if runtime hasn't been initialized
+ */
+export function getRuntime(): MovehatRuntime {
+  if (!cachedRuntime) {
+    throw new Error(
+      "Movehat Runtime not initialized. Call initRuntime() first or use getMovehat()."
+    );
+  }
+  return cachedRuntime;
+}
+
+/**
+ * Get or initialize the Movehat Runtime Environment
+ * This is a convenience function that initializes if needed
+ */
+export async function getMovehat(): Promise<MovehatRuntime> {
+  if (cachedRuntime) {
+    return cachedRuntime;
+  }
+  return initRuntime();
+}
+
+// Export a default instance getter for convenience
+export const mh = {
+  get runtime() {
+    return getRuntime();
+  },
+};

package/src/templates/.env.example

@@ -0,0 +1,9 @@
+# Private Key (used for all networks - Hardhat-style)
+# This is your wallet's private key that will be used to deploy and interact with contracts
+PRIVATE_KEY=your_private_key_here
+
+# Optional: Override RPC URL (useful for custom endpoints)
+# MOVEMENT_RPC_URL=https://custom-testnet.movementnetwork.xyz/v1
+
+# Optional: Override default network from config
+# MH_DEFAULT_NETWORK=testnet