movehat 0.2.2 → 0.2.3

package/src/fork/test.ts

@@ -2,6 +2,7 @@ import { join } from 'path';
 import { existsSync } from 'fs';
 import { runCli } from '../utils/runCli.js';
 import type { ChildProcessAdapter } from '../utils/childProcessAdapter.js';
+import { logger } from '../ui/index.js';
 
 export interface SnapshotOptions {
   path?: string;
@@ -40,7 +41,7 @@ export async function snapshot(options: SnapshotOptions = {}): Promise<string> {
   const name = options.name || `snapshot-${Date.now()}`;
   const snapshotPath = options.path || join(process.cwd(), '.movehat', 'snapshots', name);
 
-  console.log(`📸 Creating snapshot: ${name}...`);
+  logger.info(`Creating snapshot: ${name}...`);
 
   try {
     // Initialize fork/snapshot using aptos CLI.
@@ -68,7 +69,7 @@ export async function snapshot(options: SnapshotOptions = {}): Promise<string> {
       throw new Error('Snapshot directory was not created');
     }
 
-    console.log(`   ✓ Snapshot created at ${snapshotPath}`);
+    logger.success(`Snapshot created at ${snapshotPath}`, 2);
     return snapshotPath;
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);

package/src/harness/codeObject.ts

@@ -20,7 +20,7 @@ import {
 } from "../errors.js";
 import { runCli } from "../utils/runCli.js";
 import { parseTxHash } from "../utils/parseCliOutput.js";
-import { logger } from "../ui/index.js";
+import { logger, isVerbose } from "../ui/index.js";
 import {
   writeTempKeyFile,
   removeKeyFile,
@@ -206,7 +206,7 @@ async function executeMovementMoveObject(
       },
       { adapter: opts.adapter }
     );
-    if (buildResult.stdout) console.log(buildResult.stdout.trim());
+    if (isVerbose() && buildResult.stdout) logger.info(buildResult.stdout.trim(), 2);
 
     // Format the private key into AIP-80 shape so the Movement CLI
     // doesn't emit its raw-hex deprecation warning. `formatPrivateKey`
@@ -265,8 +265,11 @@ async function executeMovementMoveObject(
         { adapter: opts.adapter }
       );
       deployOut = result.stdout;
-      if (result.stdout) console.log(result.stdout.trim());
-      if (result.stderr) console.error(result.stderr.trim());
+      // Both streams gated behind isVerbose(); see §9 — stream channel
+      // is not by itself a failure signal. Real failures throw via
+      // CliExecutionError and are surfaced from the catch below.
+      if (isVerbose() && result.stdout) logger.info(result.stdout.trim(), 2);
+      if (isVerbose() && result.stderr) logger.info(result.stderr.trim(), 2);
     } finally {
       // Unlink via the observable helper — emit a warning if the file
       // could not be removed AND still exists on disk (private key
@@ -336,7 +339,7 @@ async function executeMovementMoveObject(
       throw error;
     }
     if (error instanceof CliExecutionError) {
-      if (error.stdoutPreview) console.log(error.stdoutPreview);
+      if (error.stdoutPreview) logger.info(error.stdoutPreview, 2);
       logger.error(
         `Failed to ${subcommand === "deploy-object" ? "deploy" : "upgrade"} module: ${error.message}\n${error.stderr}`
       );

package/src/harness/script.ts

@@ -10,7 +10,7 @@ import { validatePathSafety } from "../core/shell.js";
 import { CliExecutionError } from "../errors.js";
 import { runCli } from "../utils/runCli.js";
 import { parseTxHash } from "../utils/parseCliOutput.js";
-import { logger } from "../ui/index.js";
+import { logger, isVerbose } from "../ui/index.js";
 import {
   writeTempKeyFile,
   removeKeyFile,
@@ -132,8 +132,11 @@ export async function runMoveScript(
         { adapter: options.adapter }
       );
       scriptOut = result.stdout;
-      if (result.stdout) console.log(result.stdout.trim());
-      if (result.stderr) console.error(result.stderr.trim());
+      // Both streams gated behind isVerbose(); Movement CLI uses
+      // stderr for progress messages too. Real failures throw via
+      // CliExecutionError and are surfaced from the catch below.
+      if (isVerbose() && result.stdout) logger.info(result.stdout.trim(), 2);
+      if (isVerbose() && result.stderr) logger.info(result.stderr.trim(), 2);
     } finally {
       // Observable cleanup — emit a warning if the unlink failed and
       // the file is still on disk (private key would persist silently
@@ -167,7 +170,7 @@ export async function runMoveScript(
     return out;
   } catch (error) {
     if (error instanceof CliExecutionError) {
-      if (error.stdoutPreview) console.log(error.stdoutPreview);
+      if (error.stdoutPreview) logger.info(error.stdoutPreview, 2);
       logger.error(`Failed to run Move script: ${error.message}\n${error.stderr}`);
     } else {
       const err = error instanceof Error ? error : new Error(String(error));

package/src/helpers/setupLocalTesting.ts

@@ -95,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') {

package/src/node/LocalNodeManager.ts

@@ -6,7 +6,16 @@ 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)
@@ -86,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();
     }
 
@@ -98,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
@@ -133,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)}`);
+            }
           }
         });
       }
@@ -161,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;
@@ -303,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) {
@@ -317,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.test.ts

@@ -181,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 });
@@ -191,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 () => {
@@ -451,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/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,
 };