movehat 0.0.1-alpha.0

package/src/core/deployments.ts

@@ -0,0 +1,164 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { join } from "path";
+
+export interface DeploymentInfo {
+  address: string;
+  moduleName: string;
+  network: string;
+  deployer: string;
+  timestamp: number;
+  txHash?: string;
+  blockNumber?: string;
+}
+
+/**
+ * Validates that a name is safe for use in file paths
+ * Only allows alphanumeric characters, hyphens, and underscores
+ * Prevents path traversal attacks
+ */
+export function validateSafeName(name: string, type: "network" | "module"): void {
+  if (!name || typeof name !== "string") {
+    throw new Error(`Invalid ${type} name: must be a non-empty string`);
+  }
+
+  // Check for path traversal sequences
+  if (name.includes("..") || name.includes("/") || name.includes("\\")) {
+    throw new Error(
+      `Invalid ${type} name: "${name}"\n` +
+      `Path traversal sequences are not allowed.\n` +
+      `Use only alphanumeric characters, hyphens, and underscores.`
+    );
+  }
+
+  // Only allow alphanumeric, hyphens, underscores
+  const safePattern = /^[a-zA-Z0-9_-]+$/;
+  if (!safePattern.test(name)) {
+    throw new Error(
+      `Invalid ${type} name: "${name}"\n` +
+      `Only alphanumeric characters, hyphens (-), and underscores (_) are allowed.`
+    );
+  }
+
+  // Additional check: prevent starting with dot (hidden files)
+  if (name.startsWith(".")) {
+    throw new Error(
+      `Invalid ${type} name: "${name}"\n` +
+      `Names cannot start with a dot (.) to prevent hidden file creation.`
+    );
+  }
+}
+
+/**
+ * Get the deployments directory path
+ */
+function getDeploymentsDir(): string {
+  return join(process.cwd(), "deployments");
+}
+
+/**
+ * Get the network-specific deployments directory
+ */
+function getNetworkDeploymentsDir(network: string): string {
+  // Validate network name to prevent path traversal
+  validateSafeName(network, "network");
+
+  const deploymentsDir = getDeploymentsDir();
+  const networkDir = join(deploymentsDir, network);
+
+  // Create directories if they don't exist
+  if (!existsSync(deploymentsDir)) {
+    mkdirSync(deploymentsDir, { recursive: true });
+  }
+  if (!existsSync(networkDir)) {
+    mkdirSync(networkDir, { recursive: true });
+  }
+
+  return networkDir;
+}
+
+/**
+ * Save a deployment
+ */
+export function saveDeployment(deployment: DeploymentInfo): void {
+  // Validate both network and module name
+  validateSafeName(deployment.network, "network");
+  validateSafeName(deployment.moduleName, "module");
+
+  const networkDir = getNetworkDeploymentsDir(deployment.network);
+  const filePath = join(networkDir, `${deployment.moduleName}.json`);
+
+  try {
+    writeFileSync(filePath, JSON.stringify(deployment, null, 2), "utf-8");
+    console.log(
+      `💾 Deployment saved: deployments/${deployment.network}/${deployment.moduleName}.json`
+    );
+  } catch (error) {
+    console.error(
+      `Failed to save deployment for ${deployment.moduleName} on ${deployment.network} at ${filePath}:`,
+      error
+    );
+    throw error;
+  }
+}
+
+/**
+ * Load a deployment
+ */
+export function loadDeployment(network: string, moduleName: string): DeploymentInfo | null {
+  // Validate both network and module name
+  validateSafeName(network, "network");
+  validateSafeName(moduleName, "module");
+
+  const networkDir = getNetworkDeploymentsDir(network);
+  const filePath = join(networkDir, `${moduleName}.json`);
+
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    return JSON.parse(content) as DeploymentInfo;
+  } catch (error) {
+    console.error(`Failed to load deployment for ${moduleName} on ${network}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Get all deployments for a network
+ */
+export function getAllDeployments(network: string): Record<string, DeploymentInfo> {
+  // Validate network name
+  validateSafeName(network, "network");
+
+  const networkDir = getNetworkDeploymentsDir(network);
+
+  if (!existsSync(networkDir)) {
+    return {};
+  }
+
+  const files = readdirSync(networkDir).filter((f: string) => f.endsWith(".json"));
+
+  const deployments: Record<string, DeploymentInfo> = {};
+
+  for (const file of files) {
+    const moduleName = file.replace(".json", "");
+    // loadDeployment will validate moduleName internally
+    const deployment = loadDeployment(network, moduleName);
+    if (deployment) {
+      deployments[moduleName] = deployment;
+    }
+  }
+
+  return deployments;
+}
+
+/**
+ * Get deployed address for a module
+ */
+export function getDeployedAddress(network: string, moduleName: string): string | null {
+  // Validation happens in loadDeployment
+  const deployment = loadDeployment(network, moduleName);
+  return deployment ? deployment.address : null;
+}

package/src/core/shell.ts

@@ -0,0 +1,66 @@
+/**
+ * Escapes a shell argument to prevent command injection
+ * Wraps the argument in single quotes and escapes any single quotes within
+ *
+ * @param arg - The argument to escape
+ * @returns The escaped argument safe for shell execution
+ */
+export function escapeShellArg(arg: string): string {
+  if (typeof arg !== "string") {
+    throw new Error("Shell argument must be a string");
+  }
+
+  // Wrap in single quotes and escape any single quotes by replacing them with '\''
+  // This technique works on both Unix and Windows (Git Bash, WSL)
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Validates that a path is safe (no command injection characters)
+ * and returns the escaped version
+ *
+ * @param path - The path to validate and escape
+ * @param name - Name for error messages (e.g., "package directory")
+ * @returns The escaped path safe for shell execution
+ */
+export function validateAndEscapePath(path: string, name: string = "path"): string {
+  if (!path || typeof path !== "string") {
+    throw new Error(`Invalid ${name}: must be a non-empty string`);
+  }
+
+  // Check for obvious command injection attempts
+  const dangerousChars = /[;&|`$(){}[\]<>]/;
+  if (dangerousChars.test(path)) {
+    throw new Error(
+      `Invalid ${name}: "${path}"\n` +
+      `Path contains potentially dangerous characters.\n` +
+      `Allowed characters: letters, numbers, ., -, _, /, \\, spaces`
+    );
+  }
+
+  // Escape for shell safety
+  return escapeShellArg(path);
+}
+
+/**
+ * Validates that a profile name is safe
+ *
+ * @param profile - The profile name to validate
+ * @returns The escaped profile name
+ */
+export function validateAndEscapeProfile(profile: string): string {
+  if (!profile || typeof profile !== "string") {
+    throw new Error("Invalid profile name: must be a non-empty string");
+  }
+
+  // Profile names should only contain alphanumeric, hyphens, underscores
+  const safePattern = /^[a-zA-Z0-9_-]+$/;
+  if (!safePattern.test(profile)) {
+    throw new Error(
+      `Invalid profile name: "${profile}"\n` +
+      `Only alphanumeric characters, hyphens (-), and underscores (_) are allowed.`
+    );
+  }
+
+  return escapeShellArg(profile);
+}

