movehat 0.2.1 → 0.2.3

package/src/helpers/__tests__/setupLocalTesting.fork-network.test.ts

@@ -0,0 +1,212 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * F1 — Harness.createFork(network) must honor the requested network.
+ *
+ * Mocks ForkManager so we can capture which RPC URL the fresh-fork
+ * code path picks. Strategy mirrors the pattern in
+ * src/fork/__tests__/manager.test.ts: replace the manager module with
+ * a stub that records every call to `initialize`.
+ *
+ * The mock also implements `load()` + `getMetadata()` so the
+ * "fork-exists, wrong network" case (audit-f1 follow-up) can exercise
+ * the metadata-mismatch guard in the `else` branch of `setupWithFork`.
+ */
+
+interface InitCall {
+  nodeUrl: string;
+  networkName?: string;
+  apiKey?: string;
+}
+const initializeCalls: InitCall[] = [];
+
+vi.mock("../../fork/manager.js", async () => {
+  const fs = await import("node:fs");
+  return {
+    ForkManager: class {
+      forkPath: string;
+      metadata: { network: string; nodeUrl: string } | null = null;
+      constructor(forkPath: string) {
+        this.forkPath = forkPath;
+      }
+      async initialize(nodeUrl: string, networkName?: string, apiKey?: string) {
+        const entry: InitCall = { nodeUrl };
+        if (networkName !== undefined) entry.networkName = networkName;
+        if (apiKey !== undefined) entry.apiKey = apiKey;
+        initializeCalls.push(entry);
+        this.metadata = { network: networkName ?? "custom", nodeUrl };
+      }
+      load() {
+        const raw = fs.readFileSync(`${this.forkPath}/metadata.json`, "utf-8");
+        this.metadata = JSON.parse(raw);
+      }
+      getMetadata() {
+        if (!this.metadata) {
+          throw new Error("Fork not initialized");
+        }
+        return this.metadata;
+      }
+      setApiKey() {}
+      async resetState() {}
+      async fundAccount() {}
+      async fundMultipleAccounts() {}
+    },
+  };
+});
+
+vi.mock("../../fork/server.js", () => {
+  return {
+    ForkServer: class {
+      constructor(_p: string, _port: number) {}
+      async start() {}
+      async stop() {}
+    },
+  };
+});
+
+vi.mock("../../runtime.js", () => ({
+  initRuntime: vi.fn(async () => ({})),
+}));
+
+vi.mock("../../core/AccountManager.js", () => {
+  let _seq = 0;
+  return {
+    AccountManager: {
+      createBatch(labels: readonly string[]) {
+        const out: Record<string, { accountAddress: { toString(): string } }> = {};
+        for (const l of labels) {
+          _seq++;
+          const addr = "0x" + _seq.toString(16).padStart(64, "0");
+          out[l] = { accountAddress: { toString: () => addr } };
+        }
+        return out;
+      },
+      exportPrivateKeys(_labels: readonly string[]) {
+        return { deployer: "0x" + "1".repeat(64) };
+      },
+    },
+  };
+});
+
+// Imported after mocks so vi.hoisted ordering applies.
+import { setupLocalTesting } from "../setupLocalTesting.js";
+import { logger } from "../../ui/index.js";
+
+describe("F1 — setupLocalTesting honors forkNetwork", () => {
+  let cwdBackup: string;
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    initializeCalls.length = 0;
+    cwdBackup = process.cwd();
+    tmpRoot = mkdtempSync(join(tmpdir(), "movehat-f1-"));
+    process.chdir(tmpRoot);
+    vi.spyOn(logger, "step").mockImplementation(() => undefined);
+    vi.spyOn(logger, "success").mockImplementation(() => undefined);
+    vi.spyOn(logger, "plain").mockImplementation(() => undefined);
+    vi.spyOn(logger, "newline").mockImplementation(() => undefined);
+    vi.spyOn(logger, "warning").mockImplementation(() => undefined);
+    vi.spyOn(logger, "error").mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    process.chdir(cwdBackup);
+    rmSync(tmpRoot, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("uses the mainnet RPC when forkNetwork = 'mainnet'", async () => {
+    await setupLocalTesting({
+      mode: "fork",
+      forkNetwork: "mainnet",
+      accountLabels: ["deployer"],
+      autoFund: false,
+    });
+
+    expect(initializeCalls).toHaveLength(1);
+    const call = initializeCalls[0]!;
+    expect(call.networkName).toBe("mainnet");
+    expect(call.nodeUrl).not.toMatch(/testnet/i);
+    expect(call.nodeUrl).toMatch(/mainnet/i);
+  });
+
+  it("uses the testnet RPC when forkNetwork = 'testnet'", async () => {
+    await setupLocalTesting({
+      mode: "fork",
+      forkNetwork: "testnet",
+      accountLabels: ["deployer"],
+      autoFund: false,
+    });
+
+    expect(initializeCalls).toHaveLength(1);
+    const call = initializeCalls[0]!;
+    expect(call.networkName).toBe("testnet");
+    expect(call.nodeUrl).toMatch(/testnet/i);
+  });
+
+  it("uses forkRpcUrl override when supplied for a custom network", async () => {
+    await setupLocalTesting({
+      mode: "fork",
+      forkNetwork: "custom",
+      forkRpcUrl: "https://my-custom-node.example/v1",
+      accountLabels: ["deployer"],
+      autoFund: false,
+    });
+
+    expect(initializeCalls).toHaveLength(1);
+    const call = initializeCalls[0]!;
+    expect(call.networkName).toBe("custom");
+    expect(call.nodeUrl).toBe("https://my-custom-node.example/v1");
+  });
+
+  it("rejects a non-built-in forkNetwork when no forkRpcUrl is provided", async () => {
+    await expect(
+      setupLocalTesting({
+        mode: "fork",
+        forkNetwork: "some-unknown-network",
+        accountLabels: ["deployer"],
+        autoFund: false,
+      })
+    ).rejects.toThrow(/forkRpcUrl/i);
+    expect(initializeCalls).toHaveLength(0);
+  });
+
+  it("rejects when an existing fork's saved network does not match the requested one (audit-f1 follow-up)", async () => {
+    // Pre-seed `.movehat/forks/test-local/metadata.json` with the
+    // wrong network so the `forkExists` branch fires and loads stale
+    // metadata. Without the metadata-mismatch guard, setupLocalTesting
+    // would silently serve a testnet snapshot while the caller thinks
+    // it's reading mainnet.
+    const forkDir = join(tmpRoot, ".movehat", "forks", "test-local");
+    mkdirSync(forkDir, { recursive: true });
+    writeFileSync(
+      join(forkDir, "metadata.json"),
+      JSON.stringify({
+        network: "testnet",
+        nodeUrl: "https://testnet.movementnetwork.xyz/v1",
+        chainId: 250,
+        ledgerVersion: "0",
+        timestamp: "0",
+        epoch: "0",
+        blockHeight: "0",
+        createdAt: new Date().toISOString(),
+      }),
+    );
+
+    await expect(
+      setupLocalTesting({
+        mode: "fork",
+        forkNetwork: "mainnet",
+        accountLabels: ["deployer"],
+        autoFund: false,
+      })
+    ).rejects.toThrow(/network mismatch|created for|requested/i);
+    // Must not have re-initialized — the existing dir is what poisons
+    // the load path, and silently reinitializing would clobber the
+    // user's saved snapshot.
+    expect(initializeCalls).toHaveLength(0);
+  });
+});

package/src/helpers/setupLocalTesting.ts

@@ -9,6 +9,25 @@ 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}.
  *
