movehat 0.1.8 → 0.2.0

package/src/fork/__tests__/storage.test.ts

@@ -0,0 +1,281 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { vol } from 'memfs';
+import { ForkStorage } from '../storage.js';
+
+// Mock fs module
+vi.mock('fs', async () => {
+  const memfs = await import('memfs');
+  return memfs.fs;
+});
+
+describe('ForkStorage', () => {
+  const forkPath = '/test-fork';
+
+  beforeEach(() => {
+    vol.reset();
+  });
+
+  afterEach(() => {
+    vol.reset();
+  });
+
+  describe('initialize', () => {
+    it('should create fork directory structure', () => {
+      const storage = new ForkStorage(forkPath);
+      storage.initialize();
+
+      expect(vol.existsSync(forkPath)).toBe(true);
+      expect(vol.existsSync(`${forkPath}/resources`)).toBe(true);
+      expect(vol.existsSync(`${forkPath}/cache`)).toBe(true);
+      expect(vol.existsSync(`${forkPath}/cache/.gitignore`)).toBe(true);
+      expect(vol.existsSync(`${forkPath}/accounts.json`)).toBe(true);
+    });
+
+    it('should not overwrite existing files', () => {
+      vol.fromJSON({
+        [`${forkPath}/accounts.json`]: '{"existing": "data"}',
+      });
+
+      const storage = new ForkStorage(forkPath);
+      storage.initialize();
+
+      const content = vol.readFileSync(`${forkPath}/accounts.json`, 'utf-8');
+      expect(content).toBe('{"existing": "data"}');
+    });
+  });
+
+  describe('exists', () => {
+    it('should return false if fork does not exist', () => {
+      const storage = new ForkStorage(forkPath);
+      expect(storage.exists()).toBe(false);
+    });
+
+    it('should return false if metadata.json is missing', () => {
+      vol.fromJSON({
+        [`${forkPath}/accounts.json`]: '{}',
+      });
+
+      const storage = new ForkStorage(forkPath);
+      expect(storage.exists()).toBe(false);
+    });
+
+    it('should return true if fork exists with metadata', () => {
+      vol.fromJSON({
+        [`${forkPath}/metadata.json`]: '{}',
+      });
+
+      const storage = new ForkStorage(forkPath);
+      expect(storage.exists()).toBe(true);
+    });
+  });
+
+  describe('metadata', () => {
+    it('should save and load metadata', () => {
+      vol.mkdirSync(forkPath, { recursive: true });
+
+      const storage = new ForkStorage(forkPath);
+      const metadata = {
+        network: 'testnet',
+        nodeUrl: 'https://testnet.example.com/v1',
+        chainId: 250,
+        ledgerVersion: '12345',
+        timestamp: '1234567890',
+        epoch: '100',
+        blockHeight: '1000',
+        createdAt: '2024-01-01T00:00:00.000Z',
+      };
+
+      storage.saveMetadata(metadata);
+      const loaded = storage.loadMetadata();
+
+      expect(loaded).toEqual(metadata);
+    });
+
+    it('should throw error if metadata does not exist', () => {
+      const storage = new ForkStorage(forkPath);
+      expect(() => storage.loadMetadata()).toThrow('Fork metadata not found');
+    });
+  });
+
+  describe('accounts', () => {
+    it('should save and get account state', () => {
+      vol.fromJSON({
+        [`${forkPath}/accounts.json`]: '{}',
+      });
+
+      const storage = new ForkStorage(forkPath);
+      const accountState = {
+        sequenceNumber: '10',
+        authenticationKey: '0xabc123',
+      };
+
+      storage.saveAccount('0x123', accountState);
+      const loaded = storage.getAccount('0x123');
+
+      expect(loaded).toEqual(accountState);
+    });
+
+    it('should return null for non-existent account', () => {
+      vol.fromJSON({
+        [`${forkPath}/accounts.json`]: '{}',
+      });
+
+      const storage = new ForkStorage(forkPath);
+      const result = storage.getAccount('0xnonexistent');
+
+      expect(result).toBeNull();
+    });
+
+    it('should list all accounts', () => {
+      vol.fromJSON({
+        [`${forkPath}/accounts.json`]: JSON.stringify({
+          '0x1': { sequenceNumber: '0' },
+          '0x2': { sequenceNumber: '5' },
+          '0x3': { sequenceNumber: '10' },
+        }),
+      });
+
+      const storage = new ForkStorage(forkPath);
+      const accounts = storage.listAccounts();
+
+      expect(accounts).toHaveLength(3);
+      expect(accounts).toContain('0x1');
+      expect(accounts).toContain('0x2');
+      expect(accounts).toContain('0x3');
+    });
+
+    it('should clear all accounts', () => {
+      vol.fromJSON({
+        [`${forkPath}/accounts.json`]: JSON.stringify({
+          '0x1': { sequenceNumber: '0' },
+        }),
+      });
+
+      const storage = new ForkStorage(forkPath);
+      storage.clearAccounts();
+
+      const accounts = storage.listAccounts();
+      expect(accounts).toHaveLength(0);
+    });
+  });
+
+  describe('resources', () => {
+    beforeEach(() => {
+      vol.fromJSON({
+        [`${forkPath}/resources/.gitkeep`]: '',
+      });
+    });
+
+    it('should save and get resource', () => {
+      const storage = new ForkStorage(forkPath);
+      const resource = { value: '100' };
+
+      storage.saveResource('0x1', '0x1::coin::CoinStore', resource);
+      const loaded = storage.getResource('0x1', '0x1::coin::CoinStore');
+
+      expect(loaded).toEqual(resource);
+    });
+
+    it('should return null for non-existent resource', () => {
+      const storage = new ForkStorage(forkPath);
+      const result = storage.getResource('0x1', '0x1::nonexistent::Resource');
+
+      expect(result).toBeNull();
+    });
+
+    it('should get all resources for an account', () => {
+      vol.fromJSON({
+        [`${forkPath}/resources/0x1.json`]: JSON.stringify({
+          '0x1::coin::CoinStore': { value: '100' },
+          '0x1::account::Account': { sequence: '5' },
+        }),
+      });
+
+      const storage = new ForkStorage(forkPath);
+      const resources = storage.getAllResources('0x1');
+
+      expect(Object.keys(resources)).toHaveLength(2);
+      expect(resources['0x1::coin::CoinStore']).toEqual({ value: '100' });
+    });
+
+    it('should check if resource exists', () => {
+      vol.fromJSON({
+        [`${forkPath}/resources/0x1.json`]: JSON.stringify({
+          '0x1::coin::CoinStore': { value: '100' },
+        }),
+      });
+
+      const storage = new ForkStorage(forkPath);
+
+      expect(storage.hasResource('0x1', '0x1::coin::CoinStore')).toBe(true);
+      expect(storage.hasResource('0x1', '0x1::nonexistent::Resource')).toBe(false);
+    });
+
+    it('should clear all resources', () => {
+      vol.fromJSON({
+        [`${forkPath}/resources/0x1.json`]: '{}',
+        [`${forkPath}/resources/0x2.json`]: '{}',
+      });
+
+      const storage = new ForkStorage(forkPath);
+      storage.clearResources();
+
+      expect(vol.existsSync(`${forkPath}/resources/0x1.json`)).toBe(false);
+      expect(vol.existsSync(`${forkPath}/resources/0x2.json`)).toBe(false);
+    });
+  });
+
+  describe('address sanitization', () => {
+    beforeEach(() => {
+      vol.fromJSON({
+        [`${forkPath}/resources/.gitkeep`]: '',
+      });
+    });
+
+    it('should handle addresses with 0x prefix', () => {
+      const storage = new ForkStorage(forkPath);
+      storage.saveResource('0xabc123', 'test::Resource', { value: 1 });
+
+      expect(vol.existsSync(`${forkPath}/resources/0xabc123.json`)).toBe(true);
+    });
+
+    it('should normalize address to lowercase', () => {
+      const storage = new ForkStorage(forkPath);
+      storage.saveResource('0xABC123', 'test::Resource', { value: 1 });
+
+      expect(vol.existsSync(`${forkPath}/resources/0xabc123.json`)).toBe(true);
+    });
+
+    it('should reject invalid address formats', () => {
+      const storage = new ForkStorage(forkPath);
+
+      expect(() => {
+        storage.saveResource('../../../etc/passwd', 'test::Resource', { value: 1 });
+      }).toThrow('Invalid address format');
+
+      expect(() => {
+        storage.saveResource('0x123/../../etc', 'test::Resource', { value: 1 });
+      }).toThrow('Invalid address format');
+    });
+
+    it('should reject addresses with more than 64 hex chars (Movement cap)', () => {
+      const storage = new ForkStorage(forkPath);
+      const sixtyFiveHex = '0x' + 'a'.repeat(65);
+
+      expect(() => {
+        storage.saveResource(sixtyFiveHex, 'test::Resource', { value: 1 });
+      }).toThrow('Invalid address format');
+    });
+
+    it('should accept addresses exactly at the 64 hex char limit', () => {
+      const storage = new ForkStorage(forkPath);
+      const sixtyFourHex = '0x' + 'a'.repeat(64);
+
+      expect(() => {
+        storage.saveResource(sixtyFourHex, 'test::Resource', { value: 1 });
+      }).not.toThrow();
+
+      expect(vol.existsSync(`${forkPath}/resources/${sixtyFourHex}.json`)).toBe(true);
+    });
+  });
+});