package/src/errors.ts

@@ -0,0 +1,21 @@
+/**
+ * Custom error thrown when attempting to deploy a module that is already deployed
+ */
+export class ModuleAlreadyDeployedError extends Error {
+  constructor(
+    message: string,
+    public readonly moduleName: string,
+    public readonly network: string,
+    public readonly address: string,
+    public readonly timestamp: number,
+    public readonly txHash?: string
+  ) {
+    super(message);
+    this.name = 'ModuleAlreadyDeployedError';
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ModuleAlreadyDeployedError);
+    }
+  }
+}

package/src/fork/api.ts

@@ -0,0 +1,117 @@
+import https from 'https';
+import http from 'http';
+import { URL } from 'url';
+import type { LedgerInfo, AccountData, AccountResource } from '../types/fork.js';
+
+/**
+ * Client for interacting with Movement/Aptos-compatible JSON API
+ */
+export class MovementApiClient {
+  private nodeUrl: string;
+
+  constructor(nodeUrl: string) {
+    // Remove trailing slash
+    let normalized = nodeUrl.replace(/\/$/, '');
+
+    // If URL already ends with /v1, use as is
+    // Otherwise, assume it's the base URL
+    if (!normalized.endsWith('/v1')) {
+      // Base URL without /v1, we'll add it in requests
+    }
+
+    this.nodeUrl = normalized;
+  }
+
+  /**
+   * Make a GET request to the API
+   */
+  private async get<T>(path: string): Promise<T> {
+    const fullUrl = `${this.nodeUrl}${path}`;
+    const parsedUrl = new URL(fullUrl);
+    const isHttps = parsedUrl.protocol === 'https:';
+    const client = isHttps ? https : http;
+
+    return new Promise((resolve, reject) => {
+      const req = client.get(fullUrl, (res) => {
+        let data = '';
+
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`API request failed with status ${res.statusCode}: ${data}`));
+            return;
+          }
+
+          try {
+            const parsed = JSON.parse(data);
+            resolve(parsed);
+          } catch (err) {
+            reject(new Error(`Failed to parse JSON response: ${err}`));
+          }
+        });
+      });
+
+      req.on('error', (err) => {
+        reject(new Error(`API request failed: ${err.message}`));
+      });
+
+      req.end();
+    });
+  }
+
+  /**
+   * Build API path with proper prefix
+   */
+  private apiPath(suffix: string): string {
+    // If nodeUrl already ends with /v1, just add the suffix
+    // Otherwise add /v1 prefix
+    return this.nodeUrl.endsWith('/v1') ? suffix : `/v1${suffix}`;
+  }
+
+  /**
+   * Get ledger information
+   */
+  async getLedgerInfo(): Promise<LedgerInfo> {
+    return this.get<LedgerInfo>(this.apiPath('/'));
+  }
+
+  /**
+   * Get account information
+   */
+  async getAccount(address: string): Promise<AccountData> {
+    // Normalize address (ensure 0x prefix and lowercase)
+    const normalizedAddress = address.toLowerCase().startsWith('0x')
+      ? address.toLowerCase()
+      : `0x${address.toLowerCase()}`;
+
+    return this.get<AccountData>(this.apiPath(`/accounts/${normalizedAddress}`));
+  }
+
+  /**
+   * Get a specific account resource
+   */
+  async getAccountResource(address: string, resourceType: string): Promise<any> {
+    const normalizedAddress = address.toLowerCase().startsWith('0x')
+      ? address.toLowerCase()
+      : `0x${address.toLowerCase()}`;
+
+    // URL encode the resource type
+    const encodedType = encodeURIComponent(resourceType);
+
+    return this.get<any>(this.apiPath(`/accounts/${normalizedAddress}/resource/${encodedType}`));
+  }
+
+  /**
+   * Get all resources for an account
+   */
+  async getAccountResources(address: string): Promise<AccountResource[]> {
+    const normalizedAddress = address.toLowerCase().startsWith('0x')
+      ? address.toLowerCase()
+      : `0x${address.toLowerCase()}`;
+
+    return this.get<AccountResource[]>(this.apiPath(`/accounts/${normalizedAddress}/resources`));
+  }
+}

