movehat 0.1.8 → 0.2.0

package/src/templates/types/movehat.d.ts

@@ -50,16 +50,10 @@ declare module 'movehat' {
     createAccount: () => Account;
     getAccount: (privateKey: string) => Account;
     getAccountByIndex: (index: number) => Account;
-    switchNetwork: (networkName: string) => Promise<void>;
+    switchNetwork: (networkName: string) => Promise<MovehatRuntime>;
   }
 
-  export function getMovehat(): Promise<MovehatRuntime>;
   export function initRuntime(configOverride?: Partial<MovehatConfig>): Promise<MovehatRuntime>;
-  export function getRuntime(): MovehatRuntime;
-
-  export const mh: {
-    readonly runtime: MovehatRuntime;
-  };
 }
 
 declare module 'movehat/helpers' {
@@ -68,12 +62,15 @@ declare module 'movehat/helpers' {
   export interface TestEnvironment {
     aptos: Aptos;
     account: Account;
-    config: any;
+    config: import('movehat').MovehatConfig;
   }
 
   export class MoveContract {
     constructor(aptos: Aptos, address: string, moduleName: string);
-    call(sender: Account, functionName: string, args: any[]): Promise<any>;
+    // args: any[] mirrors the runtime declaration — Move entry-function
+    // arguments are heterogeneous primitives validated by the Aptos SDK
+    // at submit time.
+    call(sender: Account, functionName: string, args: any[]): Promise<TransactionResult>;
     view<T>(functionName: string, args: any[]): Promise<T>;
   }
 

package/src/types/config.ts

@@ -59,6 +59,14 @@ export interface LocalTestOptions {
     forkName?: string;                  // Name for the fork (default: 'test-local')
     forkPort?: number;                  // Fork server port (default: 8080)
     forkResetState?: boolean;           // Clear fork state before tests (default: true)
+    /**
+     * Optional API key sent as `Authorization: Bearer <key>` on every
+     * outgoing Movement API request made by the fork's
+     * `MovementApiClient`. Use for rate-limited public endpoints or
+     * auth-gated nodes. The key stays in process memory only — not
+     * persisted to the fork's on-disk metadata.
+     */
+    forkApiKey?: string;
 
     // Common options (both modes)
     autoFund?: boolean;                 // Auto-fund accounts (default: true)

package/src/types/fork.ts

@@ -37,5 +37,11 @@ export interface AccountData {
 
 export interface AccountResource {
   type: string;
-  data: any;
+  /**
+   * Move resource payload — structurally a JSON-shaped object whose
+   * schema depends on the resource type (CoinStore, AggregatorSnapshot, etc).
+   * unknown forces callers to narrow before access; the boundary-validation
+   * follow-up of #57 will add per-resource type guards.
+   */
+  data: unknown;
 }

package/src/types/harness.ts

@@ -0,0 +1,182 @@
+import type { DeploymentInfo } from "../core/deployments.js";
+import type { ChildProcessAdapter } from "../utils/childProcessAdapter.js";
+
+/**
+ * Options for `harness.deployCodeObject(options)`.
+ *
+ * Wraps `movement move deploy-object`. The Movement CLI derives the
+ * destination object address from the signing account; that address is
+ * bound to `moduleName` (passed as `--address-name`) at compile time.
+ * Callers retrieve the resulting object address via the returned
+ * `CodeObjectInfo.address`.
+ */
+export interface DeployCodeObjectOptions {
+  /**
+   * Logical module identifier (the `name` part of `module addr::name`).
+   * Used as the persistence key (`deployments/{network}/{moduleName}.json`)
+   * and as the `name` arg you'd pass to `runtime.getContract(addr, name)`
+   * after deployment.
+   *
+   * If `addressName` is omitted, `moduleName` is also used as the CLI's
+   * `--address-name` flag (correct when the Move.toml's named address
+   * matches the module identifier). For packages where they differ —
+   * e.g. `module hello_blockchain::counter` (named address
+   * `hello_blockchain`, module `counter`) — set `addressName` explicitly.
+   */
+  moduleName: string;
+
+  /**
+   * Move.toml named address that the derived object address binds to
+   * at compile time (the `--address-name` flag of `move deploy-object`).
+   *
+   * Defaults to `moduleName`. Set this when the Move.toml's named
+   * address differs from the on-chain module identifier:
+   *
+   * ```ts
+   * // Move source: `module hello_blockchain::counter`
+   * // Move.toml:   `[addresses] hello_blockchain = "_"`
+   * await harness.deployCodeObject({
+   *   moduleName: "counter",            // for getContract + save key
+   *   addressName: "hello_blockchain",  // for --address-name
+   * });
+   * ```
+   */
+  addressName?: string;
+
+  /**
+   * Extra named-address overrides merged on top of the addresses
+   * auto-detected from `<packageDir>/sources/**.move`. Values here win
+   * for the matching keys; auto-detected names not present here are
+   * still pinned to the deployer address (Publisher convention).
+   */
+  namedAddresses?: Record<string, string>;
+
+  /**
+   * Path to the Move package. Defaults to `config.moveDir` from the
+   * harness's runtime config (usually `./move`).
+   */
+  packageDir?: string;
+
+  /**
+   * Artifact set written into the on-chain package. Mirrors the CLI
+   * flag. Defaults to `'sparse'` (the Movement CLI default).
+   */
+  includedArtifacts?: "none" | "sparse" | "all";
+
+  /**
+   * Test-only override for the child-process adapter. Production callers
+   * leave this undefined so the default spawn-based adapter is used.
+   * @internal
+   */
+  adapter?: ChildProcessAdapter;
+}
+
+/**
+ * Options for `harness.upgradeCodeObject(options)`.
+ *
+ * Wraps `movement move upgrade-object`. The object must already exist
+ * on-chain at `objectAddress` and have been deployed previously (typically
+ * via `deployCodeObject`).
+ */
+export interface UpgradeCodeObjectOptions extends DeployCodeObjectOptions {
+  /** Address of the existing code object to upgrade. Required. */
+  objectAddress: string;
+}
+
+/**
+ * Result of `deployCodeObject` / `upgradeCodeObject`.
+ *
+ * Today this is structurally identical to {@link DeploymentInfo} — the
+ * `address` field holds the derived **object address** (the value
+ * callers pass to `runtime.getContract(...)` to interact with the
+ * modules), and `deployer` is the signing account.
+ *
+ * The alias exists so future iterations can layer additional fields
+ * (e.g. an explicit `kind: 'code-object' | 'publish'` discriminator)
+ * without churning every callsite.
+ */
+export type CodeObjectInfo = DeploymentInfo;
+
+/**
+ * Options for `harness.runViewFunction(options)`.
+ *
+ * Delegates to the Aptos SDK's `aptos.view(...)` — no CLI invocation,
+ * no profile management. Works on `createLocal`, `createFork`, and
+ * `createLive` harnesses (view functions are read-only).
+ */
+export interface RunViewFunctionOptions {
+  /**
+   * Fully qualified Move function id, e.g. `0xCAFE::counter::get`.
+   */
+  function: string;
+
+  /**
+   * Move type-tag arguments, e.g. `['0x1::aptos_coin::AptosCoin']`.
+   */
+  typeArguments?: string[];
+
+  /**
+   * Move function arguments. SDK-validated at the boundary; pass values
+   * matching the Move function signature (strings for `address`,
+   * numbers / bigints for `u8`-`u256`, booleans, etc.).
+   */
+  functionArguments?: unknown[];
+}
+
+/**
+ * Options for `harness.runMoveScript(options)`.
+ *
+ * Wraps `movement move run-script`. The CLI handles compilation
+ * inline when given a `.move` source; the user can also pass a
+ * pre-compiled `.mv` bytecode file.
+ *
+ * Not available on fork-mode harnesses (forks are read-only).
+ */
+export interface RunMoveScriptOptions {
+  /**
+   * Path to the Move script. Extension determines the CLI flag:
+   *   - `.move` → `--script-path` (CLI auto-compiles)
+   *   - `.mv` → `--compiled-script-path` (user pre-compiled)
+   * Other extensions throw synchronously before any CLI call.
+   */
+  scriptPath: string;
+
+  /**
+   * CLI-formatted typed arguments. Movement CLI expects each arg
+   * prefixed by its Move type, e.g. `'address:0x1'`, `'u8:42'`,
+   * `'bool:true'`, `'string:hello'`. See
+   * `movement move run-script --help` for the full grammar.
+   */
+  args?: string[];
+
+  /**
+   * Type-tag arguments for generic scripts, e.g.
+   * `['0x1::aptos_coin::AptosCoin']`.
+   */
+  typeArgs?: string[];
+
+  /**
+   * Optional working directory for compilation. Most callers leave
+   * this undefined — the CLI uses the script's parent directory.
+   */
+  packageDir?: string;
+
+  /**
+   * Test-only override for the child-process adapter.
+   * @internal
+   */
+  adapter?: ChildProcessAdapter;
+}
+
+/**
+ * Result of `harness.runMoveScript`.
+ *
+ * Always carries `txHash` (parser throws if it can't extract one).
+ * `success` and `vmStatus` are best-effort: parsed from the CLI's
+ * JSON `Result` block when present, `undefined` if the parser misses.
+ */
+export interface MoveScriptResult {
+  txHash: string;
+  success?: boolean;
+  vmStatus?: string;
+}

package/src/types/runtime.ts

@@ -2,6 +2,7 @@ import { Aptos, Account } from "@aptos-labs/ts-sdk";
 import { MovehatConfig } from "./config.js";
 import { MoveContract } from "../core/contract.js";
 import { DeploymentInfo } from "../core/deployments.js";
+import type { ChildProcessAdapter } from "../utils/childProcessAdapter.js";
 
 export interface NetworkInfo {
   name: string;
@@ -16,7 +17,7 @@ export interface MovehatRuntime {
   // Network information
   network: NetworkInfo;
 
-  // Aptos client instance
+  // Movement TypeScript SDK client instance
   aptos: Aptos;
 
   // Default account from config (accounts[0])
@@ -33,6 +34,11 @@ export interface MovehatRuntime {
     moduleName: string,
     options?: {
       packageDir?: string;
+      /**
+       * Override the child-process adapter. Test-only: production callers
+       * leave this undefined so the default spawn-based adapter is used.
+       */
+      adapter?: ChildProcessAdapter;
     }
   ) => Promise<DeploymentInfo>;
   getDeployment: (moduleName: string) => DeploymentInfo | null;
@@ -44,6 +50,8 @@ export interface MovehatRuntime {
   getAccount: (privateKey: string) => Account;
   getAccountByIndex: (index: number) => Account;
 
-  // Network switching
-  switchNetwork: (networkName: string) => Promise<void>;
+  // Network switching — returns a new runtime bound to the requested
+  // network. As of M1.5 there is no module-cached runtime, so callers
+  // must capture and use the returned instance.
+  switchNetwork: (networkName: string) => Promise<MovehatRuntime>;
 }

package/src/ui/__tests__/colors.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  shouldUseColor,
+  colors,
+  rgbToAnsi,
+  applyGradient,
+  gradients,
+} from '../colors.js';
+
+describe('shouldUseColor', () => {
+  const originalEnv = process.env;
+  const originalIsTTY = process.stdout.isTTY;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env.NO_COLOR;
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY });
+  });
+
+  it('should return true when TTY and NO_COLOR not set', () => {
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
+    delete process.env.NO_COLOR;
+    expect(shouldUseColor()).toBe(true);
+  });
+
+  it('should return false when NO_COLOR is set', () => {
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
+    process.env.NO_COLOR = '1';
+    expect(shouldUseColor()).toBe(false);
+  });
+
+  it('should return false when not TTY', () => {
+    Object.defineProperty(process.stdout, 'isTTY', { value: false, configurable: true });
+    delete process.env.NO_COLOR;
+    expect(shouldUseColor()).toBe(false);
+  });
+});
+
+describe('rgbToAnsi', () => {
+  it('should generate correct ANSI escape code', () => {
+    expect(rgbToAnsi(255, 0, 0)).toBe('\x1b[38;2;255;0;0m');
+    expect(rgbToAnsi(0, 255, 0)).toBe('\x1b[38;2;0;255;0m');
+    expect(rgbToAnsi(0, 0, 255)).toBe('\x1b[38;2;0;0;255m');
+    expect(rgbToAnsi(128, 128, 128)).toBe('\x1b[38;2;128;128;128m');
+  });
+
+  it('should handle edge values', () => {
+    expect(rgbToAnsi(0, 0, 0)).toBe('\x1b[38;2;0;0;0m');
+    expect(rgbToAnsi(255, 255, 255)).toBe('\x1b[38;2;255;255;255m');
+  });
+});
+
+describe('applyGradient', () => {
+  const originalEnv = process.env;
+  const originalIsTTY = process.stdout.isTTY;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env.NO_COLOR;
+    Object.defineProperty(process.stdout, 'isTTY', { value: true, configurable: true });
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY });
+  });
+
+  it('should apply gradient to text', () => {
+    const palette = [[255, 0, 0], [0, 255, 0]] as [number, number, number][];
+    const result = applyGradient('AB', palette);
+
+    expect(result).toContain('\x1b[38;2;255;0;0m'); // Red for 'A'
+    expect(result).toContain('\x1b[38;2;0;255;0m'); // Green for 'B'
+    expect(result).toContain('A');
+    expect(result).toContain('B');
+    expect(result).toContain('\x1b[0m'); // Reset at end
+  });
+
+  it('should return plain text when colors disabled', () => {
+    process.env.NO_COLOR = '1';
+    const palette = [[255, 0, 0]] as [number, number, number][];
+    const result = applyGradient('Hello', palette);
+
+    expect(result).toBe('Hello');
+    expect(result).not.toContain('\x1b');
+  });
+
+  it('should cycle through palette for long text', () => {
+    const palette = [[255, 0, 0], [0, 255, 0]] as [number, number, number][];
+    const result = applyGradient('ABCD', palette);
+
+    // Should alternate: A=red, B=green, C=red, D=green
+    expect(result).toContain('A');
+    expect(result).toContain('B');
+    expect(result).toContain('C');
+    expect(result).toContain('D');
+  });
+
+  it('should handle offset parameter', () => {
+    const palette = [[255, 0, 0], [0, 255, 0]] as [number, number, number][];
+    const result = applyGradient('AB', palette, 1);
+
+    // With offset 1: A=green, B=red
+    expect(result.indexOf('\x1b[38;2;0;255;0m')).toBeLessThan(result.indexOf('\x1b[38;2;255;0;0m'));
+  });
+});
+
+describe('gradients', () => {
+  it('should have movehat gradient with 5 colors', () => {
+    expect(gradients.movehat).toHaveLength(5);
+    gradients.movehat.forEach(([r, g, b]) => {
+      expect(r).toBeGreaterThanOrEqual(0);
+      expect(r).toBeLessThanOrEqual(255);
+      expect(g).toBeGreaterThanOrEqual(0);
+      expect(g).toBeLessThanOrEqual(255);
+      expect(b).toBeGreaterThanOrEqual(0);
+      expect(b).toBeLessThanOrEqual(255);
+    });
+  });
+
+  it('should have success gradient', () => {
+    expect(gradients.success).toBeDefined();
+    expect(gradients.success.length).toBeGreaterThan(0);
+  });
+
+  it('should have error gradient', () => {
+    expect(gradients.error).toBeDefined();
+    expect(gradients.error.length).toBeGreaterThan(0);
+  });
+});
+
+describe('colors object', () => {
+  it('should have all semantic color functions', () => {
+    expect(typeof colors.success).toBe('function');
+    expect(typeof colors.error).toBe('function');
+    expect(typeof colors.warning).toBe('function');
+    expect(typeof colors.info).toBe('function');
+    expect(typeof colors.primary).toBe('function');
+    expect(typeof colors.secondary).toBe('function');
+    expect(typeof colors.muted).toBe('function');
+    expect(typeof colors.dim).toBe('function');
+    expect(typeof colors.bold).toBe('function');
+    expect(typeof colors.brand).toBe('function');
+    expect(typeof colors.brandBright).toBe('function');
+  });
+
+  it('should return strings when called', () => {
+    expect(typeof colors.success('test')).toBe('string');
+    expect(typeof colors.error('test')).toBe('string');
+    expect(typeof colors.brand('test')).toBe('string');
+  });
+});