package/src/fork/__tests__/test.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { snapshot, viewForkResource } from '../test.js';
+import type { ChildProcessAdapter, RunResult } from '../../utils/childProcessAdapter.js';
+
+/**
+ * Guards the exitCode-failure path that CodeRabbit flagged on PR #100:
+ * before this hardening, an `aptos` command that exited non-zero with a
+ * stderr containing the word "Success" (or no stderr at all) could slip
+ * past the stderr-defense check in `snapshot`, and a non-JSON stderr from
+ * `view-resource` produced a cryptic JSON parse error instead of the
+ * actual aptos failure.
+ */
+describe('fork/test — exitCode failure paths', () => {
+  let tmpCwd: string;
+  let origCwd: string;
+
+  beforeEach(() => {
+    tmpCwd = mkdtempSync(join(tmpdir(), 'movehat-fork-test-'));
+    origCwd = process.cwd();
+    process.chdir(tmpCwd);
+  });
+
+  afterEach(() => {
+    try {
+      process.chdir(origCwd);
+    } finally {
+      rmSync(tmpCwd, { recursive: true, force: true });
+    }
+  });
+
+  function adapterReturning(result: RunResult): ChildProcessAdapter {
+    return {
+      async run() {
+        return result;
+      },
+      spawn() {
+        throw new Error('spawn not used in fork/test failure-path tests');
+      },
+    };
+  }
+
+  it("snapshot throws on non-zero exit even when stderr contains 'Success'", async () => {
+    // The pre-fix edge case: aptos exits 1, stderr says
+    // "Failed: Success criteria not met" → the stderr.includes('Success')
+    // gate returned false-positive ok, and a stale directory from a prior
+    // run would mask the failure entirely.
+    const adapter = adapterReturning({
+      exitCode: 1,
+      stdout: '',
+      stderr: 'Failed: Success criteria not met for snapshot init',
+    });
+
+    await expect(snapshot({ name: 'edge', adapter })).rejects.toThrow(
+      /Success criteria not met/
+    );
+  });
+
+  it('snapshot still throws when a stale directory from a prior run exists (the full edge case)', async () => {
+    // The pre-fix combined edge case: aptos exits non-zero, stderr happens
+    // to contain "Success" (so the stderr.includes('Success') gate would
+    // false-positive), AND the snapshot directory already exists from a
+    // previous successful run (so the existsSync check would false-positive
+    // too). The new exitCode check fires first and throws regardless.
+    const stalePath = join(tmpCwd, '.movehat', 'snapshots', 'stale');
+    mkdirSync(stalePath, { recursive: true });
+    writeFileSync(join(stalePath, 'config.json'), '{}');
+
+    const adapter = adapterReturning({
+      exitCode: 1,
+      stdout: '',
+      stderr: 'Failed but Success was nearby',
+    });
+
+    await expect(
+      snapshot({ name: 'stale', path: stalePath, adapter })
+    ).rejects.toThrow(/Failed but Success was nearby/);
+  });
+
+  it('viewForkResource throws on non-zero exit with non-JSON stderr (informative message)', async () => {
+    // Pre-fix the failure surfaced as "Unexpected token ..." from
+    // JSON.parse, which obscured the actual aptos error.
+    const adapter = adapterReturning({
+      exitCode: 1,
+      stdout: '',
+      stderr: 'Error: session not found',
+    });
+
+    await expect(
+      viewForkResource('/nonexistent/session', '0x1', '0x1::coin::CoinStore', {
+        adapter,
+      })
+    ).rejects.toThrow(/session not found/);
+  });
+});

