movehat 0.2.0 → 0.2.2

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}.
  *
@@ -20,8 +39,7 @@ import type { LocalTestOptions } from "../types/config.js";
  * @public The `runtime` and `teardown` fields are the supported surface.
  *         `localNode`, `forkServer`, and `forkManager` are exposed for
  *         escape hatches (e.g. mid-test `forkManager.resetState()`) but
- *         their concrete shapes are considered `@internal` until the M5
- *         TypeDoc pass formalizes the public API.
+ *         their concrete shapes are `@internal`.
  */
 export interface LocalTestingContext {
   runtime: MovehatRuntime;
@@ -265,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 {
@@ -279,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

@@ -18,6 +18,13 @@ export type { ForkMetadata, AccountState, LedgerInfo, AccountData, AccountResour
 // Export custom errors
 export { ModuleAlreadyDeployedError, PostPublishError } from "./errors.js";
 
-// Export Harness (Hardhat-style API — primary public surface from M2 onward)
 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

@@ -12,7 +12,15 @@ 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 +30,8 @@ export interface LocalNodeOptions {
   adapter?: ChildProcessAdapter;
 }
 
+const MOVEMENT_API_PORT = 8080;
+
 export interface LocalNodeInfo {
   rpcUrl: string;
   faucetUrl: string;
@@ -47,11 +57,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,
     };

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();
+  });
+});

package/src/node/__tests__/LocalNodeManager.test.ts

