cli: add --json structured-output mode for init / add-chain / push / transfer-ownership

Adds a global --json flag (also activated by WL_NTT_JSON=1) that:

- Redirects console.log / .info / .warn / .debug and direct process.stdout
  writes to stderr.
- Emits exactly one { ok, command, data } envelope on stdout from the
  command's success path via emitResult().

Failure paths are intentionally unstructured: non-zero exit + stderr
message is the contract. Wrappers (scripts, parent processes) read the
trailing stdout line on exit code 0; treat anything else as failure.

Bun's console implementation doesn't always route through
process.stdout.write, so we override the console methods directly *and*
hijack process.stdout.write for transitive deps.

Author: kcsongor

cli/src/__tests__/json-output.test.ts

@@ -0,0 +1,100 @@
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  setDefaultTimeout,
+} from "bun:test";
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+const CLI = path.resolve(import.meta.dir, "../index.ts");
+const SUBPROCESS_TIMEOUT = 30_000;
+
+setDefaultTimeout(SUBPROCESS_TIMEOUT);
+
+async function runCli(
+  args: string[],
+  opts?: { cwd?: string; env?: Record<string, string> }
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(["bun", "run", CLI, ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+    cwd: opts?.cwd ?? process.cwd(),
+    env: { ...process.env, ...(opts?.env ?? {}) },
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+  return { stdout, stderr, exitCode };
+}
+
+describe("--json output mode", () => {
+  let workDir: string;
+
+  beforeEach(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "ntt-json-test-"));
+  });
+
+  afterEach(() => {
+    if (workDir && fs.existsSync(workDir)) {
+      fs.rmSync(workDir, { recursive: true, force: true });
+    }
+  });
+
+  it("ntt init --json emits a single JSON envelope on stdout", async () => {
+    const { stdout, exitCode } = await runCli(["init", "Testnet", "--json"], {
+      cwd: workDir,
+    });
+    expect(exitCode).toBe(0);
+    // stdout should be exactly the JSON envelope (plus trailing newline).
+    const lines = stdout.trim().split("\n").filter(Boolean);
+    expect(lines.length).toBe(1);
+    const parsed = JSON.parse(lines[0]!);
+    expect(parsed.ok).toBe(true);
+    expect(parsed.command).toBe("init");
+    expect(parsed.data.network).toBe("Testnet");
+    expect(parsed.data.path).toBe("deployment.json");
+  });
+
+  it("WL_NTT_JSON=1 activates the same envelope without --json flag", async () => {
+    const { stdout, exitCode } = await runCli(["init", "Mainnet"], {
+      cwd: workDir,
+      env: { WL_NTT_JSON: "1" },
+    });
+    expect(exitCode).toBe(0);
+    const lines = stdout.trim().split("\n").filter(Boolean);
+    expect(lines.length).toBe(1);
+    const parsed = JSON.parse(lines[0]!);
+    expect(parsed.ok).toBe(true);
+    expect(parsed.command).toBe("init");
+    expect(parsed.data.network).toBe("Mainnet");
+  });
+
+  it("human mode is unchanged (no JSON envelope on stdout)", async () => {
+    const { stdout, stderr, exitCode } = await runCli(["init", "Testnet"], {
+      cwd: workDir,
+    });
+    expect(exitCode).toBe(0);
+    // Human-readable messages on stdout, no JSON envelope.
+    expect(stdout).toContain("deployment.json created");
+    expect(stdout).not.toContain('"ok":true');
+    // Should NOT have routed human output to stderr in human mode.
+    expect(stderr).not.toContain("deployment.json created");
+  });
+
+  it("--json routes human messages to stderr, keeping stdout clean", async () => {
+    const { stdout, stderr, exitCode } = await runCli(
+      ["init", "Testnet", "--json"],
+      { cwd: workDir }
+    );
+    expect(exitCode).toBe(0);
+    expect(stderr).toContain("deployment.json created");
+    // stdout must be ONLY the JSON envelope.
+    expect(stdout.trim()).toMatch(/^\{.*\}$/);
+  });
+});

cli/src/commands/add-chain.ts