package/src/fork/api.ts

@@ -2,14 +2,21 @@ import https from 'https';
 import http from 'http';
 import { URL } from 'url';
 import type { LedgerInfo, AccountData, AccountResource } from '../types/fork.js';
+import { normalizeAddressShort } from '../utils/address.js';
 
 /**
- * Client for interacting with Movement/Aptos-compatible JSON API
+ * Client for interacting with Movement L1 JSON API.
+ *
+ * When constructed with an `apiKey`, every outgoing request carries
+ * an `Authorization: Bearer <apiKey>` header. Use this for rate-
+ * limited public endpoints (e.g. Movement testnet under load) or
+ * auth-gated nodes.
  */
 export class MovementApiClient {
   private nodeUrl: string;
+  private readonly apiKey?: string;
 
-  constructor(nodeUrl: string) {
+  constructor(nodeUrl: string, apiKey?: string) {
     // Remove trailing slash
     let normalized = nodeUrl.replace(/\/$/, '');
 
@@ -20,10 +27,16 @@ export class MovementApiClient {
     }
 
     this.nodeUrl = normalized;
+    if (apiKey !== undefined) this.apiKey = apiKey;
   }
 
   /**
-   * Make a GET request to the API
+   * Make a GET request to the API.
+   *
+   * Adds `Authorization: Bearer <apiKey>` when the client was
+   * constructed with an `apiKey`. The header is omitted otherwise
+   * to preserve backwards-compatible behavior for unauthenticated
+   * public endpoints.
    */
   private async get<T>(path: string): Promise<T> {
     const fullUrl = `${this.nodeUrl}${path}`;
@@ -31,8 +44,16 @@ export class MovementApiClient {
     const isHttps = parsedUrl.protocol === 'https:';
     const client = isHttps ? https : http;
 
+    const requestOptions: {
+      method: 'GET';
+      headers?: Record<string, string>;
+    } = { method: 'GET' };
+    if (this.apiKey !== undefined) {
+      requestOptions.headers = { Authorization: `Bearer ${this.apiKey}` };
+    }
+
     return new Promise((resolve, reject) => {
-      const req = client.get(fullUrl, (res) => {
+      const req = client.get(fullUrl, requestOptions, (res) => {
         let data = '';
 
         res.on('data', (chunk) => {
@@ -82,10 +103,7 @@ export class MovementApiClient {
    * 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()}`;
+    const normalizedAddress = normalizeAddressShort(address);
 
     return this.get<AccountData>(this.apiPath(`/accounts/${normalizedAddress}`));
   }
@@ -94,9 +112,7 @@ export class MovementApiClient {
    * Get a specific account resource
    */
   async getAccountResource(address: string, resourceType: string): Promise<any> {
-    const normalizedAddress = address.toLowerCase().startsWith('0x')
-      ? address.toLowerCase()
-      : `0x${address.toLowerCase()}`;
+    const normalizedAddress = normalizeAddressShort(address);
 
     // URL encode the resource type
     const encodedType = encodeURIComponent(resourceType);
@@ -108,9 +124,7 @@ export class MovementApiClient {
    * Get all resources for an account
    */
   async getAccountResources(address: string): Promise<AccountResource[]> {
-    const normalizedAddress = address.toLowerCase().startsWith('0x')
-      ? address.toLowerCase()
-      : `0x${address.toLowerCase()}`;
+    const normalizedAddress = normalizeAddressShort(address);
 
     return this.get<AccountResource[]>(this.apiPath(`/accounts/${normalizedAddress}/resources`));
   }