package/src/fork/manager.ts

@@ -0,0 +1,264 @@
+import { MovementApiClient } from './api.js';
+import { ForkStorage } from './storage.js';
+import type { ForkMetadata, AccountState } from '../types/fork.js';
+
+/**
+ * Manager for fork operations
+ * Orchestrates API client and storage
+ */
+export class ForkManager {
+  private storage: ForkStorage;
+  private apiClient: MovementApiClient | null = null;
+  private metadata: ForkMetadata | null = null;
+
+  constructor(forkPath: string) {
+    this.storage = new ForkStorage(forkPath);
+  }
+
+  /**
+   * Initialize a new fork from a network
+   */
+  async initialize(nodeUrl: string, networkName: string = 'custom'): Promise<void> {
+    // Create API client
+    this.apiClient = new MovementApiClient(nodeUrl);
+
+    // Fetch network info
+    const ledgerInfo = await this.apiClient.getLedgerInfo();
+
+    // Create fork structure
+    this.storage.initialize();
+
+    // Save metadata
+    this.metadata = {
+      network: networkName,
+      nodeUrl,
+      chainId: ledgerInfo.chain_id,
+      ledgerVersion: ledgerInfo.ledger_version,
+      timestamp: ledgerInfo.ledger_timestamp,
+      epoch: ledgerInfo.epoch,
+      blockHeight: ledgerInfo.block_height,
+      createdAt: new Date().toISOString(),
+    };
+
+    this.storage.saveMetadata(this.metadata);
+
+    console.log(`✓ Fork initialized at ledger version ${ledgerInfo.ledger_version}`);
+  }
+
+  /**
+   * Load an existing fork
+   */
+  load(): void {
+    if (!this.storage.exists()) {
+      throw new Error('Fork does not exist. Run `initialize()` first.');
+    }
+
+    this.metadata = this.storage.loadMetadata();
+    this.apiClient = new MovementApiClient(this.metadata.nodeUrl);
+  }
+
+  /**
+   * Get fork metadata
+   */
+  getMetadata(): ForkMetadata {
+    if (!this.metadata) {
+      this.metadata = this.storage.loadMetadata();
+    }
+    return this.metadata;
+  }
+
+  /**
+   * Get account state (with lazy loading)
+   */
+  async getAccount(address: string): Promise<AccountState> {
+    // Normalize address
+    const normalizedAddress = this.normalizeAddress(address);
+
+    // Check cache first
+    let accountState = this.storage.getAccount(normalizedAddress);
+
+    if (!accountState) {
+      // Fetch from network
+      if (!this.apiClient) {
+        throw new Error('Fork not initialized. Call initialize() or load() first.');
+      }
+
+      console.log(`  Fetching account ${normalizedAddress} from network...`);
+      const accountData = await this.apiClient.getAccount(normalizedAddress);
+
+      accountState = {
+        sequenceNumber: accountData.sequence_number,
+        authenticationKey: accountData.authentication_key,
+      };
+
+      // Cache it
+      this.storage.saveAccount(normalizedAddress, accountState);
+      console.log(`  ✓ Cached account ${normalizedAddress}`);
+    }
+
+    return accountState;
+  }
+
+  /**
+   * Get a specific resource (with lazy loading)
+   */
+  async getResource(address: string, resourceType: string): Promise<any> {
+    const normalizedAddress = this.normalizeAddress(address);
+
+    // Check cache first
+    let resource = this.storage.getResource(normalizedAddress, resourceType);
+
+    if (!resource) {
+      // Fetch from network
+      if (!this.apiClient) {
+        throw new Error('Fork not initialized. Call initialize() or load() first.');
+      }
+
+      console.log(`  Fetching resource ${resourceType} for ${normalizedAddress}...`);
+
+      try {
+        const resourceData = await this.apiClient.getAccountResource(normalizedAddress, resourceType);
+        resource = resourceData.data;
+
+        // Cache it
+        this.storage.saveResource(normalizedAddress, resourceType, resource);
+        console.log(`  ✓ Cached resource ${resourceType}`);
+      } catch (error: any) {
+        if (error.message.includes('404')) {
+          throw new Error(`Resource ${resourceType} not found for account ${normalizedAddress}`);
+        }
+        throw error;
+      }
+    }
+
+    return resource;
+  }
+
+  /**
+   * Get all resources for an account (with lazy loading)
+   */
+  async getAllResources(address: string): Promise<Record<string, any>> {
+    const normalizedAddress = this.normalizeAddress(address);
+
+    // Check if we have any cached resources
+    let resources = this.storage.getAllResources(normalizedAddress);
+
+    // If no cached resources, fetch all from network
+    if (Object.keys(resources).length === 0) {
+      if (!this.apiClient) {
+        throw new Error('Fork not initialized. Call initialize() or load() first.');
+      }
+
+      console.log(`  Fetching all resources for ${normalizedAddress}...`);
+      const resourcesList = await this.apiClient.getAccountResources(normalizedAddress);
+
+      resources = {};
+      for (const resource of resourcesList) {
+        resources[resource.type] = resource.data;
+      }
+
+      // Cache them
+      this.storage.saveAllResources(normalizedAddress, resources);
+      console.log(`  ✓ Cached ${Object.keys(resources).length} resources`);
+    }
+
+    return resources;
+  }
+
+  /**
+   * Set a resource value (for testing/mocking)
+   */
+  async setResource(address: string, resourceType: string, data: any): Promise<void> {
+    const normalizedAddress = this.normalizeAddress(address);
+    this.storage.saveResource(normalizedAddress, resourceType, data);
+    console.log(`  ✓ Updated resource ${resourceType} for ${normalizedAddress}`);
+  }
+
+  /**
+   * Fund an account with coins (adds to existing balance)
+   */
+  async fundAccount(address: string, amount: number, coinType: string = '0x1::aptos_coin::AptosCoin'): Promise<void> {
+    const normalizedAddress = this.normalizeAddress(address);
+    const resourceType = `0x1::coin::CoinStore<${coinType}>`;
+
+    // Try to get existing coin store
+    let coinStore: any;
+    try {
+      coinStore = await this.getResource(normalizedAddress, resourceType);
+    } catch (error: any) {
+      // Only catch "not found" errors, rethrow others (network, API, etc.)
+      if (!error.message || !error.message.includes('not found')) {
+        throw error;
+      }
+
+      // If doesn't exist, create new one
+      coinStore = {
+        coin: { value: '0' },
+        deposit_events: {
+          counter: '0',
+          guid: {
+            id: {
+              addr: normalizedAddress,
+              creation_num: '0',
+            },
+          },
+        },
+        withdraw_events: {
+          counter: '0',
+          guid: {
+            id: {
+              addr: normalizedAddress,
+              creation_num: '1',
+            },
+          },
+        },
+        frozen: false,
+      };
+    }
+
+    // Add to existing balance (instead of replacing it)
+    const currentBalance = BigInt(coinStore.coin.value ?? '0');
+    const newBalance = currentBalance + BigInt(amount);
+    coinStore.coin.value = newBalance.toString();
+
+    // Save
+    await this.setResource(normalizedAddress, resourceType, coinStore);
+
+    // Also ensure account exists
+    let account = this.storage.getAccount(normalizedAddress);
+    if (!account) {
+      account = {
+        sequenceNumber: '0',
+        authenticationKey: normalizedAddress.padEnd(66, '0'),
+      };
+      this.storage.saveAccount(normalizedAddress, account);
+    }
+
+    console.log(`  ✓ Funded ${normalizedAddress} with ${amount} coins`);
+  }
+
+  /**
+   * Normalize address format
+   */
+  private normalizeAddress(address: string): string {
+    let normalized = address.toLowerCase();
+
+    if (!normalized.startsWith('0x')) {
+      normalized = `0x${normalized}`;
+    }
+
+    // Pad to 66 characters (0x + 64 hex chars)
+    if (normalized.length < 66) {
+      normalized = '0x' + normalized.slice(2).padStart(64, '0');
+    }
+
+    return normalized;
+  }
+
+  /**
+   * List all accounts in the fork
+   */
+  listAccounts(): string[] {
+    return this.storage.listAccounts();
+  }
+}