movehat 0.3.0 → 0.4.1

package/README.md

@@ -22,7 +22,7 @@
 - **Three execution modes** — full local blockchain, read-only fork of a remote network, or live testnet/mainnet binding.
 - **Auto-deploy in tests + auto-detect named addresses** — contracts compile and deploy automatically; no manual address wiring.
 - **Fast local boot with movelite** — on supported platforms an auto-installed [movelite](https://github.com/gilbertsahumada/movelite) binary boots the local test chain in under a second instead of ~15s, with transparent fallback to the full Movement node.
-- **Foundry-style execution traces** — raise verbosity (`-vv` … `-vvvv`) to render an indented call tree for each `contract.call(...)` with decoded arguments, gas, events, and the abort stack (movelite backend).
+- **Foundry-style execution traces** — raise verbosity (`-vv` … `-vvvv`) to render an indented call tree for each `contract.call(...)` with decoded arguments, gas, events, and the abort stack (full tree on the movelite backend; the Movement node renders a degraded flat trace — events, state changes, and gas).
 - **Native fork system** — local JSON-backed snapshots of Movement L1 state, no BCS compatibility issues.
 - **TypeScript-first** — single `PRIVATE_KEY` across all networks (Hardhat-style); deployments tracked per-network in `deployments/`.
 - **SLSA-provenance releases** — every npm release ships with [Trusted Publishers](https://docs.npmjs.com/trusted-publishers) provenance. Verify with `npm view movehat@<version>`.

package/dist/core/contract.js

@@ -1,6 +1,7 @@
 import { logger } from "../ui/index.js";
 import { traceTransaction } from "./trace/client.js";
 import { renderTrace } from "./trace/renderer.js";
+import { renderNodeTrace } from "./trace/nodeRenderer.js";
 export class MoveContract {
     aptos;
     moduleAddress;
@@ -71,6 +72,24 @@ export class MoveContract {
         const response = await this.aptos.waitForTransaction({
             transactionHash: committedTxn.hash,
         });
+        // Degraded trace: the Movement node does not expose internal call frames,
+        // but the REST response already carries the events, write-set, and gas.
+        // At raised verbosity render that flat view (a render failure must never
+        // fail a transaction that already committed).
+        //
+        // waitForTransaction returns the CommittedTransactionResponse union; the
+        // `in` guards narrow it to the user-transaction shape that carries events
+        // and changes, so renderNodeTrace receives a typed value without a cast.
+        const nodeLevel = logger.getVerbosityLevel();
+        if (nodeLevel >= 2 && "events" in response && "changes" in response) {
+            try {
+                renderNodeTrace(response, { level: nodeLevel });
+            }
+            catch (renderError) {
+                const msg = renderError instanceof Error ? renderError.message : String(renderError);
+                logger.warning(`Failed to render trace: ${msg}`);
+            }
+        }
         logger.success(`Transaction ${committedTxn.hash} committed with status: ${response.vm_status}`);
         logger.newline();
         return {

package/dist/core/trace/format.d.ts

@@ -0,0 +1,27 @@
+export declare const brightBlue: (s: string) => string;
+export declare const indent: (depth: number) => string;
+/** Shorten a 0x-prefixed address for display (`0xf903..9b16`); leave short
+ *  framework addresses like `0x1` untouched. */
+export declare const shortAddr: (addr: string) => string;
+/** Shorten the address part of a `address::module[::Name]` path. */
+export declare const shortenPath: (path: string) => string;
+/** Format a decoded value. Struct (and vector) values arrive as objects with
+ *  by-index keys; their fields can themselves be structs, so recurse rather
+ *  than `String()`-ing a nested object into `[object Object]`. */
+export declare const formatValue: (value: unknown) => string;
+export declare const formatData: (data: unknown) => string;
+/** One emitted-event line: `emit <module>::<Event> {…data}`. Reads only `type`
+ *  and `data`, so it accepts both the movelite `TracedEvent` and the SDK's
+ *  `Event` shape. */
+export declare const formatEventLine: (event: {
+    type: string;
+    data: unknown;
+}) => string;
+/** One storage / state-change line: `<op> <module>::<Resource> [@addr]`. The
+ *  `op` object is duck-typed so both movelite storage ops and SDK write-set
+ *  changes (after reshaping) feed it. */
+export declare const storageLine: (op: {
+    op: string;
+    type: string;
+    address: string | null;
+}) => string;

package/dist/core/trace/format.js

@@ -0,0 +1,61 @@
+import { colors, rgbToAnsi, shouldUseColor } from "../../ui/colors.js";
+// Generic, stateless formatting helpers shared by the movelite call-tree
+// renderer (renderer.ts) and the node degraded-trace renderer (nodeRenderer.ts).
+// None of these are tied to a specific response shape.
+// rgbToAnsi emits raw escapes unconditionally, so guard these ourselves
+// (unlike colors.*, which already no-op when color is disabled). `orange` is
+// module-private (only `leafValue` uses it); `brightBlue` is consumed by the
+// movelite renderer's footer.
+const orange = (s) => shouldUseColor() ? `${rgbToAnsi(255, 165, 0)}${s}\x1b[0m` : s;
+export const brightBlue = (s) => shouldUseColor() ? `${rgbToAnsi(90, 170, 255)}${s}\x1b[0m` : s;
+export const indent = (depth) => "  ".repeat(depth);
+/** Shorten a 0x-prefixed address for display (`0xf903..9b16`); leave short
+ *  framework addresses like `0x1` untouched. */
+export const shortAddr = (addr) => addr.startsWith("0x") && addr.length > 12
+    ? `${addr.slice(0, 6)}..${addr.slice(-4)}`
+    : addr;
+/** Shorten the address part of a `address::module[::Name]` path. */
+export const shortenPath = (path) => {
+    const [addr, ...rest] = path.split("::");
+    if (addr === undefined || rest.length === 0)
+        return path;
+    return [shortAddr(addr), ...rest].join("::");
+};
+const NUMERIC = /^\d+$/;
+const leafValue = (value) => {
+    const s = String(value);
+    if (NUMERIC.test(s))
+        return orange(s);
+    if (s.startsWith("0x") && s.length > 12)
+        return shortAddr(s);
+    return s;
+};
+/** Format a decoded value. Struct (and vector) values arrive as objects with
+ *  by-index keys; their fields can themselves be structs, so recurse rather
+ *  than `String()`-ing a nested object into `[object Object]`. */
+export const formatValue = (value) => {
+    if (value !== null && typeof value === "object") {
+        return `{ ${Object.values(value)
+            .map(formatValue)
+            .join(", ")} }`;
+    }
+    return leafValue(value);
+};
+export const formatData = (data) => {
+    if (data === null || data === undefined)
+        return "";
+    try {
+        return colors.dim(JSON.stringify(data));
+    }
+    catch {
+        return colors.dim(String(data));
+    }
+};
+/** One emitted-event line: `emit <module>::<Event> {…data}`. Reads only `type`
+ *  and `data`, so it accepts both the movelite `TracedEvent` and the SDK's
+ *  `Event` shape. */
+export const formatEventLine = (event) => `${colors.warning(`emit ${shortenPath(event.type)}`)} ${formatData(event.data)}`.trimEnd();
+/** One storage / state-change line: `<op> <module>::<Resource> [@addr]`. The
+ *  `op` object is duck-typed so both movelite storage ops and SDK write-set
+ *  changes (after reshaping) feed it. */
+export const storageLine = (op) => `${colors.primary(`${op.op} ${shortenPath(op.type)}`)}${op.address ? colors.dim(` @${shortAddr(op.address)}`) : ""}`;

package/dist/core/trace/nodeRenderer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Minimal structural view of a committed transaction, as the Aptos SDK's
+ * `waitForTransaction` returns it (`UserTransactionResponse`). Typed loosely so
+ * unit tests can feed plain fixtures and so we never depend on the full SDK
+ * response union. The real Movement node REST API does NOT expose internal call
+ * frames, so this is a flat, degraded trace — events + write-set + gas — rather
+ * than the movelite call tree.
+ */
+export interface NodeTxView {
+    success: boolean;
+    vm_status: string;
+    /** Transaction gas in octas (external unit). */
+    gas_used: string;
+    events: {
+        type: string;
+        data: unknown;
+    }[];
+    changes: NodeWriteSetChange[];
+}
+/** Loose shape of an SDK `WriteSetChange` — only the fields we render. */
+interface NodeWriteSetChange {
+    type: string;
+    address?: string;
+    /** `write_resource` payload (a `MoveResource` `{type,data}`); typed `unknown`
+     *  and narrowed at the use sites since the shape varies by change type. */
+    data?: unknown;
+    /** `delete_resource` carries the resource type as a string here. */
+    resource?: string;
+    /** Table-item changes carry a `handle` instead of an `address`. */
+    handle?: string;
+}
+/**
+ * Pure formatter for the node degraded trace. Snapshot-testable without
+ * touching stdout. `level` is the verbosity level (2..4): L2 = events, L3 =
+ * + state changes, L4 = + each change's decoded data. The footer carries the
+ * status and the octa `gas_used` (there is no per-frame trace timing off the
+ * node).
+ */
+export declare function formatNodeTraceLines(tx: NodeTxView, level: number): string[];
+/** Render a node degraded trace to the terminal. Wraps {@link formatNodeTraceLines}. */
+export declare function renderNodeTrace(tx: NodeTxView, opts: {
+    level: number;
+}): void;
+export {};

package/dist/core/trace/nodeRenderer.js

@@ -0,0 +1,90 @@
+import { logger } from "../../ui/index.js";
+import { colors } from "../../ui/colors.js";
+import { symbols } from "../../ui/symbols.js";
+import { formatData, formatEventLine, storageLine } from "./format.js";
+/** Reshape an SDK write-set change into the shared `storageLine` duck-type. */
+const changeToOp = (c) => {
+    const address = typeof c.address === "string" ? c.address : null;
+    switch (c.type) {
+        case "write_resource": {
+            const t = c.data && typeof c.data === "object" && "type" in c.data
+                ? String(c.data.type ?? "?")
+                : "?";
+            return { op: c.type, type: t, address };
+        }
+        case "delete_resource":
+            return { op: c.type, type: c.resource ?? "?", address };
+        case "write_module":
+        case "delete_module":
+            return { op: c.type, type: "module", address };
+        case "write_table_item":
+        case "delete_table_item":
+            // Table items have no resource type; key off the table `handle`.
+            return { op: c.type, type: "table_item", address: c.handle ?? null };
+        default:
+            return { op: c.type, type: "?", address };
+    }
+};
+/** Level-4 payload for a change: the resource's decoded fields when present. */
+const changePayload = (c) => {
+    if (c.data && typeof c.data === "object" && "data" in c.data) {
+        return c.data.data;
+    }
+    return c.data;
+};
+const nodeFooter = (tx) => {
+    const status = tx.success
+        ? colors.success(`${symbols.success} ${tx.vm_status}`)
+        : colors.error(`${symbols.error} ${tx.vm_status}`);
+    const sep = colors.dim(" · ");
+    const gas = colors.dim(`gas_used: ${tx.gas_used} octas`);
+    return `${status}${sep}${gas}`;
+};
+/**
+ * Pure formatter for the node degraded trace. Snapshot-testable without
+ * touching stdout. `level` is the verbosity level (2..4): L2 = events, L3 =
+ * + state changes, L4 = + each change's decoded data. The footer carries the
+ * status and the octa `gas_used` (there is no per-frame trace timing off the
+ * node).
+ */
+export function formatNodeTraceLines(tx, level) {
+    const lines = [];
+    // Events (level 2+).
+    if (tx.events.length === 0) {
+        lines.push(colors.dim("(no events emitted)"));
+    }
+    else {
+        lines.push(colors.bold("Events"));
+        for (const e of tx.events)
+            lines.push("  " + formatEventLine(e));
+    }
+    // State changes (level 3+).
+    if (level >= 3) {
+        lines.push("");
+        if (tx.changes.length === 0) {
+            lines.push(colors.dim("(no state changes)"));
+        }
+        else {
+            lines.push(colors.bold("State changes"));
+            for (const c of tx.changes) {
+                lines.push("  " + storageLine(changeToOp(c)));
+                if (level >= 4) {
+                    const payload = formatData(changePayload(c));
+                    if (payload)
+                        lines.push("    " + payload);
+                }
+            }
+        }
+    }
+    lines.push("");
+    lines.push(nodeFooter(tx));
+    return lines;
+}
+/** Render a node degraded trace to the terminal. Wraps {@link formatNodeTraceLines}. */
+export function renderNodeTrace(tx, opts) {
+    logger.newline();
+    for (const line of formatNodeTraceLines(tx, opts.level)) {
+        logger.plain(line);
+    }
+    logger.newline();
+}

package/dist/core/trace/renderer.js

@@ -1,46 +1,10 @@
 import { logger } from "../../ui/index.js";
-import { colors, rgbToAnsi, shouldUseColor } from "../../ui/colors.js";
+import { colors } from "../../ui/colors.js";
 import { symbols } from "../../ui/symbols.js";
-// rgbToAnsi emits raw escapes unconditionally, so guard these two ourselves
-// (unlike colors.*, which already no-op when color is disabled).
-const orange = (s) => shouldUseColor() ? `${rgbToAnsi(255, 165, 0)}${s}\x1b[0m` : s;
-const brightBlue = (s) => shouldUseColor() ? `${rgbToAnsi(90, 170, 255)}${s}\x1b[0m` : s;
-const indent = (depth) => "  ".repeat(depth);
-/** Shorten a 0x-prefixed address for display (`0xf903..9b16`); leave short
- *  framework addresses like `0x1` untouched. */
-const shortAddr = (addr) => addr.startsWith("0x") && addr.length > 12
-    ? `${addr.slice(0, 6)}..${addr.slice(-4)}`
-    : addr;
-/** Shorten the address part of a `address::module[::Name]` path. */
-const shortenPath = (path) => {
-    const [addr, ...rest] = path.split("::");
-    if (addr === undefined || rest.length === 0)
-        return path;
-    return [shortAddr(addr), ...rest].join("::");
-};
+import { brightBlue, formatEventLine, formatValue, indent, shortenPath, storageLine, } from "./format.js";
 const isFramework = (module) => module !== null && module.startsWith("0x1::");
 /** Visible at level 3 (user-module tree): not a framework frame, not a native. */
 const isUserFrame = (node) => !isFramework(node.module) && node.kind !== "native";
-const NUMERIC = /^\d+$/;
-const leafValue = (value) => {
-    const s = String(value);
-    if (NUMERIC.test(s))
-        return orange(s);
-    if (s.startsWith("0x") && s.length > 12)
-        return shortAddr(s);
-    return s;
-};
-/** Format a decoded value. Struct (and vector) values arrive as objects with
- *  by-index keys; their fields can themselves be structs, so recurse rather
- *  than `String()`-ing a nested object into `[object Object]`. */
-const formatValue = (value) => {
-    if (value !== null && typeof value === "object") {
-        return `{ ${Object.values(value)
-            .map(formatValue)
-            .join(", ")} }`;
-    }
-    return leafValue(value);
-};
 const formatArgValue = (arg) => {
     if (arg.value === null)
         return "()";
@@ -61,18 +25,6 @@ const frameLabel = (node) => {
     const gas = colors.dim(` [${node.gas}]`);
     return `${colored}(${formatArgs(node.args)})${gas}`;
 };
-const formatData = (data) => {
-    if (data === null || data === undefined)
-        return "";
-    try {
-        return colors.dim(JSON.stringify(data));
-    }
-    catch {
-        return colors.dim(String(data));
-    }
-};
-const eventLine = (event) => `${colors.warning(`emit ${shortenPath(event.type)}`)} ${formatData(event.data)}`.trimEnd();
-const storageLine = (op) => `${colors.primary(`${op.op} ${shortenPath(op.type)}`)}${op.address ? colors.dim(` @${shortAddr(op.address)}`) : ""}`;
 /** Non-unit return values only; null when nothing to show. */
 const returnLine = (ret) => {
     const meaningful = ret.filter((r) => r.type !== "()" && r.value !== null);
@@ -106,7 +58,7 @@ const renderNode = (node, depth, showFull, lines) => {
     const childDepth = depth + 1;
     if (showFull) {
         for (const e of node.events)
-            lines.push(indent(childDepth) + eventLine(e));
+            lines.push(indent(childDepth) + formatEventLine(e));
         for (const s of node.storage)
             lines.push(indent(childDepth) + storageLine(s));
         const ret = returnLine(node.return);
@@ -122,7 +74,7 @@ const renderNode = (node, depth, showFull, lines) => {
     const visibleChildren = [];
     gatherHidden(node.children, bubbled, visibleChildren);
     for (const e of [...node.events, ...bubbled]) {
-        lines.push(indent(childDepth) + eventLine(e));
+        lines.push(indent(childDepth) + formatEventLine(e));
     }
     for (const c of visibleChildren)
         renderNode(c, childDepth, showFull, lines);
@@ -170,7 +122,7 @@ export function formatTraceLines(response, level, elapsedMs) {
         else {
             lines.push(colors.bold("Events"));
             for (const { event } of events)
-                lines.push("  " + eventLine(event));
+                lines.push("  " + formatEventLine(event));
         }
     }
     else {

package/dist/ui/spinner.js

@@ -1,5 +1,20 @@
 import ora from 'ora';
 import { shouldUseColor } from './colors.js';
+import { coloredSymbol } from './symbols.js';
+/**
+ * Persist a spinner's final line with a color-gated status symbol.
+ *
+ * ora's own `.succeed()` / `.fail()` color their log-symbols through ora's
+ * internal TTY detection, which still emits ANSI on the persisted line when
+ * stdout is piped (non-TTY) even though our `shouldUseColor()` says no color.
+ * Routing the symbol through `coloredSymbol` (gated by `shouldUseColor`) keeps
+ * piped output escape-free while preserving the colored glyph in a real TTY.
+ */
+const persist = (spin, type, text) => {
+    spin.stopAndPersist(text === undefined
+        ? { symbol: coloredSymbol(type) }
+        : { symbol: coloredSymbol(type), text });
+};
 /**
  * Create and start a spinner
  * Automatically disabled in non-TTY environments (CI, pipes)
@@ -63,12 +78,12 @@ export const withSpinner = async (startText, task, successText, errorText, inden
     const spin = spinner({ text: startText, indent });
     try {
         const result = await task();
-        spin.succeed(successText || startText.replace(/\.\.\.?$/, ''));
+        persist(spin, 'success', successText || startText.replace(/\.\.\.?$/, ''));
         return result;
     }
     catch (error) {
         const errMsg = error instanceof Error ? error.message : String(error);
-        spin.fail(errorText || `Failed: ${errMsg}`);
+        persist(spin, 'error', errorText || `Failed: ${errMsg}`);
         throw error;
     }
 };
@@ -104,12 +119,12 @@ export const withTimedSpinner = async (label, task, indent = 0) => {
     }, 500);
     try {
         const result = await task();
-        spin.succeed(`${label} (${((Date.now() - start) / 1000).toFixed(1)}s)`);
+        persist(spin, 'success', `${label} (${((Date.now() - start) / 1000).toFixed(1)}s)`);
         return result;
     }
     catch (error) {
         const errMsg = error instanceof Error ? error.message : String(error);
-        spin.fail(errMsg);
+        persist(spin, 'error', errMsg);
         throw error;
     }
     finally {
@@ -146,11 +161,11 @@ export const createSpinnerChain = () => {
             currentSpinner = spinner({ text, indent });
             try {
                 const result = await task();
-                currentSpinner.succeed();
+                persist(currentSpinner, 'success');
                 return result;
             }
             catch (error) {
-                currentSpinner.fail();
+                persist(currentSpinner, 'error');
                 throw error;
             }
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "movehat",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Hardhat-like development framework for Movement L1 smart contracts",
   "bin": {