@@ -76,9 +95,9 @@ export async function setupLocalTesting(
   const accountLabels = options.accountLabels || ["deployer", "alice", "bob"];
 
   logger.newline();
-  logger.step("Setting up local testing environment...");
-  logger.plain(`   Mode: ${mode}`);
-  logger.plain(`   Accounts: ${accountLabels.join(", ")}`);
+  logger.phase("Setting up local testing environment");
+  logger.kv("Mode", mode, 2);
+  logger.kv("Accounts", accountLabels.join(", "), 2);
   logger.newline();
 
   if (mode === 'local-node') {
@@ -264,8 +283,8 @@ async function setupWithFork(
 
   if (!forkExists) {
     logger.step(`Creating fork from ${forkNetwork}...`);
-    const testnetRpc = "https://testnet.movementnetwork.xyz/v1";
-    await forkManager.initialize(testnetRpc, forkNetwork, options.forkApiKey);
+    const rpcUrl = resolveForkRpcUrl(forkNetwork, options.forkRpcUrl);
+    await forkManager.initialize(rpcUrl, forkNetwork, options.forkApiKey);
     logger.success(`Fork created at ${forkPath}`);
     logger.newline();
   } else {
@@ -278,6 +297,21 @@ async function setupWithFork(
     }
     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();

package/src/index.ts

@@ -19,4 +19,12 @@ export type { ForkMetadata, AccountState, LedgerInfo, AccountData, AccountResour
 export { ModuleAlreadyDeployedError, PostPublishError } from "./errors.js";
 
 export { Harness, HarnessDisposedError } from "./harness/index.js";
-export type { HarnessMode } from "./harness/index.js";
+export type { HarnessMode } from "./harness/index.js";
+export type {
+  DeployCodeObjectOptions,
+  UpgradeCodeObjectOptions,
+  CodeObjectInfo,
+  RunViewFunctionOptions,
+  RunMoveScriptOptions,
+  MoveScriptResult,
+} from "./types/harness.js";

package/src/node/LocalNodeManager.ts

@@ -6,13 +6,30 @@ import {
   type ChildProcessAdapter,
   type SpawnedProcess,
 } from "../utils/childProcessAdapter.js";
-import { logger } from "../ui/index.js";
+import { logger, isVerbose, colors, symbols } from "../ui/index.js";
+import { withTimedSpinner, withSpinner } from "../ui/spinner.js";
+
+/**
+ * Substrings that always surface from the movement subprocess regardless
+ * of verbosity. These are signals the user must see to debug a stuck
+ * startup (panic, fatal, address-in-use). Tested in
+ * __tests__/LocalNodeManager.test.ts to guard against silent regressions.
+ */
+const CRITICAL_NODE_OUTPUT = /panic|fatal|address already in use|EADDRINUSE/i;
 
 export interface LocalNodeOptions {
   testDir?: string;           // Directory for node data (default: .movehat/local-node)
   forceRestart?: boolean;     // Clean state and start fresh
   faucetPort?: number;        // Faucet port (default: 8081)
-  apiPort?: number;           // API/RPC port (default: 8080)
+  /**
+   * REST API port. Movement CLI (`movement node run-localnet`) does
+   * not accept a flag to change this — the node always binds 8080.
+   * Passing any other value triggers a warning at construction time
+   * and is replaced with 8080. Field is kept for source compatibility.
+   *
+   * @deprecated Movement CLI does not honor this. Omit it.
+   */
+  apiPort?: number;
   readyPort?: number;         // Ready server port (default: 8070)
   silent?: boolean;           // Suppress node output
   /**
@@ -22,6 +39,8 @@ export interface LocalNodeOptions {
   adapter?: ChildProcessAdapter;
 }
 
+const MOVEMENT_API_PORT = 8080;
+
 export interface LocalNodeInfo {
   rpcUrl: string;
   faucetUrl: string;
@@ -47,11 +66,23 @@ export class LocalNodeManager {
 
   constructor(options: LocalNodeOptions = {}) {
     this.adapter = options.adapter ?? defaultChildProcessAdapter;
+    if (
+      options.apiPort !== undefined &&
+      options.apiPort !== MOVEMENT_API_PORT
+    ) {
+      // Movement CLI hardcodes the REST API port to 8080. Surfacing
+      // the requested port via getNodeInfo() would lie about where
+      // the node actually listens.
+      logger.warning(
+        `LocalNodeManager: apiPort=${options.apiPort} is not supported by ` +
+          `movement node run-localnet; forcing REST API port to 8080.`
+      );
+    }
     this.options = {
       testDir: options.testDir || join(process.cwd(), ".movehat", "local-node"),
       forceRestart: options.forceRestart ?? false,
       faucetPort: options.faucetPort || 8081,
-      apiPort: options.apiPort || 8080,
+      apiPort: MOVEMENT_API_PORT,
       readyPort: options.readyPort || 8070,
       silent: options.silent ?? false,
     };
@@ -64,7 +95,7 @@ export class LocalNodeManager {
    */
   async start(): Promise<LocalNodeInfo> {
     if (this.spawned) {
-      console.log("Local node already running");
+      logger.info("Local node already running");
       return this.getNodeInfo();
     }
 
@@ -76,11 +107,11 @@ export class LocalNodeManager {
 
     try {
       logger.newline();
-      logger.step("Starting local Movement node...");
-      logger.plain(`   Test directory: ${this.options.testDir}`);
-      logger.plain(`   RPC port: ${this.options.apiPort}`);
-      logger.plain(`   Faucet port: ${this.options.faucetPort}`);
-      logger.plain(`   Ready port: ${this.options.readyPort}`);
+      logger.step("Starting local Movement node");
+      logger.kv("Test directory", this.options.testDir, 2);
+      logger.kv("RPC port", String(this.options.apiPort), 2);
+      logger.kv("Faucet port", String(this.options.faucetPort), 2);
+      logger.kv("Ready port", String(this.options.readyPort), 2);
       logger.newline();
 
       // Clean state if force restart
@@ -111,19 +142,43 @@ export class LocalNodeManager {
         stdio: this.options.silent ? "ignore" : "pipe",
       });
 
-      // Handle process output
+      // Subprocess output handling (see §9 Console UX in CLAUDE.md):
+      //   - stdout chatter is hidden by default; gated by isVerbose()
+      //   - lines matching CRITICAL_NODE_OUTPUT always surface as warnings
+      //     so the user is never silenced through a real failure
+      //   - stderr is always surfaced (real signal), modulo benign WARN
+      //     lines that the movement binary emits during normal startup
       if (!this.options.silent && this.spawned.stdout && this.spawned.stderr) {
         this.spawned.stdout.on("data", (data: Buffer) => {
           const output = data.toString().trim();
-          if (output) {
-            console.log(`[Node] ${output}`);
+          if (!output) return;
+          if (CRITICAL_NODE_OUTPUT.test(output)) {
+            logger.warning(output);
+            return;
+          }
+          if (isVerbose()) {
+            for (const line of output.split("\n")) {
+              if (line) console.log(`  ${colors.muted(symbols.pointer + " " + line)}`);
+            }
           }
         });
 
         this.spawned.stderr.on("data", (data: Buffer) => {
           const output = data.toString().trim();
-          if (output && !output.includes("WARN")) {
-            console.error(`[Node Error] ${output}`);
+          if (!output) return;
+          // Movement CLI uses stderr for both progress messages
+          // ("Applying post startup steps...", "Compiling...") and
+          // real errors. Stream channel alone isn't a reliable
+          // signal — gate routine lines behind verbosity, escalate
+          // anything matching CRITICAL_NODE_OUTPUT regardless.
+          if (CRITICAL_NODE_OUTPUT.test(output)) {
+            logger.error(output);
+            return;
+          }
+          if (isVerbose()) {
+            for (const line of output.split("\n")) {
+              if (line) console.error(`  ${colors.muted(symbols.pointer + " " + line)}`);
+            }
           }
         });
       }
@@ -139,11 +194,13 @@ export class LocalNodeManager {
         this.spawned = null;
       });
 
-      // Wait for node to be ready
-      logger.step("Waiting for node to be ready...");
-      await this.waitForReady(60000); // 60 second timeout
+      // Wait for node to be ready — wrapped in withTimedSpinner so the
+      // user sees live elapsed-time feedback while subprocess chatter is
+      // hidden in non-verbose mode.
+      await withTimedSpinner("Waiting for node to be ready", () =>
+        this.waitForReady(60000)
+      );
 
-      logger.success("Local Movement node is ready!");
       logger.newline();
 
       this.starting = false;
@@ -281,7 +338,9 @@ export class LocalNodeManager {
       }
 
       const result = await response.json();
-      logger.success(`Funded ${address} with ${amount} octas`, 2);
+      if (isVerbose()) {
+        logger.success(`Funded ${address} with ${amount} octas`, 2);
+      }
 
       return result;
     } catch (error) {
@@ -295,13 +354,15 @@ export class LocalNodeManager {
    */
   async fundAccounts(accounts: (Account | string)[], amount: number = 100_000_000): Promise<void> {
     logger.newline();
-    logger.step(`Funding ${accounts.length} accounts from local faucet...`);
-
-    for (const account of accounts) {
-      await this.fundAccount(account, amount);
-    }
-
-    logger.success("All accounts funded successfully");
+    await withSpinner(
+      `Funding ${accounts.length} accounts from local faucet`,
+      async () => {
+        for (const account of accounts) {
+          await this.fundAccount(account, amount);
+        }
+      },
+      `Funded ${accounts.length} accounts (${(amount / 1e8).toFixed(0)} APT each)`,
+    );
     logger.newline();
   }
 

package/src/node/__tests__/LocalNodeManager.api-port.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { LocalNodeManager } from "../LocalNodeManager.js";
+import { logger } from "../../ui/index.js";
+
+/**
+ * F9 — `apiPort` must not lie about where the node listens.
+ *
+ * `movement node run-localnet` (Movement CLI 7.4.0) does NOT accept a
+ * flag to change the REST API port. It always binds 8080. Earlier
+ * versions of LocalNodeManager accepted `apiPort: 9000` from the
+ * caller, stored it, and surfaced `http://127.0.0.1:9000` from
+ * `getNodeInfo()` — but the actual node was still on 8080. That
+ * mismatch would silently surface as "Movement command failed" with
+ * no useful signal. F9 closes the gap by refusing to lie: the
+ * effective port is 8080 regardless of what the caller passes, with a
+ * warning when they pass anything else.
+ */
+
+describe("F9 — LocalNodeManager apiPort is constrained to 8080", () => {
+  let tmpDir: string;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "movehat-f9-"));
+    warnSpy = vi.spyOn(logger, "warning").mockImplementation(() => undefined);
+    vi.spyOn(logger, "step").mockImplementation(() => undefined);
+    vi.spyOn(logger, "plain").mockImplementation(() => undefined);
+    vi.spyOn(logger, "newline").mockImplementation(() => undefined);
+    vi.spyOn(logger, "success").mockImplementation(() => undefined);
+    vi.spyOn(logger, "error").mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("ignores non-default apiPort, forces 8080, and warns", () => {
+    const mgr = new LocalNodeManager({ testDir: tmpDir, apiPort: 9000 });
+    expect(mgr.getNodeInfo().rpcUrl).toBe("http://127.0.0.1:8080");
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = warnSpy.mock.calls[0]?.[0] as string;
+    expect(msg).toMatch(/8080/);
+    expect(msg).toMatch(/apiPort|REST API port/i);
+  });
+
+  it("accepts apiPort: 8080 without warning", () => {
+    const mgr = new LocalNodeManager({ testDir: tmpDir, apiPort: 8080 });
+    expect(mgr.getNodeInfo().rpcUrl).toBe("http://127.0.0.1:8080");
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("accepts omitted apiPort without warning (default path)", () => {
+    const mgr = new LocalNodeManager({ testDir: tmpDir });
+    expect(mgr.getNodeInfo().rpcUrl).toBe("http://127.0.0.1:8080");
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});