movehat 0.2.5 → 0.2.7

package/dist/commands/run.d.ts

@@ -1,4 +1,21 @@
 import type { RunResult } from "../utils/childProcessAdapter.js";
+/**
+ * Resolve the tsx CLI entrypoint (`<tsx-pkg>/dist/cli.mjs`) used by
+ * `movehat run` to execute user scripts. Prefers movehat's bundled tsx
+ * by default; falls back to the cwd's tsx only if bundled is missing
+ * (defensive — should not happen for normal installs). Set
+ * `MOVEHAT_TSX_FROM_CWD=1` or pass `preferCwd: true` to flip the
+ * order — power-users who pinned a different tsx in their project.
+ *
+ * Security: the default order closes #52 (untrusted cwd could ship a
+ * malicious `node_modules/tsx/dist/cli.mjs`).
+ *
+ * Exported so the resolution logic can be unit-tested without
+ * spawning a real process.
+ */
+export declare function resolveTsxCliPath(opts?: {
+    preferCwd?: boolean;
+}): string | null;
 /**
  * Apply the exit policy for a child whose output was inherited by the
  * parent. When the child dies via signal, re-raise it on the parent so

package/dist/commands/run.js

@@ -4,6 +4,45 @@ import { fileURLToPath } from "url";
 import { createRequire } from "module";
 import { runCli } from "../utils/runCli.js";
 import { logger } from "../ui/index.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const requireFromHere = createRequire(import.meta.url);
+/**
+ * Resolve the tsx CLI entrypoint (`<tsx-pkg>/dist/cli.mjs`) used by
+ * `movehat run` to execute user scripts. Prefers movehat's bundled tsx
+ * by default; falls back to the cwd's tsx only if bundled is missing
+ * (defensive — should not happen for normal installs). Set
+ * `MOVEHAT_TSX_FROM_CWD=1` or pass `preferCwd: true` to flip the
+ * order — power-users who pinned a different tsx in their project.
+ *
+ * Security: the default order closes #52 (untrusted cwd could ship a
+ * malicious `node_modules/tsx/dist/cli.mjs`).
+ *
+ * Exported so the resolution logic can be unit-tested without
+ * spawning a real process.
+ */
+export function resolveTsxCliPath(opts) {
+    const preferCwd = opts?.preferCwd ?? process.env.MOVEHAT_TSX_FROM_CWD === "1";
+    const bundledRoot = __dirname;
+    const cwdRoot = process.cwd();
+    const lookupOrder = preferCwd
+        ? [cwdRoot, bundledRoot]
+        : [bundledRoot, cwdRoot];
+    for (const root of lookupOrder) {
+        try {
+            const tsxEntry = requireFromHere.resolve("tsx", { paths: [root] });
+            // require.resolve("tsx") returns .../tsx/dist/loader.mjs; walk up
+            // to the package root and into dist/cli.mjs.
+            const packageRoot = dirname(dirname(tsxEntry));
+            const cliPath = join(packageRoot, "dist", "cli.mjs");
+            if (existsSync(cliPath))
+                return cliPath;
+        }
+        catch {
+            // Lookup failed at this root; try the next one.
+        }
+    }
+    return null;
+}
 /**
  * Apply the exit policy for a child whose output was inherited by the
  * parent. When the child dies via signal, re-raise it on the parent so
@@ -50,39 +89,14 @@ export default async function runCommand(scriptPath) {
         logger.plain(`   Network: ${network}`);
     }
     logger.newline();
-    // Find tsx binary - try multiple locations for compatibility
-    // Uses require.resolve for cross-platform compatibility (works on Windows, macOS, Linux)
-    const __filename = fileURLToPath(import.meta.url);
-    const __dirname = dirname(__filename);
-    // Create require function for ESM (needed to use require.resolve in ESM modules)
-    const require = createRequire(import.meta.url);
-    let tsxPath;
-    try {
-        // Try to resolve tsx package from user's project first
-        const tsxPackagePath = require.resolve("tsx", { paths: [process.cwd()] });
-        // require.resolve("tsx") returns .../tsx/dist/loader.mjs
-        // We need to go up to the tsx package root, then into dist/cli.mjs
-        const tsxPackageRoot = dirname(dirname(tsxPackagePath));
-        tsxPath = join(tsxPackageRoot, "dist", "cli.mjs");
-        // Verify the file exists
-        if (!existsSync(tsxPath)) {
-            throw new Error("cli.mjs not found");
-        }
-    }
-    catch {
-        try {
-            // Fallback to movehat's own tsx
-            const tsxPackagePath = require.resolve("tsx", { paths: [__dirname] });
-            const tsxPackageRoot = dirname(dirname(tsxPackagePath));
-            tsxPath = join(tsxPackageRoot, "dist", "cli.mjs");
-            if (!existsSync(tsxPath)) {
-                throw new Error("cli.mjs not found");
-            }
-        }
-        catch {
-            tsxPath = "";
-        }
+    // Find tsx binary — bundled-first per #52 (supply-chain hardening).
+    // Cwd resolution stays available behind an opt-in env var for users
+    // who pinned a different tsx in their project.
+    if (process.env.MOVEHAT_TSX_FROM_CWD === "1") {
+        logger.warning("MOVEHAT_TSX_FROM_CWD=1: resolving tsx from cwd first. " +
+            "Only use this in trusted project directories.");
     }
+    const tsxPath = resolveTsxCliPath();
     if (!tsxPath) {
         logger.error("tsx binary not found");
         logger.plain("   Make sure 'tsx' is installed in your project:");

package/dist/core/AccountManager.d.ts

@@ -14,183 +14,165 @@ export interface SaveAccountPoolOptions {
      */
     includeImported?: boolean | undefined;
 }