@@ -14,6 +14,7 @@ import type { Argv } from "yargs";
 import { colors } from "../colors.js";
 import { loadConfig, type Config } from "../deployments";
 import { enableBigBlocks } from "../evm/hyperliquid.js";
+import { emitResult } from "../output.js";
 import { promptYesNo } from "../prompts.js";
 import { promptSolanaMainnetOverridesIfNeeded } from "../overrides.js";
 import { validatePayerOption } from "../validation";
@@ -403,6 +404,16 @@ export function createAddChainCommand(
         console.log(
           `Added ${chain} to ${path} (instance ${instance.toBase58()} under program ${instanceOf})`
         );
+        emitResult("add-chain", {
+          path,
+          chain,
+          manager: deployedManager.address.toString(),
+          instance: instance.toBase58(),
+          decimals,
+          mode,
+          token,
+          instanceOf,
+        });
         return;
       }
 
@@ -464,6 +475,15 @@ export function createAddChainCommand(
       );
       fs.writeFileSync(path, JSON.stringify(deployments, null, 2));
       console.log(`Added ${chain} to ${path}`);
+      emitResult("add-chain", {
+        path,
+        chain,
+        manager: deployedManager.address.toString(),
+        instance: solanaInstance,
+        decimals,
+        mode,
+        token,
+      });
     },
   };
 }

cli/src/commands/init.ts

@@ -2,6 +2,7 @@ import fs from "fs";
 import { isNetwork } from "@wormhole-foundation/sdk";
 import type { Argv } from "yargs";
 import { colors } from "../colors.js";
+import { emitResult } from "../output.js";
 import { options } from "./shared";
 
 export function createInitCommand() {
@@ -48,6 +49,7 @@ export function createInitCommand() {
           `\nTip: To use custom RPC endpoints, rename example-overrides.json to overrides.json and edit as needed.`
         )
       );
+      emitResult("init", { path, network: argv["network"] });
     },
   };
 }

cli/src/commands/push.ts

@@ -16,6 +16,7 @@ import type { Argv } from "yargs";
 import { ethers, Interface } from "ethers";
 import { colors } from "../colors.js";
 import { loadConfig, type Config } from "../deployments";
+import { emitResult } from "../output.js";
 import { getSigner, type SignerType } from "../signers/getSigner";
 import { newSignSendWaiter } from "../signers/signSendWait.js";
 import { registerSolanaTransceiver } from "../solana/transceiver";
@@ -264,6 +265,7 @@ export function createPushCommand(overrides: WormholeConfigOverrides<Network>) {
         process.exit(1);
       }
 
+      const chainsTouched: string[] = [];
       for (const [chain, deployment] of Object.entries(
         depsAfterRegistrations
       )) {
@@ -284,7 +286,17 @@ export function createPushCommand(overrides: WormholeConfigOverrides<Network>) {
           argv["dangerously-transfer-ownership-in-one-step"],
           overrides
         );
+        chainsTouched.push(chain);
       }
+      emitResult("push", {
+        path: argv["path"],
+        chainsTouched,
+        skipChains,
+        onlyChains,
+        ownershipTransferredOneStep: Boolean(
+          argv["dangerously-transfer-ownership-in-one-step"]
+        ),
+      });
     },
   };
 }

cli/src/commands/transfer-ownership.ts

@@ -17,6 +17,7 @@ import { ethers } from "ethers";
 
 import { colors } from "../colors.js";
 import { loadConfig, type Config } from "../deployments";
+import { emitResult } from "../output.js";
 import { getSigner } from "../signers/getSigner";
 
 import { options } from "./shared";
