movehat 0.2.1 → 0.2.3

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

@@ -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");
   });
@@ -180,7 +181,7 @@ describe("LocalNodeManager — start / stop / lifecycle", () => {
     expect(proc.stderr!.listenerCount("data")).toBe(0);
   });
 
-  it("start in non-silent mode wires stdout/stderr listeners that log events", async () => {
+  it("start in non-silent mode wires stdout/stderr listeners that respect §9 filtering", async () => {
     const { adapter, spawned } = buildFakeAdapter();
     stubFetchAlwaysOk();
     const mgr = new LocalNodeManager({ adapter, testDir: tmpDir, silent: false });
@@ -190,19 +191,9 @@ describe("LocalNodeManager — start / stop / lifecycle", () => {
     const proc = spawned[0]!;
     expect(proc.stdout!.listenerCount("data")).toBeGreaterThan(0);
     expect(proc.stderr!.listenerCount("data")).toBeGreaterThan(0);
-
-    // Drive a line through stdout — the manager's listener forwards to console.log.
-    proc.stdout!.emit("data", Buffer.from("local node ready\n"));
-    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("local node ready"));
-
-    // stderr non-WARN line goes through console.error.
-    proc.stderr!.emit("data", Buffer.from("real error\n"));
-    expect(errSpy).toHaveBeenCalledWith(expect.stringContaining("real error"));
-
-    // stderr WARN line should be filtered (no error log).
-    errSpy.mockClear();
-    proc.stderr!.emit("data", Buffer.from("WARN something\n"));
-    expect(errSpy).not.toHaveBeenCalledWith(expect.stringContaining("WARN"));
+    // Detailed filter behavior — what passes through vs what's gated
+    // behind isVerbose() — lives in the "§9 console UX" describe block
+    // below. This test only locks the listener-wiring contract.
   });
 
   it("force-restart cleans the test directory before spawn", async () => {
@@ -450,3 +441,139 @@ describe("LocalNodeManager — fundAccount", () => {
     expect(fetchFn.mock.calls.length).toBeGreaterThanOrEqual(4);
   });
 });
+
+describe("LocalNodeManager — subprocess output filtering (§9 console UX)", () => {
+  let tmpDir: string;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let errSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "movehat-localnode-filter-"));
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    // Ensure quiet mode is the default for each test; the verbose tests
+    // set MOVEHAT_VERBOSE explicitly inside their own scope.
+    delete process.env.MOVEHAT_VERBOSE;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    delete process.env.MOVEHAT_VERBOSE;
+    if (existsSync(tmpDir)) {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("hides routine stdout chatter from the movement node in quiet mode", async () => {
+    const { adapter, spawned } = buildFakeAdapter();
+    stubFetchAlwaysOk();
+    const mgr = new LocalNodeManager({ adapter, testDir: tmpDir });
+    await mgr.start();
+
+    const proc = spawned[0]!;
+    logSpy.mockClear();
+
+    // Push routine chatter — exactly the noise we used to spam to stdout.
+    proc.stdout!.emit("data", Buffer.from("Loading aptos framework module"));
+    proc.stdout!.emit("data", Buffer.from("Compiling Move bytecode"));
+    proc.stdout!.emit("data", Buffer.from("aptos_account: account created"));
+
+    // None of these should have reached stdout (no `[Node]` prefix, no
+    // muted gray `›` prefix). The only console.log calls that may arise
+    // are from the spinner mock falling back to plain text — but since
+    // ora auto-disables in non-TTY (vitest is non-TTY), even those are
+    // suppressed.
+    const stdoutCalls = logSpy.mock.calls.flat().join(" ");
+    expect(stdoutCalls).not.toContain("Loading aptos framework module");
+    expect(stdoutCalls).not.toContain("Compiling Move bytecode");
+    expect(stdoutCalls).not.toContain("aptos_account: account created");
+  });
+
+  it("always surfaces panic / fatal lines as warnings, even in quiet mode", async () => {
+    const { adapter, spawned } = buildFakeAdapter();
+    stubFetchAlwaysOk();
+    const mgr = new LocalNodeManager({ adapter, testDir: tmpDir });
+    await mgr.start();
+
+    const proc = spawned[0]!;
+    warnSpy.mockClear();
+
+    proc.stdout!.emit("data", Buffer.from("thread 'main' panicked at 'state corrupted'"));
+
+    const warnCalls = warnSpy.mock.calls.flat().join(" ");
+    expect(warnCalls).toContain("panicked");
+  });
+
+  it("surfaces 'address already in use' (port conflict) regardless of verbosity", async () => {
+    const { adapter, spawned } = buildFakeAdapter();
+    stubFetchAlwaysOk();
+    const mgr = new LocalNodeManager({ adapter, testDir: tmpDir });
+    await mgr.start();
+
+    const proc = spawned[0]!;
+    warnSpy.mockClear();
+
+    proc.stdout!.emit(
+      "data",
+      Buffer.from("error: address already in use: 127.0.0.1:8080"),
+    );
+
+    const warnCalls = warnSpy.mock.calls.flat().join(" ");
+    expect(warnCalls).toContain("address already in use");
+  });
+
+  it("surfaces stdout chatter with gray prefix in verbose mode", async () => {
+    process.env.MOVEHAT_VERBOSE = "1";
+    const { adapter, spawned } = buildFakeAdapter();
+    stubFetchAlwaysOk();
+    const mgr = new LocalNodeManager({ adapter, testDir: tmpDir });
+    await mgr.start();
+
+    const proc = spawned[0]!;
+    logSpy.mockClear();
+
+    proc.stdout!.emit("data", Buffer.from("Loading aptos framework module"));
+
+    const stdoutCalls = logSpy.mock.calls.flat().join(" ");
+    expect(stdoutCalls).toContain("Loading aptos framework module");
+  });
+
+  it("always surfaces critical stderr (panic/EADDRINUSE) via logger.error", async () => {
+    const { adapter, spawned } = buildFakeAdapter();
+    stubFetchAlwaysOk();
+    const mgr = new LocalNodeManager({ adapter, testDir: tmpDir });
+    await mgr.start();
+
+    const proc = spawned[0]!;
+    errSpy.mockClear();
+
+    proc.stderr!.emit("data", Buffer.from("thread panicked: failed to bind socket"));
+
+    const stderrCalls = errSpy.mock.calls.flat().join(" ");
+    expect(stderrCalls).toContain("panicked");
+  });
+
+  it("hides routine progress stderr in quiet mode (Movement CLI emits progress to stderr too)", async () => {
+    const { adapter, spawned } = buildFakeAdapter();
+    stubFetchAlwaysOk();
+    const mgr = new LocalNodeManager({ adapter, testDir: tmpDir });
+    await mgr.start();
+
+    const proc = spawned[0]!;
+    errSpy.mockClear();
+
+    // The movement subprocess emits progress messages to stderr that
+    // are NOT errors: "Applying post startup steps...", "Compiling,
+    // may take a little while...". Hiding stream channel from the
+    // user keeps the console clean.
+    proc.stderr!.emit("data", Buffer.from("Applying post startup steps..."));
+    proc.stderr!.emit("data", Buffer.from("[WARN] deprecated config field"));
+
+    const stderrCalls = errSpy.mock.calls.flat().join(" ");
+    expect(stderrCalls).not.toContain("Applying post startup steps");
+    expect(stderrCalls).not.toContain("deprecated config field");
+  });
+});

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

@@ -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/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/ui/__tests__/logger.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { configureLogger, isVerbose, divider, phase } from "../logger.js";
+
+describe("logger — verbosity", () => {
+  let originalEnv: string | undefined;
+
+  beforeEach(() => {
+    originalEnv = process.env.MOVEHAT_VERBOSE;
+    // Start each test from a clean slate so prior runs cannot leak.
+    delete process.env.MOVEHAT_VERBOSE;
+    configureLogger({ verbosity: "normal" });
+  });
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.MOVEHAT_VERBOSE;
+    } else {
+      process.env.MOVEHAT_VERBOSE = originalEnv;
+    }
+    configureLogger({ verbosity: "normal" });
+  });
+
+  it("defaults to non-verbose when MOVEHAT_VERBOSE is unset and config is normal", () => {
+    expect(isVerbose()).toBe(false);
+  });
+
+  it("returns true when MOVEHAT_VERBOSE=1 (env-driven path)", () => {
+    process.env.MOVEHAT_VERBOSE = "1";
+    expect(isVerbose()).toBe(true);
+  });
+
+  it("returns true when configureLogger({ verbosity: 'verbose' }) is set in-process", () => {
+    configureLogger({ verbosity: "verbose" });
+    expect(isVerbose()).toBe(true);
+  });
+
+  it("env var wins even when in-process config is normal (allows shell-script callers)", () => {
+    configureLogger({ verbosity: "normal" });
+    process.env.MOVEHAT_VERBOSE = "1";
+    expect(isVerbose()).toBe(true);
+  });
+
+  it("non-'1' MOVEHAT_VERBOSE values do not enable verbose mode", () => {
+    process.env.MOVEHAT_VERBOSE = "true";
+    expect(isVerbose()).toBe(false);
+    process.env.MOVEHAT_VERBOSE = "0";
+    expect(isVerbose()).toBe(false);
+  });
+});
+
+describe("logger.phase / logger.divider", () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    configureLogger({ silent: false });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("phase prints three lines: top rule, indented title, bottom rule", () => {
+    phase("Local Movement node");
+    expect(logSpy).toHaveBeenCalledTimes(3);
+
+    const calls = logSpy.mock.calls.map((c: unknown[]) => String(c[0]));
+    // The title line carries the supplied text after the two-space indent.
+    expect(calls[1]).toContain("Local Movement node");
+    // Top and bottom rules should be identical (same width, same color).
+    expect(calls[0]).toBe(calls[2]);
+  });
+
+  it("divider prints a single muted rule line", () => {
+    divider();
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    const line = String(logSpy.mock.calls[0]?.[0] ?? "");
+    // The rule character is `━` (BOX DRAWINGS HEAVY HORIZONTAL).
+    expect(line).toMatch(/━+/);
+  });
+
+  it("phase and divider are silenced when configureLogger({ silent: true })", () => {
+    configureLogger({ silent: true });
+    phase("hidden phase");
+    divider();
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+});

package/src/ui/formatters.ts

@@ -176,7 +176,7 @@ export const indent = (text: string, spaces: number): string => {
  * console.log(divider(40, '='));
  * // ========================================
  */
-export const divider = (
+const divider = (
   width: number = 60,
   char: string = symbols.line
 ): string => {

package/src/ui/logger.ts

@@ -6,6 +6,14 @@ import { coloredSymbol, symbols } from './symbols.js';
  */
 export type LogLevel = 'info' | 'success' | 'error' | 'warning' | 'debug';
 
+/**
+ * Verbosity level for subprocess output and gray-prefixed chatter.
+ * - `quiet`   — reserved; currently behaves like `normal`
+ * - `normal`  — default; system logs only, subprocess chatter hidden
+ * - `verbose` — surface subprocess stdout with a muted gray `›` prefix
+ */
+export type Verbosity = 'quiet' | 'normal' | 'verbose';
+
 /**
  * Logger configuration options
  */
@@ -16,6 +24,8 @@ export interface LoggerConfig {
   level?: LogLevel;
   /** Include timestamps in log messages */
   timestamp?: boolean;
+  /** Verbosity level for subprocess output */
+  verbosity?: Verbosity;
 }
 
 /**
@@ -25,8 +35,18 @@ let config: LoggerConfig = {
   silent: false,
   level: 'info',
   timestamp: false,
+  verbosity: process.env.MOVEHAT_VERBOSE === '1' ? 'verbose' : 'normal',
 };
 
+/**
+ * Whether subprocess chatter should reach the user's terminal.
+ * Honors both the in-process config (set by the `-v` CLI flag's
+ * preAction hook) and the `MOVEHAT_VERBOSE=1` env var (which lets
+ * callers opt in before the CLI parses args, e.g. in shell scripts).
+ */
+export const isVerbose = (): boolean =>
+  config.verbosity === 'verbose' || process.env.MOVEHAT_VERBOSE === '1';
+
 /**
  * Configure logger globally
  *
@@ -186,6 +206,45 @@ export const section = (title: string): void => {
   console.log(`\n${colors.brandBright(title)}`);
 };
 
+/**
+ * Width of the `━` rule used by `phase` and `divider`. Matched to a
+ * comfortable terminal width that fits in a side-by-side dev layout.
+ */
+const PHASE_RULE_WIDTH = 52;
+
+/**
+ * Single muted horizontal rule. Use to close out a phase or to
+ * visually separate output sections.
+ */
+export const divider = (): void => {
+  if (config.silent) return;
+  console.log(colors.muted('━'.repeat(PHASE_RULE_WIDTH)));
+};
+
+/**
+ * Phase header — renders a muted top rule, a bold brand-colored title
+ * indented two spaces, and a muted bottom rule. Use at top-level phase
+ * boundaries (local node start, deploy flow, test orchestrator
+ * sections) so the user can visually anchor where one phase ends and
+ * the next begins.
+ *
+ * @param title - Phase title (e.g. "Local Movement node")
+ *
+ * @example
+ * logger.phase('Local Movement node');
+ * // Renders:
+ * // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * //   Local Movement node
+ * // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ */
+export const phase = (title: string): void => {
+  if (config.silent) return;
+  const rule = colors.muted('━'.repeat(PHASE_RULE_WIDTH));
+  console.log(rule);
+  console.log(`  ${colors.brandBright(title)}`);
+  console.log(rule);
+};
+
 /**
  * Key-value pair
  * Use for displaying structured data
@@ -235,6 +294,7 @@ export const item = (text: string, indent: number = 0): void => {
  */
 export const logger = {
   configure: configureLogger,
+  isVerbose,
   info,
   success,
   error,
@@ -243,6 +303,8 @@ export const logger = {
   plain,
   newline,
   section,
+  phase,
+  divider,
   kv,
   item,
 };

package/src/ui/spinner.ts

@@ -103,6 +103,53 @@ export const withSpinner = async <T>(
   }
 };
 
+/**
+ * Execute async task with a spinner that updates its label with
+ * elapsed seconds while the task runs. Use for long-running phases
+ * (local node startup, publish + tx wait) where the user wants
+ * visible progress feedback in lieu of subprocess chatter.
+ *
+ * Pairs with the `§9` console-UX convention: any phase that
+ * empirically takes ≥3s in normal use should wrap its body in
+ * `withTimedSpinner` so the terminal never goes silent while work
+ * happens.
+ *
+ * @param label - Stable label shown next to the spinner (e.g. "Starting node")
+ * @param task - Async function to execute
+ * @param indent - Number of spaces to indent (default: 0)
+ * @returns Promise resolving to task result
+ *
+ * @example
+ * await withTimedSpinner('Starting local node', async () => {
+ *   await this.waitForReady(60_000);
+ * });
+ * // Renders: ⠋ Starting local node — 0.0s ... ⠼ Starting local node — 14.2s
+ * // On success: ✔ Starting local node (14.2s)
+ * // On error:   ✖ <error.message>
+ */
+export const withTimedSpinner = async <T>(
+  label: string,
+  task: () => Promise<T>,
+  indent: number = 0
+): Promise<T> => {
+  const start = Date.now();
+  const spin = spinner({ text: `${label} — 0.0s`, indent });
+  const timer = setInterval(() => {
+    spin.text = `${label} — ${((Date.now() - start) / 1000).toFixed(1)}s`;
+  }, 500);
+  try {
+    const result = await task();
+    spin.succeed(`${label} (${((Date.now() - start) / 1000).toFixed(1)}s)`);
+    return result;
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    spin.fail(errMsg);
+    throw error;
+  } finally {
+    clearInterval(timer);
+  }
+};
+
 /**
  * Spinner chain for sequential operations
  * Manages multiple spinners in sequence

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/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
@@ -114,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 = () => {