+export interface AccountManagerOptions {
+    /**
+     * Filesystem location where `saveAccountPool` writes `test-pool.json`
+     * and `loadAccountPool` reads from. When omitted, the path is computed
+     * LAZILY on each call from `join(process.cwd(), ".movehat", "accounts")`
+     * — so `process.chdir()` between construction and pool I/O is respected.
+     *
+     * Pass an explicit value when per-instance isolation matters (parallel
+     * test files, harness pools that must not collide with another suite's).
+     *
+     * The process-wide static facade exposed on the `AccountManager` class
+     * itself uses a separate singleton whose `poolPath` is EAGERLY captured
+     * at module-import time. That preserves the legacy F8(b) behavior for
+     * any code still on the static API during the 0.2.7 deprecation window;
+     * the static facade is removed in 0.3.0.
+     */
+    poolPath?: string | undefined;
+}
 /**
  * Centralized Account Manager for movehat
  *
  * Manages all account creation, loading, and lifecycle operations.
- * Provides a pool of reusable test accounts with labels for better test readability.
+ * Provides a pool of reusable test accounts with labels for better test
+ * readability.
+ *
+ * Two API surfaces are exposed:
+ *
+ * **Instance API (recommended; M9.1+)** — `new AccountManager(options?)`
+ * gives a fully isolated pool. Two instances in the same process have
+ * independent labelMaps, private-key maps, and account pools. Each
+ * `Harness` constructed in 0.3.0+ will own one of these; user code
+ * accesses labeled accounts via `harness.accounts.<label>` (Harness
+ * snapshots them at construction time).
+ *
+ * **Static facade (deprecated; will be removed in 0.3.0)** — every
+ * former static method (`AccountManager.createAccount(...)`, etc.) still
+ * works and forwards to a single process-wide singleton. This preserves
+ * the existing label-sharing behavior across calls during the
+ * deprecation window. Migration target is the instance API; see M9 meta
+ * (#270) and migration guide at `/docs/upgrading/0.3.0` (published in
+ * M9.4).
  */
 export declare class AccountManager {
-    private static pool;
-    private static privateKeys;
-    private static labelMap;
-    private static generatedAccountAddresses;
-    private static poolLoaded;
-    private static defaultPoolPath;
-    /**
-     * Get a test account from the pool. If label is provided and exists, returns that account.
-     * Otherwise creates a new account with the optional label.
-     *
-     * @param label Optional label for the account (e.g., "alice", "bob", "deployer")
+    private readonly pool;
+    private readonly privateKeys;
+    private readonly labelMap;
+    private readonly generatedAccountAddresses;
+    private poolLoaded;
+    private readonly poolPathOverride;
+    constructor(options?: AccountManagerOptions);
+    /**
+     * Resolved pool directory. When the caller supplied an explicit
+     * `poolPath` to the constructor, that value is returned verbatim.
+     * Otherwise the path is computed LAZILY from the current
+     * `process.cwd()` on each access — so `process.chdir()` performed
+     * between construction and pool I/O takes effect, unlike the legacy
+     * static-only API which captured cwd at module import time
+     * (audit finding F8(b)).
+     */
+    private get poolPath();
+    /**
+     * Get a test account from the pool. If label is provided and exists,
+     * returns that account. Otherwise creates a new account with the
+     * optional label.
+     *
+     * @param label Optional label for the account (e.g., "alice", "bob")
      * @returns An Account instance
-     *
-     * @example
-     * const alice = AccountManager.getTestAccount("alice");
-     * const randomAccount = AccountManager.getTestAccount();
      */
-    static getTestAccount(label?: string): Account;
+    getTestAccount(label?: string): Account;
     /**
-     * Create a new account and optionally add it to the pool with a label
-     *
-     * @param label Optional label for the account
-     * @param fund Whether to fund the account (handled externally)
-     * @returns A new Account instance
-     *
-     * @example
-     * const deployer = AccountManager.createAccount("deployer");
-     * const bob = AccountManager.createAccount("bob", true);
+     * Create a new account and optionally add it to the pool with a
+     * label. The `fund` parameter is accepted for API symmetry; actual
+     * funding is the caller's responsibility.
      */
-    static createAccount(label?: string, fund?: boolean): Account;
+    createAccount(label?: string, _fund?: boolean): Account;
     /**
-     * Get an account by its label
-     *
-     * @param label The label to look up
-     * @returns The Account if found, undefined otherwise
-     *
-     * @example
-     * const alice = AccountManager.getAccountByLabel("alice");
-     * if (alice) {
-     *   console.log(`Alice's address: ${alice.accountAddress.toString()}`);
-     * }
+     * Get an account by its label, or undefined if not present.
      */
-    static getAccountByLabel(label: string): Account | undefined;
+    getAccountByLabel(label: string): Account | undefined;
     /**
-     * Load account from environment variable
-     *
-     * @param envVar The environment variable name (defaults to "PRIVATE_KEY")
-     * @returns Account instance
-     * @throws Error if environment variable is not set
+     * Load account from environment variable.
      *
-     * @example
-     * const account = AccountManager.loadAccountFromEnv("MH_PRIVATE_KEY");
+     * @throws Error if the environment variable is not set
      */
-    static loadAccountFromEnv(envVar?: string): Account;
+    loadAccountFromEnv(envVar?: string): Account;
     /**
-     * Load account from a private key hex string
-     *
-     * @param privateKeyHex The private key as a hex string (with or without 0x prefix)
-     * @returns Account instance
-     *
-     * @example
-     * const account = AccountManager.loadAccountFromPrivateKey("0xabc123...");
+     * Load account from a private key hex string (with or without 0x prefix).
      */
-    static loadAccountFromPrivateKey(privateKeyHex: string): Account;
+    loadAccountFromPrivateKey(privateKeyHex: string): Account;
     /**
-     * Load all accounts from movehat config
-     *
-     * @param config The resolved MovehatConfig
-     * @returns Array of Account instances
-     *
-     * @example
-     * const config = await resolveNetworkConfig(userConfig);
-     * const accounts = AccountManager.loadAccountsFromConfig(config);
+     * Load all accounts from movehat config.
      */
-    static loadAccountsFromConfig(config: MovehatConfig): Account[];
+    loadAccountsFromConfig(config: MovehatConfig): Account[];
     /**
-     * Get all labeled accounts in the pool
-     *
-     * @returns Record of label to Account mappings
-     *
-     * @example
-     * const labeled = AccountManager.getLabeledAccounts();
-     * console.log(`Deployer: ${labeled.deployer?.accountAddress.toString()}`);
+     * Get all labeled accounts in the pool.
      */
-    static getLabeledAccounts(): Record<string, Account>;
+    getLabeledAccounts(): Record<string, Account>;
     /**
-     * Save the current account pool to disk for persistence
-     *
-     * @param poolPath Optional custom path (defaults to .movehat/accounts)
-     *
-     * @example
-     * AccountManager.saveAccountPool();
+     * Save the current account pool to disk for persistence.
      */
-    static saveAccountPool(): void;
-    static saveAccountPool(poolPath: string): void;
-    static saveAccountPool(options: SaveAccountPoolOptions): void;
-    static saveAccountPool(poolPath: string, options: SaveAccountPoolOptions): void;
+    saveAccountPool(): void;
+    saveAccountPool(poolPath: string): void;
+    saveAccountPool(options: SaveAccountPoolOptions): void;
+    saveAccountPool(poolPath: string, options: SaveAccountPoolOptions): void;
     /**
-     * Load account pool from disk
-     *
-     * @param poolPath Optional custom path (defaults to .movehat/accounts)
-     * @returns true if pool was loaded, false if file doesn't exist
-     *
-     * @example
-     * if (AccountManager.loadAccountPool()) {
-     *   console.log("Pool loaded successfully");
-     * }
+     * Load account pool from disk. Returns true if a pool file was found
+     * and parsed, false if the file does not exist or parsing failed.
      */
-    static loadAccountPool(poolPath?: string): boolean;
+    loadAccountPool(poolPath?: string): boolean;
     /**
-     * Clear the entire account pool
-     * Useful for test isolation
-     *
-     * @example
-     * after(() => {
-     *   AccountManager.clearPool();
-     * });
+     * Clear the entire account pool. Useful for test isolation.
      */
-    static clearPool(): void;
+    clearPool(): void;
     /**
-     * Get the current size of the account pool
-     *
-     * @returns Number of accounts in the pool
+     * Number of accounts in the pool.
      */
-    static getPoolSize(): number;
+    getPoolSize(): number;
     /**
-     * Get all accounts in the pool
-     *
-     * @returns Array of all Account instances
+     * All accounts in the pool.
      */
-    static getAllAccounts(): Account[];
+    getAllAccounts(): Account[];
     /**
-     * Check if a label is already in use
-     *
-     * @param label The label to check
-     * @returns true if label exists, false otherwise
+     * Whether a label is currently bound to an account in this pool.
      */
-    static hasLabel(label: string): boolean;
+    hasLabel(label: string): boolean;
     /**
-     * Get or create an account with a specific label
-     * If the label exists, returns the existing account
-     * Otherwise creates a new account with that label
-     *
-     * @param label The label for the account
-     * @returns Account instance
-     *
-     * @example
-     * const alice = AccountManager.getOrCreateLabeled("alice");
-     * const aliceAgain = AccountManager.getOrCreateLabeled("alice"); // Same account
+     * Get or create an account with a specific label.
      */
-    static getOrCreateLabeled(label: string): Account;
+    getOrCreateLabeled(label: string): Account;
     /**
-     * Batch create multiple labeled accounts
-     *
-     * @param labels Array of labels to create
-     * @returns Record of label to Account mappings
-     *
-     * @example
-     * const accounts = AccountManager.createBatch(["alice", "bob", "charlie"]);
-     * console.log(accounts.alice.accountAddress.toString());
+     * Batch create multiple labeled accounts.
      */
-    static createBatch(labels: readonly string[]): Record<string, Account>;
+    createBatch(labels: readonly string[]): Record<string, Account>;
     /**
-     * Export account private keys for backup/sharing
-     * WARNING: Only use this for test accounts, never production keys
-     *
-     * @param labels Optional array of labels to export (exports all if not provided)
-     * @returns Record of label/address to private key hex string
+     * Export account private keys for backup/sharing.
+     * WARNING: Only use this for test accounts, never production keys.
      */
+    exportPrivateKeys(labels?: string[]): Record<string, string>;
+    private accountFromPrivateKey;
+    private trackAccount;
+    static getTestAccount(label?: string): Account;
+    static createAccount(label?: string, fund?: boolean): Account;
+    static getAccountByLabel(label: string): Account | undefined;
+    static loadAccountFromEnv(envVar?: string): Account;
+    static loadAccountFromPrivateKey(privateKeyHex: string): Account;
+    static loadAccountsFromConfig(config: MovehatConfig): Account[];
+    static getLabeledAccounts(): Record<string, Account>;
+    static saveAccountPool(): void;
+    static saveAccountPool(poolPath: string): void;
+    static saveAccountPool(options: SaveAccountPoolOptions): void;
+    static saveAccountPool(poolPath: string, options: SaveAccountPoolOptions): void;
+    static loadAccountPool(poolPath?: string): boolean;
+    static clearPool(): void;
+    static getPoolSize(): number;
+    static getAllAccounts(): Account[];
+    static hasLabel(label: string): boolean;
+    static getOrCreateLabeled(label: string): Account;
+    static createBatch(labels: readonly string[]): Record<string, Account>;
     static exportPrivateKeys(labels?: string[]): Record<string, string>;
-    private static accountFromPrivateKey;
-    private static trackAccount;
 }
+/** @internal — test-only. Resets the once-per-method dedup Set. */
+export declare function _resetDeprecationWarnings(): void;