@@ -144,6 +145,13 @@ export function createTransferOwnershipCommand(
           console.log(
             `✅ Ownership transferred successfully to ${destination}`
           );
+          emitResult("transfer-ownership", {
+            chain,
+            manager: chainConfig.manager,
+            previousOwner: currentOwner.toString(),
+            newOwner: newOwnerFromContract,
+            txHash: tx.hash,
+          });
         } else {
           console.error(`❌ Ownership transfer verification failed`);
           console.error(`   New owner:        ${newOwnerFromContract}`);

cli/src/index.ts

@@ -41,6 +41,13 @@ const overrides: WormholeConfigOverrides<Network> = loadOverrides();
 yargs(hideBin(process.argv))
   .wrap(Math.min(process.stdout.columns || 120, 160)) // Use terminal width, but no more than 160 characters
   .scriptName("ntt")
+  .option("json", {
+    describe:
+      "Emit a single JSON result line on stdout (everything else routed to stderr). Also activated by WL_NTT_JSON=1.",
+    type: "boolean",
+    default: false,
+    global: true,
+  })
   .version(
     (() => {
       if (!nttVersion()) return "unknown";

cli/src/output.ts

@@ -0,0 +1,74 @@
+// Structured-output mode for the NTT CLI.
+//
+// Enabled by `--json` (anywhere in argv) or `WL_NTT_JSON=1`. While active,
+// every stdout write is redirected to stderr — the only thing that lands on
+// stdout is the final `{ ok: true, command, data }` line emitted by
+// `emitResult()` at the end of a successful command. Callers (`wl sunrise`,
+// scripts, the future web server) can read the single trailing line and
+// ignore everything else as logs.
+//
+// Failure paths are intentionally unstructured in v1: a non-zero exit code +
+// stderr is the contract. If we ever need typed errors on stdout, add an
+// `{ ok: false, ... }` envelope here.
+
+let mode: "human" | "json" = "human";
+let originalStdoutWrite: typeof process.stdout.write | null = null;
+
+/**
+ * Activate JSON mode if `--json` is in argv or `WL_NTT_JSON=1` is set. Must
+ * run before any command handler logs (called from `side-effects.ts` at
+ * module load time so the hijack lands before any other import has a chance
+ * to write).
+ *
+ * Bun's `console.log` doesn't always route through `process.stdout.write`, so
+ * we override the console methods directly *and* keep a reference to the
+ * original `process.stdout.write` for `emitResult` to use.
+ */
+export function initOutputMode(): void {
+  if (mode === "json") return;
+  const requested =
+    process.env.WL_NTT_JSON === "1" || process.argv.includes("--json");
+  if (!requested) return;
+
+  mode = "json";
+  originalStdoutWrite = process.stdout.write.bind(process.stdout);
+
+  // Redirect console.log / .info / .warn / .debug to stderr. console.error
+  // already goes to stderr; leave it alone.
+  const redirect =
+    (label: string) =>
+    (...args: unknown[]): void => {
+      // Use console.error so chalk / colors keep working and we don't have to
+      // reimplement util.format.
+      console.error(...args);
+    };
+  console.log = redirect("log") as typeof console.log;
+  console.info = redirect("info") as typeof console.info;
+  console.warn = redirect("warn") as typeof console.warn;
+  console.debug = redirect("debug") as typeof console.debug;
+
+  // Belt-and-braces: also hijack process.stdout.write so any direct stdout
+  // write from a transitive dep lands on stderr.
+  process.stdout.write = ((chunk: any, ...rest: any[]): boolean =>
+    (process.stderr.write as any).call(
+      process.stderr,
+      chunk,
+      ...rest
+    )) as typeof process.stdout.write;
+}
+
+export function isJsonMode(): boolean {
+  return mode === "json";
+}
+
+/**
+ * Emit the final `{ ok: true, command, data }` line on stdout. No-op in human
+ * mode. Call this exactly once at the end of a successful command handler.
+ */
+export function emitResult(
+  command: string,
+  data: Record<string, unknown>
+): void {
+  if (mode !== "json" || !originalStdoutWrite) return;
+  originalStdoutWrite(JSON.stringify({ ok: true, command, data }) + "\n");
+}

cli/src/side-effects.ts

@@ -1,3 +1,9 @@
+import { initOutputMode } from "./output";
+
+// Activate `--json` / `WL_NTT_JSON=1` stdout hijack before any other import
+// has a chance to log.
+initOutputMode();
+
 // <sigh>
 // when the native secp256k1 is missing, the eccrypto library decides TO PRINT A MESSAGE TO STDOUT:
 // https://github.com/bitchan/eccrypto/blob/a4f4a5f85ef5aa1776dfa1b7801cad808264a19c/index.js#L23