package/src/ui/colors.ts

@@ -86,8 +86,11 @@ export const applyGradient = (
   let result = '';
   for (let i = 0; i < text.length; i++) {
     const colorIndex = (i + offset) % palette.length;
-    const [r, g, b] = palette[colorIndex];
-    result += `${rgbToAnsi(r, g, b)}${text[i]}`;
+    const color = palette[colorIndex];
+    const ch = text[i];
+    if (!color || ch === undefined) continue;
+    const [r, g, b] = color;
+    result += `${rgbToAnsi(r, g, b)}${ch}`;
   }
   return result + '\x1b[0m';
 };

package/src/ui/logger.ts

@@ -119,6 +119,27 @@ export const warning = (message: string, indent: number = 0): void => {
   console.warn(`${coloredSymbol('warning')} ${formatted}`);
 };
 
+/**
+ * Action / progress message (dim chevron prefix)
+ * Use for in-progress action lines like "Building package", "Publishing
+ * to blockchain" — anything that's a status update during a multi-step
+ * operation. Distinct from `info` (general updates) and `success`
+ * (completion).
+ *
+ * @param message - Message to log
+ * @param indent - Number of spaces to indent (default: 0)
+ *
+ * @example
+ * logger.step('Building package...');
+ * logger.step('Publishing to blockchain...');
+ * logger.success('Module published successfully!');
+ */
+export const step = (message: string, indent: number = 0): void => {
+  if (config.silent) return;
+  const formatted = formatMessage(message, indent);
+  console.log(`${colors.dim(symbols.step)} ${formatted}`);
+};
+
 /**
  * Plain message without symbol
  * Use for continuation lines or when symbol is not appropriate
@@ -218,6 +239,7 @@ export const logger = {
   success,
   error,
   warning,
+  step,
   plain,
   newline,
   section,

package/src/ui/symbols.ts

@@ -16,7 +16,13 @@ export const symbols = {
   warning: figures.warning,       // ⚠ or ‼
   info: figures.info,             // ℹ or i
 
-  // Action symbols
+  // Action / progress symbols
+  step: '▸',                 // ▸  — used to prefix in-progress action lines
+                                  // (e.g. "▸ Building package"). Plain Unicode
+                                  // BLACK RIGHT-POINTING SMALL TRIANGLE, supported
+                                  // in every UTF-8 terminal. If a non-UTF-8
+                                  // environment ever surfaces, switch to
+                                  // figures.pointerSmall ('›' with ASCII fallback).
   pointer: figures.pointer,       // ❯ or >
   checkboxOn: figures.checkboxOn, // ☑ or [×]
   checkboxOff: figures.checkboxOff, // ☐ or [ ]

package/src/utils/__tests__/address.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isHexAddress,
+  normalizeAddress,
+  normalizeAddressShort,
+} from '../address.js';
+
+const PADDED_ONE = '0x' + '0'.repeat(63) + '1';
+const PADDED_DEAD = '0x' + '0'.repeat(60) + 'dead';
+
+describe('normalizeAddress', () => {
+  it('pads a short hex to 64 chars and adds 0x', () => {
+    expect(normalizeAddress('1')).toBe(PADDED_ONE);
+  });
+
+  it('preserves a fully padded address', () => {
+    const full = '0x' + 'a'.repeat(64);
+    expect(normalizeAddress(full)).toBe(full);
+  });
+
+  it('lowercases mixed-case input', () => {
+    expect(normalizeAddress('0xDEAD')).toBe(PADDED_DEAD);
+  });
+
+  it('adds the 0x prefix when missing', () => {
+    expect(normalizeAddress('dead')).toBe(PADDED_DEAD);
+  });
+
+  it('returns 0x followed by 64 zeros for empty input', () => {
+    expect(normalizeAddress('')).toBe('0x' + '0'.repeat(64));
+  });
+
+  it('matches fork/manager.ts legacy semantics for the canonical case', () => {
+    // Mirrors the inline `private normalizeAddress` from fork/manager.ts:243.
+    expect(normalizeAddress('0X1')).toBe(PADDED_ONE);
+  });
+});
+
+describe('normalizeAddressShort', () => {
+  it('adds 0x and lowercases without padding', () => {
+    expect(normalizeAddressShort('DEAD')).toBe('0xdead');
+  });
+
+  it('preserves the 0x prefix when already present', () => {
+    expect(normalizeAddressShort('0xBeef')).toBe('0xbeef');
+  });
+
+  it('does not pad a short address', () => {
+    expect(normalizeAddressShort('1')).toBe('0x1');
+  });
+
+  it('returns just 0x for empty input', () => {
+    expect(normalizeAddressShort('')).toBe('0x');
+  });
+});
+
+describe('isHexAddress', () => {
+  it('accepts short hex with 0x prefix', () => {
+    expect(isHexAddress('0x1')).toBe(true);
+  });
+
+  it('accepts hex without 0x prefix', () => {
+    expect(isHexAddress('dead')).toBe(true);
+  });
+
+  it('accepts uppercase 0X prefix', () => {
+    expect(isHexAddress('0Xabc')).toBe(true);
+  });
+
+  it('accepts a full 64-char address', () => {
+    expect(isHexAddress('0x' + 'f'.repeat(64))).toBe(true);
+  });
+
+  it('rejects empty string', () => {
+    expect(isHexAddress('')).toBe(false);
+  });
+
+  it('rejects lone 0x with no hex', () => {
+    expect(isHexAddress('0x')).toBe(false);
+  });
+
+  it('rejects non-hex characters', () => {
+    expect(isHexAddress('0xghij')).toBe(false);
+  });
+
+  it('rejects input longer than 64 hex chars', () => {
+    expect(isHexAddress('0x' + '0'.repeat(65))).toBe(false);
+  });
+
+  it('accepts mixed case hex', () => {
+    expect(isHexAddress('0xAbCdEf')).toBe(true);
+  });
+});