@@ -13,7 +13,7 @@ import type {
 } from "../../utils/childProcessAdapter.js";
 
 /**
- * Tests for `LocalNodeManager` (M3.3).
+ * Tests for `LocalNodeManager`.
  *
  * Strategy:
  *   - Inject a fake `ChildProcessAdapter` so we control the spawn
@@ -126,17 +126,18 @@ describe("LocalNodeManager — start / stop / lifecycle", () => {
     expect(info.testDir).toBe(tmpDir);
   });
 
-  it("honors custom ports from constructor options", () => {
+  it("honors custom faucet/ready ports; apiPort is pinned to 8080 (see F9)", () => {
     const { adapter } = buildFakeAdapter();
     const mgr = new LocalNodeManager({
       adapter,
       testDir: tmpDir,
-      apiPort: 9000,
       faucetPort: 9001,
       readyPort: 9002,
     });
     const info = mgr.getNodeInfo();
-    expect(info.rpcUrl).toContain(":9000");
+    // Movement CLI does not accept a flag for the REST API port; see
+    // LocalNodeManager.api-port.test.ts for the F9 contract.
+    expect(info.rpcUrl).toBe("http://127.0.0.1:8080");
     expect(info.faucetUrl).toContain(":9001");
     expect(info.readyUrl).toContain(":9002");
   });

package/src/runtime.ts

@@ -93,9 +93,7 @@ export async function initRuntime(
       adapter?: ChildProcessAdapter;
     }
   ): Promise<DeploymentInfo> => {
-    // Thin orchestrator over Publisher (M1.4 / #79). The 250-line closure
-    // body lives in core/Publisher.ts and carries the bug fixes for
-    // #36 / #37 / #38.
+    // Thin orchestrator; the actual logic lives in core/Publisher.ts.
     return new Publisher({ adapter: options?.adapter }).deploy({
       moduleName,
       config,

package/src/templates/move/Move.toml

@@ -1,5 +1,5 @@
 [package]
-name = "{{projectName}}"
+name = "{{movePackageName}}"
 version = "1.0.0"
 authors = []
 

package/src/templates/move/sources/Counter.move

@@ -33,7 +33,16 @@ module counter::counter {
 
     public entry fun increment(account: &signer) acquires Counter {
         let account_addr = signer::address_of(account);
-        assert!(exists<Counter>(account_addr), E_NOT_INITIALIZED);
+
+        // Auto-init: create Counter if it doesn't exist yet. Defense in
+        // depth so the module stays usable even if a caller skips the
+        // dedicated `init` entry function.
+        if (!exists<Counter>(account_addr)) {
+            move_to(account, Counter {
+                value: 0,
+                increment_events: account::new_event_handle<IncrementEvent>(account),
+            });
+        };
 
         let counter = borrow_global_mut<Counter>(account_addr);
         let old_value = counter.value;
@@ -56,14 +65,32 @@ module counter::counter {
     public fun test_increment(account: &signer) acquires Counter {
         let addr = signer::address_of(account);
         aptos_framework::account::create_account_for_test(addr);
-        
+
         init(account);
         assert!(get(addr) == 0, 0);
-        
+
         increment(account);
         assert!(get(addr) == 1, 1);
-        
+
         increment(account);
         assert!(get(addr) == 2, 2);
     }
+
+    // Regression guard: increment must auto-create the Counter resource
+    // when called against a never-initialized account. Locks the
+    // defense-in-depth behavior so a future refactor can't accidentally
+    // remove it.
+    #[test(account = @0x2)]
+    public fun test_increment_auto_inits(account: &signer) acquires Counter {
+        let addr = signer::address_of(account);
+        aptos_framework::account::create_account_for_test(addr);
+
+        // Skip init entirely — increment must create the resource.
+        increment(account);
+        assert!(get(addr) == 1, 0);
+
+        // Idempotent: a second increment uses the now-existing resource.
+        increment(account);
+        assert!(get(addr) == 2, 1);
+    }
 }

package/src/templates/scripts/deploy-counter.ts

@@ -3,7 +3,7 @@ import { Harness } from "movehat";
 async function main() {
   console.log("🚀 Deploying Counter contract...\n");
 
-  // Hardhat-style Harness — primary public API since M2.
+  // Hardhat-style Harness — the primary public API.
   // createLive binds to a real running network (testnet / mainnet / a
   // custom one defined in movehat.config.ts). No local process spawned.
   const network = process.env.MOVEHAT_NETWORK ?? "testnet";
@@ -31,6 +31,16 @@ async function main() {
     // Interact with the freshly deployed module via the runtime helper.
     const counter = harness.runtime.getContract(deployment.address, "counter");
 
+    // Counter is a Move resource — it must be created explicitly per
+    // account before any method that reads or mutates it. The dedicated
+    // `init` entry function does this once per signer. (The module also
+    // auto-inits inside `increment` as defense in depth, so this call is
+    // technically optional today, but kept for pedagogy: real-world Move
+    // modules usually require an explicit init step.)
+    console.log("\n🔧 Initializing counter resource for this account...");
+    const initTx = await counter.call(harness.runtime.account, "init", []);
+    console.log(`   Init tx: ${initTx.hash}`);
+
     console.log("\n📝 Incrementing counter...");
     const txResult = await counter.call(harness.runtime.account, "increment", []);
     console.log(`✅ Transaction hash: ${txResult.hash}`);

package/src/templates/tests/Counter.test.ts

@@ -11,7 +11,7 @@ describe("Counter Contract", () => {
   before(async function () {
     this.timeout(60000); // Allow time for local node startup + deployment
 
-    // Hardhat-style Harness — primary public API since M2.
+    // Hardhat-style Harness — the primary public API.
     // createLocal spins up a Movement local node, funds the labeled
     // accounts from the local faucet, and (via autoDeploy) builds +
     // publishes the named modules so they're ready to use.
@@ -43,7 +43,7 @@ describe("Counter Contract", () => {
       const tx = await counter.call(deployer, "init", []);
       console.log(`   Init transaction: ${tx.hash}`);
 
-      // Read counter value via harness.runViewFunction (new in M2)
+      // Read counter value via harness.runViewFunction
       const [value] = await harness.runViewFunction({
         function: `${counter.moduleAddress}::counter::get`,
         functionArguments: [deployer.accountAddress.toString()],

package/src/types/config.ts

@@ -55,7 +55,14 @@ export interface LocalTestOptions {
     nodeSilent?: boolean;               // Suppress node output (default: false)
 
     // Fork options (when mode='fork')
-    forkNetwork?: 'testnet' | string;   // Network to fork from (default: 'testnet')
+    forkNetwork?: 'testnet' | 'mainnet' | string;   // Network to fork from (default: 'testnet')
+    /**
+     * RPC URL override used when forking a non-built-in network.
+     * Required when `forkNetwork` is not one of the built-in names
+     * (`'testnet'`, `'mainnet'`). Ignored when a fork already exists
+     * on disk (the saved metadata's nodeUrl is reused).
+     */
+    forkRpcUrl?: string;
     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)

package/src/types/runtime.ts

@@ -51,7 +51,7 @@ export interface MovehatRuntime {
   getAccountByIndex: (index: number) => Account;
 
   // 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.
+  // network. There is no module-cached runtime, so callers must capture
+  // and use the returned instance.
   switchNetwork: (networkName: string) => Promise<MovehatRuntime>;
 }

