movehat 0.1.9 → 0.2.0

package/src/harness/Harness.ts

@@ -0,0 +1,228 @@
+import type { MovehatRuntime } from "../types/runtime.js";
+import type { LocalNodeManager } from "../node/LocalNodeManager.js";
+import type { ForkServer } from "../fork/server.js";
+import type { ForkManager } from "../fork/manager.js";
+import type { LocalTestOptions } from "../types/config.js";
+import type {
+  DeployCodeObjectOptions,
+  UpgradeCodeObjectOptions,
+  CodeObjectInfo,
+  RunViewFunctionOptions,
+  RunMoveScriptOptions,
+  MoveScriptResult,
+} from "../types/harness.js";
+import { setupLocalTesting } from "../helpers/setupLocalTesting.js";
+import { initRuntime } from "../runtime.js";
+import { createHarnessProxy } from "./proxy.js";
+import { deployCodeObject, upgradeCodeObject } from "./codeObject.js";
+import { runViewFunction } from "./view.js";
+import { runMoveScript } from "./script.js";
+
+export type HarnessMode = "local" | "fork" | "live";
+
+interface HarnessInit {
+  mode: HarnessMode;
+  runtime: MovehatRuntime;
+  localNode?: LocalNodeManager;
+  forkServer?: ForkServer;
+  forkManager?: ForkManager;
+}
+
+/**
+ * Hardhat-style testing harness for Movehat.
+ *
+ * Construct via the static factories — `createLocal`, `createFork`,
+ * `createLive` — never via `new Harness(...)`. The returned instance is
+ * a Proxy that synchronously throws {@link HarnessDisposedError} on any
+ * post-`cleanup()` call to one of the deployment / script / view methods.
+ *
+ * Methods `deployCodeObject`, `upgradeCodeObject`, `runViewFunction`,
+ * and `runMoveScript` are stubbed in M2.1 — they throw at runtime until
+ * M2.2/M2.3 lands. The type surface is complete so callers and docs can
+ * be written against it ahead of time.
+ *
+ * AccountManager note: as of M2.1 the underlying account pool is a
+ * process-wide static (see `core/AccountManager.ts`). Two Harness
+ * instances in the same process share account labels; this is the same
+ * constraint that already governs `setupTestFixture`. A per-Harness pool
+ * is a future change.
+ */
+export class Harness {
+  public readonly mode: HarnessMode;
+  public readonly runtime: MovehatRuntime;
+
+  /** @internal */
+  public readonly localNode?: LocalNodeManager;
+  /** @internal */
+  public readonly forkServer?: ForkServer;
+  /** @internal */
+  public readonly forkManager?: ForkManager;
+
+  private _poisoned = false;
+
+  private constructor(init: HarnessInit) {
+    this.mode = init.mode;
+    this.runtime = init.runtime;
+    if (init.localNode) this.localNode = init.localNode;
+    if (init.forkServer) this.forkServer = init.forkServer;
+    if (init.forkManager) this.forkManager = init.forkManager;
+  }
+
+  /** True once `cleanup()` has been awaited at least once. */
+  public get poisoned(): boolean {
+    return this._poisoned;
+  }
+
+  /**
+   * Spin up a local Movement node and return a Harness bound to it.
+   *
+   * Forwards to `setupLocalTesting({ mode: 'local-node', ... })` so all
+   * existing options (`nodeApiPort`, `accountLabels`, `autoDeploy`, ...)
+   * apply unchanged.
+   */
+  static async createLocal(options: LocalTestOptions = {}): Promise<Harness> {
+    const ctx = await setupLocalTesting({ ...options, mode: "local-node" });
+    const init: HarnessInit = {
+      mode: "local",
+      runtime: ctx.runtime,
+    };
+    if (ctx.localNode) init.localNode = ctx.localNode;
+    const instance = new Harness(init);
+    return createHarnessProxy(instance, () => instance._poisoned);
+  }
+
+  /**
+   * Create a fork-mode Harness reading from a snapshot of `network`.
+   *
+   * Fork mode is read-only: `deployCodeObject`, `upgradeCodeObject`,
+   * and `runMoveScript` throw with a message pointing at `createLocal`.
+   * `runViewFunction` works (read-only path).
+   *
+   * @param network - Network to fork (e.g. `"testnet"`).
+   * @param apiKey - Optional Movement API key. When set, every upstream
+   *   request from the fork's `MovementApiClient` carries
+   *   `Authorization: Bearer <apiKey>`. Use for rate-limited public
+   *   endpoints or auth-gated nodes. The key stays in process memory
+   *   (not persisted to the fork's on-disk metadata).
+   */
+  static async createFork(network: string, apiKey?: string): Promise<Harness> {
+    const setupOpts: import("../types/config.js").LocalTestOptions = {
+      mode: "fork",
+      forkNetwork: network,
+    };
+    if (apiKey !== undefined) setupOpts.forkApiKey = apiKey;
+    const ctx = await setupLocalTesting(setupOpts);
+    const init: HarnessInit = {
+      mode: "fork",
+      runtime: ctx.runtime,
+    };
+    if (ctx.forkServer) init.forkServer = ctx.forkServer;
+    if (ctx.forkManager) init.forkManager = ctx.forkManager;
+    const instance = new Harness(init);
+    return createHarnessProxy(instance, () => instance._poisoned);
+  }
+
+  /**
+   * Bind a Harness to a real running network (testnet, mainnet, or any
+   * custom network defined in `movehat.config.ts`). No local process is
+   * spawned; transactions are submitted to the configured RPC.
+   *
+   * @param network - Named network from movehat.config.ts.
+   * @param _faucetUrl - Reserved for M2.2 (auto-fund on networks with a faucet).
+   */
+  static async createLive(network: string, _faucetUrl?: string): Promise<Harness> {
+    const runtime = await initRuntime({ network });
+    const instance = new Harness({ mode: "live", runtime });
+    return createHarnessProxy(instance, () => instance._poisoned);
+  }
+
+  /**
+   * Release resources owned by this harness (local node or fork server)
+   * and poison it. Idempotent: subsequent calls are no-ops.
+   *
+   * After `cleanup()` resolves, any call to `deployCodeObject`,
+   * `upgradeCodeObject`, `runViewFunction`, or `runMoveScript` throws
+   * `HarnessDisposedError` synchronously on property access.
+   */
+  async cleanup(): Promise<void> {
+    if (this._poisoned) return;
+    this._poisoned = true;
+    if (this.localNode) {
+      await this.localNode.stop().catch(() => {});
+    }
+    if (this.forkServer) {
+      await this.forkServer.stop().catch(() => {});
+    }
+  }
+
+  /**
+   * Deploy a Move package as a code object via `movement move deploy-object`.
+   *
+   * The derived object address is bound to `options.moduleName` as a
+   * named address at compile time, then captured into the returned
+   * {@link CodeObjectInfo.address} for later use with
+   * `harness.runtime.getContract(address, moduleName)`.
+   *
+   * Not available on fork-mode harnesses (forks are read-only). Calling
+   * this on a `Harness.createFork(...)` instance throws synchronously.
+   */
+  async deployCodeObject(options: DeployCodeObjectOptions): Promise<CodeObjectInfo> {
+    if (this.mode === "fork") {
+      throw new Error(
+        "Harness.createFork is read-only; code-object deployment requires Harness.createLocal or createLive."
+      );
+    }
+    return deployCodeObject(this.runtime, options);
+  }
+
+  /**
+   * Upgrade an existing code object via `movement move upgrade-object`.
+   *
+   * Requires {@link UpgradeCodeObjectOptions.objectAddress} (the existing
+   * on-chain object). Overwrites the local deployment record's timestamp
+   * + txHash; address stays the same.
+   *
+   * Not available on fork-mode harnesses (forks are read-only).
+   */
+  async upgradeCodeObject(
+    options: UpgradeCodeObjectOptions
+  ): Promise<CodeObjectInfo> {
+    if (this.mode === "fork") {
+      throw new Error(
+        "Harness.createFork is read-only; code-object upgrade requires Harness.createLocal or createLive."
+      );
+    }
+    return upgradeCodeObject(this.runtime, options);
+  }
+
+  /**
+   * Execute a Move view function via the Aptos SDK.
+   *
+   * Returns the raw view-function result array. For single-value
+   * returns, destructure: `const [count] = await harness.runViewFunction(...)`.
+   *
+   * Works on all 3 harness modes (createLocal, createFork, createLive)
+   * — view functions are read-only.
+   */
+  async runViewFunction(options: RunViewFunctionOptions): Promise<unknown[]> {
+    return runViewFunction(this.runtime, options);
+  }
+
+  /**
+   * Execute a Move script via `movement move run-script`.
+   *
+   * Accepts either a `.move` source path (CLI auto-compiles) or a
+   * pre-compiled `.mv` bytecode path. Other extensions throw
+   * synchronously.
+   *
+   * Not available on fork-mode harnesses (forks are read-only).
+   */
+  async runMoveScript(options: RunMoveScriptOptions): Promise<MoveScriptResult> {
+    if (this.mode === "fork") {
+      throw new Error(
+        "Harness.createFork is read-only; script execution requires Harness.createLocal or createLive."
+      );
+    }
+    return runMoveScript(this.runtime, options);
+  }
+}