package/src/utils/__tests__/childProcessAdapter.maxBuffer.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { defaultChildProcessAdapter } from "../childProcessAdapter.js";
+
+/**
+ * F4 — `run()` must reject when child output exceeds `maxBuffer`.
+ *
+ * Without this cap, the stdout/stderr Buffer arrays in
+ * DefaultChildProcessAdapter grow without limit. A buggy or hostile
+ * subprocess can OOM the parent process. F4 adds an opt-in byte cap
+ * with kill-on-overflow semantics.
+ */
+
+const NODE = process.execPath;
+
+describe("F4 — ChildProcessAdapter.run maxBuffer", () => {
+  it("rejects with a maxBuffer error when stdout exceeds the cap", async () => {
+    // 8KiB of output, cap at 1KiB → must abort.
+    const script = `process.stdout.write('x'.repeat(8 * 1024)); setTimeout(() => {}, 30000);`;
+    await expect(
+      defaultChildProcessAdapter.run({
+        command: NODE,
+        args: ["-e", script],
+        maxBuffer: 1024,
+        timeoutMs: 10_000,
+      })
+    ).rejects.toThrow(/maxBuffer|exceeded/i);
+  });
+
+  it("rejects with a maxBuffer error when stderr exceeds the cap", async () => {
+    const script = `process.stderr.write('y'.repeat(8 * 1024)); setTimeout(() => {}, 30000);`;
+    await expect(
+      defaultChildProcessAdapter.run({
+        command: NODE,
+        args: ["-e", script],
+        maxBuffer: 1024,
+        timeoutMs: 10_000,
+      })
+    ).rejects.toThrow(/maxBuffer|exceeded/i);
+  });
+
+  it("does NOT throw when output stays under the cap", async () => {
+    const script = `process.stdout.write('ok'); process.exit(0);`;
+    const result = await defaultChildProcessAdapter.run({
+      command: NODE,
+      args: ["-e", script],
+      maxBuffer: 1024,
+    });
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("ok");
+  });
+});

package/src/utils/address.ts

@@ -1,10 +1,6 @@
 /**
  * Address normalization helpers shared across the fork code.
  *
- * Two normalization variants live in production today and are preserved here
- * with identical semantics so the in-place migration in M1.2 is behavior-
- * preserving:
- *
  *   - `normalizeAddress`      → lowercase + `0x` + left-pad to 64 hex chars.
  *                                Used by `fork/manager.ts` for storage keys.
  *   - `normalizeAddressShort` → lowercase + `0x`, no padding.

package/src/utils/childProcessAdapter.ts

@@ -38,8 +38,17 @@ export interface RunInput {
    * Default: `false`.
    */
   inheritStdio?: boolean;
+  /**
+   * Maximum combined bytes (stdout + stderr) the captured Buffers may
+   * grow to before the child is killed and the promise rejects. Defaults
+   * to 64 MiB. Set to `Infinity` to disable. Ignored when
+   * `inheritStdio` is `true` (no buffering happens).
+   */
+  maxBuffer?: number;
 }
 
+const DEFAULT_MAX_BUFFER = 64 * 1024 * 1024;
+
 export interface RunResult {
   /**
    * Numeric exit code from the child. `-1` when the child was terminated by
@@ -99,10 +108,9 @@ class DefaultChildProcessAdapter implements ChildProcessAdapter {
   run(input: RunInput): Promise<RunResult> {
     // Skip the default 5-minute timeout when the caller wires stdio
     // through to the terminal — interactive sessions (mocha, tsx scripts,
-    // `movement move test`, `pnpm install`) routinely exceed 5 minutes and
-    // SIGTERM'ing them silently is a regression vs the direct-spawn code
-    // these callers used before M1.3a. An explicitly-passed `timeoutMs`
-    // is always honored, regardless of `inheritStdio`.
+    // `movement move test`, `pnpm install`) routinely exceed 5 minutes
+    // and SIGTERM'ing them silently would be a regression. An explicit
+    // `timeoutMs` is always honored, regardless of `inheritStdio`.
     const timeoutMs =
       input.timeoutMs ?? (input.inheritStdio ? undefined : DEFAULT_TIMEOUT_MS);
 
@@ -115,10 +123,31 @@ class DefaultChildProcessAdapter implements ChildProcessAdapter {
 
       const stdoutChunks: Buffer[] = [];
       const stderrChunks: Buffer[] = [];
+      let totalBytes = 0;
+      let overflowed = false;
+      const maxBuffer = input.maxBuffer ?? DEFAULT_MAX_BUFFER;
+
+      const onChunk = (chunks: Buffer[]) => (chunk: Buffer) => {
+        if (overflowed) return;
+        totalBytes += chunk.length;
+        if (totalBytes > maxBuffer) {
+          overflowed = true;
+          clearTimer();
+          input.signal?.removeEventListener('abort', onAbort);
+          child.kill('SIGTERM');
+          reject(
+            new Error(
+              `Command output exceeded maxBuffer (${maxBuffer} bytes): ${input.command}`
+            )
+          );
+          return;
+        }
+        chunks.push(chunk);
+      };
 
       // Streams are null when stdio is 'inherit'; the `?.` covers that.
-      child.stdout?.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
-      child.stderr?.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
+      child.stdout?.on('data', onChunk(stdoutChunks));
+      child.stderr?.on('data', onChunk(stderrChunks));
 
       let timeoutHandle: NodeJS.Timeout | undefined;
       const clearTimer = () => {