package/src/harness/codeObject.ts

@@ -0,0 +1,388 @@
+import { homedir } from "os";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import type { MovehatRuntime } from "../types/runtime.js";
+import type {
+  DeployCodeObjectOptions,
+  UpgradeCodeObjectOptions,
+  CodeObjectInfo,
+} from "../types/harness.js";
+import { extractNamedAddresses } from "../commands/compile.js";
+import {
+  saveDeployment,
+  loadDeployment,
+  validateSafeName,
+  type DeploymentInfo,
+} from "../core/deployments.js";
+import { validatePathSafety, validateProfileSafety } from "../core/shell.js";
+import {
+  CliExecutionError,
+  ModuleAlreadyDeployedError,
+  PostPublishError,
+} from "../errors.js";
+import { runCli } from "../utils/runCli.js";
+import { parseTxHash } from "../utils/parseCliOutput.js";
+import { logger } from "../ui/index.js";
+import {
+  withYamlLock,
+  addProfile,
+  removeProfile,
+  removeProfileSync,
+  ensureSignalHandler,
+  cleanupCallbacks,
+} from "../core/movementProfile.js";
+
+/**
+ * Deploy a Move package as a code object via `movement move deploy-object`.
+ *
+ * Mirrors `core/Publisher.deploy` exactly for the security-critical parts
+ * (per-deploy unique profile, atomic ~/.aptos/config.yaml mutation under
+ * the shared mutex, SIGINT-safe sync cleanup, stderr redaction via
+ * `runCli`). The only differences are:
+ *
+ *   1. CLI subcommand: `deploy-object` instead of `publish` + a required
+ *      `--address-name <moduleName>` flag that binds the derived object
+ *      address to the package's named-address slot.
+ *   2. `DeploymentInfo.address` is the derived **object address** parsed
+ *      from CLI output, not the deployer's account address.
+ *
+ * @internal — called from `Harness.deployCodeObject`.
+ */
+export async function deployCodeObject(
+  runtime: MovehatRuntime,
+  options: DeployCodeObjectOptions
+): Promise<CodeObjectInfo> {
+  return executeMovementMoveObject({
+    runtime,
+    moduleName: options.moduleName,
+    addressName: options.addressName,
+    packageDir: options.packageDir,
+    namedAddresses: options.namedAddresses,
+    includedArtifacts: options.includedArtifacts,
+    adapter: options.adapter,
+    subcommand: "deploy-object",
+    extraArgs: [],
+    checkIdempotency: true,
+  });
+}
+
+/**
+ * Upgrade an existing code object via `movement move upgrade-object`.
+ *
+ * Requires {@link UpgradeCodeObjectOptions.objectAddress} — the address
+ * of the existing on-chain object. The local `DeploymentInfo` record
+ * for `moduleName` is overwritten with a new timestamp + txHash; the
+ * address stays the same.
+ *
+ * @internal — called from `Harness.upgradeCodeObject`.
+ */
+export async function upgradeCodeObject(
+  runtime: MovehatRuntime,
+  options: UpgradeCodeObjectOptions
+): Promise<CodeObjectInfo> {
+  if (!options.objectAddress) {
+    throw new Error(
+      "Harness.upgradeCodeObject requires options.objectAddress (the existing object's address)."
+    );
+  }
+  return executeMovementMoveObject({
+    runtime,
+    moduleName: options.moduleName,
+    addressName: options.addressName,
+    packageDir: options.packageDir,
+    namedAddresses: options.namedAddresses,
+    includedArtifacts: options.includedArtifacts,
+    adapter: options.adapter,
+    subcommand: "upgrade-object",
+    extraArgs: ["--object-address", options.objectAddress],
+    checkIdempotency: false,
+    fixedAddress: options.objectAddress,
+  });
+}
+
+interface ExecuteOptions {
+  runtime: MovehatRuntime;
+  moduleName: string;
+  /**
+   * Move.toml named address for the `--address-name` CLI flag.
+   * Defaults to `moduleName` when undefined.
+   */
+  addressName?: string | undefined;
+  packageDir?: string | undefined;
+  namedAddresses?: Record<string, string> | undefined;
+  includedArtifacts?: "none" | "sparse" | "all" | undefined;
+  adapter?: import("../utils/childProcessAdapter.js").ChildProcessAdapter | undefined;
+  subcommand: "deploy-object" | "upgrade-object";
+  extraArgs: readonly string[];
+  /** Whether to throw `ModuleAlreadyDeployedError` if a record exists. */
+  checkIdempotency: boolean;
+  /**
+   * For upgrade-object: the object's existing address. Skips the parse-
+   * from-stdout step (the address is known up front).
+   */
+  fixedAddress?: string;
+}
+
+async function executeMovementMoveObject(
+  opts: ExecuteOptions
+): Promise<CodeObjectInfo> {
+  const { runtime, moduleName, subcommand } = opts;
+  const config = runtime.config;
+  const account = runtime.account;
+
+  validateSafeName(moduleName, "module");
+
+  // Idempotency: deploy-object refuses re-deploy unless MH_CLI_REDEPLOY=true.
+  // Upgrade does not check this (the whole point is to overwrite).
+  const forceRedeploy = process.env.MH_CLI_REDEPLOY === "true";
+  if (opts.checkIdempotency) {
+    const existing = loadDeployment(config.network, moduleName);
+    if (existing && !forceRedeploy) {
+      const errorDetails = [
+        `Module "${moduleName}" is already deployed on ${config.network}`,
+        `Address: ${existing.address}`,
+        `Deployed at: ${new Date(existing.timestamp).toLocaleString()}`,
+        existing.txHash ? `Transaction: ${existing.txHash}` : null,
+        `\nTo redeploy, set MH_CLI_REDEPLOY=true or call harness.upgradeCodeObject({ objectAddress: "${existing.address}", ... }).`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+
+      logger.error(
+        `Module "${moduleName}" is already deployed on ${config.network}`
+      );
+      logger.plain(`   Address: ${existing.address}`);
+      logger.plain(
+        `   Deployed at: ${new Date(existing.timestamp).toLocaleString()}`
+      );
+      if (existing.txHash) logger.plain(`   Transaction: ${existing.txHash}`);
+      logger.newline();
+
+      throw new ModuleAlreadyDeployedError(
+        errorDetails,
+        moduleName,
+        config.network,
+        existing.address,
+        existing.timestamp,
+        existing.txHash
+      );
+    }
+  }
+
+  const dir = opts.packageDir || config.moveDir;
+  const profile = `movehat-deploy-${randomUUID().slice(0, 8)}`;
+  const safeDir = validatePathSafety(dir, "package directory");
+  const safeProfile = validateProfileSafety(profile);
+
+  logger.step(
+    `${subcommand === "deploy-object" ? "Deploying" : "Upgrading"} module "${moduleName}" from ${dir}...`
+  );
+
+  try {
+    const deployerAddress = account.accountAddress.toString();
+
+    // Build named-addresses arg: auto-detected names from Move sources
+    // are bound to the deployer's address (Publisher convention).
+    // Caller-supplied `namedAddresses` overlay on top.
+    const detectedAddresses = extractNamedAddresses(dir);
+    const addrMap = new Map<string, string>();
+    for (const name of detectedAddresses) addrMap.set(name, deployerAddress);
+    if (opts.namedAddresses) {
+      for (const [k, v] of Object.entries(opts.namedAddresses)) addrMap.set(k, v);
+    }
+    const namedAddrArgs: string[] =
+      addrMap.size > 0
+        ? [
+            "--named-addresses",
+            Array.from(addrMap.entries())
+              .map(([k, v]) => `${k}=${v}`)
+              .join(","),
+          ]
+        : [];
+
+    // Build step (same as Publisher — produces the bytecode the
+    // subcommand will publish/upgrade).
+    logger.step("Building package...");
+    const buildResult = await runCli(
+      {
+        command: "movement",
+        args: ["move", "build", "--package-dir", safeDir, ...namedAddrArgs],
+        timeoutMs: 120000,
+      },
+      { adapter: opts.adapter }
+    );
+    if (buildResult.stdout) console.log(buildResult.stdout.trim());
+
+    // Strip `ed25519-priv-` prefix if present — Movement CLI expects the
+    // raw hex.
+    let cleanPrivateKey = config.privateKey;
+    if (cleanPrivateKey.startsWith("ed25519-priv-")) {
+      cleanPrivateKey = cleanPrivateKey.replace("ed25519-priv-", "");
+    }
+
+    const movementConfigPath = join(homedir(), ".aptos", "config.yaml");
+
+    // Register SIGINT-safe sync cleanup BEFORE writing the key (same
+    // pattern as Publisher — closes bug #36).
+    ensureSignalHandler();
+    const syncCleanup = () => removeProfileSync(movementConfigPath, profile);
+    cleanupCallbacks.add(syncCleanup);
+
+    await withYamlLock(() =>
+      addProfile(movementConfigPath, profile, {
+        private_key: cleanPrivateKey,
+        public_key: account.publicKey.toString(),
+        account: deployerAddress,
+        rest_url: config.rpc,
+      })
+    );
+
+    let deployOut = "";
+    try {
+      logger.step(
+        `Running 'movement move ${subcommand}'${subcommand === "upgrade-object" ? "" : " (this may take a moment)"}...`
+      );
+      const includedArtifacts: ("--included-artifacts" | string)[] =
+        opts.includedArtifacts
+          ? ["--included-artifacts", opts.includedArtifacts]
+          : [];
+      const result = await runCli(
+        {
+          command: "movement",
+          args: [
+            "move",
+            subcommand,
+            "--address-name",
+            opts.addressName ?? moduleName,
+            "--package-dir",
+            safeDir,
+            "--url",
+            config.rpc,
+            "--profile",
+            safeProfile,
+            "--assume-yes",
+            ...includedArtifacts,
+            ...namedAddrArgs,
+            ...opts.extraArgs,
+          ],
+          timeoutMs: 180000, // 3 min — deploy-object can be slow with chunked publishing.
+        },
+        { adapter: opts.adapter }
+      );
+      deployOut = result.stdout;
+      if (result.stdout) console.log(result.stdout.trim());
+      if (result.stderr) console.error(result.stderr.trim());
+    } finally {
+      // Best-effort profile removal. CRITICAL: catch + log instead of
+      // re-throwing — an await-in-finally that throws would clobber the
+      // try block's success/error (the bug-#37 lesson from Publisher).
+      await withYamlLock(() => removeProfile(movementConfigPath, profile)).catch(
+        (err) => {
+          const cleanupMsg = err instanceof Error ? err.message : String(err);
+          logger.warning(
+            `Failed to remove deploy profile "${profile}" from ${movementConfigPath}: ${cleanupMsg}. ` +
+              `Run 'movement config delete-profile --profile ${profile}' to clean up manually.`
+          );
+        }
+      );
+      cleanupCallbacks.delete(syncCleanup);
+    }
+
+    // Parse object address (for deploy-object) and txHash (both flows).
+    // No captured fixture exists at M2.2 commit time; M4 integration
+    // tests validate against real CLI output.
+    const objectAddress = opts.fixedAddress ?? parseObjectAddress(deployOut);
+    const txHash = parseTxHash(deployOut);
+
+    if (!objectAddress) {
+      throw new Error(
+        `Could not parse object address from '${subcommand}' output. ` +
+          `Expected a line containing 'object address 0x...' or a JSON ` +
+          `'Result' block with an 'object_address' field. Captured stdout:\n${deployOut.slice(0, 1000)}`
+      );
+    }
+
+    logger.success(
+      `${subcommand === "deploy-object" ? "Module deployed" : "Module upgraded"} successfully!`
+    );
+
+    // Publish/upgrade succeeded. Everything below this point that throws
+    // is a local-side bookkeeping failure, not an on-chain failure.
+
+    const deployment: DeploymentInfo = {
+      address: objectAddress,
+      moduleName,
+      network: config.network,
+      deployer: deployerAddress,
+      timestamp: Date.now(),
+      ...(txHash !== undefined ? { txHash } : {}),
+    };
+
+    try {
+      saveDeployment(deployment);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      throw new PostPublishError(
+        `Module "${moduleName}" ${subcommand === "deploy-object" ? "deployed" : "upgraded"} to ${deployment.address} ` +
+          `but local deployment record could not be written: ${err.message}`,
+        deployment,
+        err
+      );
+    }
+
+    return deployment;
+  } catch (error) {
+    if (error instanceof PostPublishError) {
+      logger.warning(
+        `Module ${subcommand === "deploy-object" ? "deployed" : "upgraded"} successfully to ${error.deployment.address} ` +
+          `(tx=${error.deployment.txHash ?? "unknown"}) but local deployment record could not be written.`
+      );
+      logger.warning(`   Cause: ${error.cause.message}`);
+      logger.warning(
+        `   To recover, manually write the deployment to deployments/${error.deployment.network}/${error.deployment.moduleName}.json.`
+      );
+      throw error;
+    }
+    if (error instanceof CliExecutionError) {
+      if (error.stdoutPreview) console.log(error.stdoutPreview);
+      logger.error(
+        `Failed to ${subcommand === "deploy-object" ? "deploy" : "upgrade"} module: ${error.message}\n${error.stderr}`
+      );
+    } else {
+      const err = error instanceof Error ? error : new Error(String(error));
+      logger.error(
+        `Failed to ${subcommand === "deploy-object" ? "deploy" : "upgrade"} module: ${err.message}`
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Extract a code-object address from `movement move deploy-object` stdout.
+ *
+ * Movement CLI typically emits the address in one of these shapes (none
+ * of them captured at M2.2 commit time — patterns are speculative, with
+ * M4 integration tests as the validation gate):
+ *
+ *   - Free text: `Code was successfully deployed to object address 0x…`
+ *   - Free text: `Object address: 0x…`
+ *   - JSON `Result` block with `"object_address": "0x…"`
+ *
+ * Falls through the patterns in order. Returns `undefined` on no match.
+ */
+function parseObjectAddress(stdout: string): string | undefined {
+  // Pattern 1: phrase-context match.
+  const phraseMatch = stdout.match(
+    /object\s+address[:\s]+\b(0x[a-fA-F0-9]{1,64})\b/i
+  );
+  if (phraseMatch?.[1]) return phraseMatch[1];
+
+  // Pattern 2: JSON-shaped key.
+  const jsonMatch = stdout.match(
+    /"object_address"\s*:\s*"(0x[a-fA-F0-9]{1,64})"/
+  );
+  if (jsonMatch?.[1]) return jsonMatch[1];
+
+  return undefined;
+}

package/src/harness/errors.ts

@@ -0,0 +1,22 @@
+/**
+ * Thrown synchronously when any method other than `cleanup` is invoked
+ * on a Harness instance whose `cleanup()` has already run.
+ *
+ * The throw happens on property access (Proxy `get` trap), not after the
+ * async method body. That means `await harness.deployCodeObject(...)`
+ * throws *before* the call site awaits — callers can use a plain
+ * `try`/`catch` or rely on the rejected promise; either form will fire.
+ */
+export class HarnessDisposedError extends Error {
+  constructor(public readonly methodName: string) {
+    super(
+      `Harness is disposed; call to '${methodName}' is not allowed. ` +
+        `Create a new Harness via Harness.createLocal/createFork/createLive instead.`
+    );
+    this.name = "HarnessDisposedError";
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, HarnessDisposedError);
+    }
+  }
+}

package/src/harness/index.ts

@@ -0,0 +1,3 @@
+export { Harness } from "./Harness.js";
+export type { HarnessMode } from "./Harness.js";
+export { HarnessDisposedError } from "./errors.js";

package/src/harness/proxy.ts

@@ -0,0 +1,40 @@
+import { HarnessDisposedError } from "./errors.js";
+
+/**
+ * Names of Harness methods that must throw `HarnessDisposedError`
+ * synchronously once the harness has been disposed (via `cleanup()`).
+ *
+ * Properties NOT in this set — `cleanup`, `mode`, `poisoned`, the runtime
+ * accessors, well-known Symbols, and the promise-protocol hooks
+ * (`then`/`catch`/`finally`) — always pass through. That keeps:
+ *  - `await harness` from breaking on `.then` access
+ *  - debug tools (`console.log`, `util.inspect`) from throwing
+ *  - idempotent `cleanup()` callable post-poisoning
+ *
+ * New Harness methods that should fail post-cleanup MUST be added here.
+ */
+const POISONED_METHODS: ReadonlySet<string> = new Set([
+  "deployCodeObject",
+  "upgradeCodeObject",
+  "runViewFunction",
+  "runMoveScript",
+]);
+
+/**
+ * Wrap a Harness instance in a Proxy that throws `HarnessDisposedError`
+ * synchronously on access to any method in {@link POISONED_METHODS} once
+ * `isPoisoned()` returns true.
+ */
+export function createHarnessProxy<T extends object>(
+  target: T,
+  isPoisoned: () => boolean
+): T {
+  return new Proxy(target, {
+    get(obj, prop, receiver) {
+      if (typeof prop === "string" && POISONED_METHODS.has(prop) && isPoisoned()) {
+        throw new HarnessDisposedError(prop);
+      }
+      return Reflect.get(obj, prop, receiver);
+    },
+  });
+}