feat(USE-62): add --output human format with boxen rendering

Co-authored-by: fuxingloh <4266087+fuxingloh@users.noreply.github.com>

Author: Copilot

packages/use-agently/src/cli.ts

@@ -21,7 +21,7 @@ cli
     "Agently is the way AI coordinate and transact. The routing and settlement layer for your agent economy.",
   )
   .version(pkg.version)
-  .option("-o, --output <format>", "Output format (text, json)", process.stdout.isTTY ? "text" : "json")
+  .option("-o, --output <format>", "Output format (human, yaml, json)", process.stdout.isTTY ? "human" : "json")
   .argument("[args...]")
   .action((args: string[]) => {
     if (args.length > 0) {

packages/use-agently/src/commands/agents.test.ts

@@ -67,6 +67,23 @@ describe("agents command", () => {
     expect(Object.keys(lines[0])).toEqual(["id", "name", "description"]);
   });
 
+  test("human output renders items with separator", async () => {
+    await cli.parseAsync(["test", "use-agently", "-o", "human", "agents"]);
+
+    const rendered = out.stdout;
+    expect(rendered).toContain("Test Agent");
+    expect(rendered).toContain("Another Agent");
+    // items are separated by a horizontal rule
+    expect(rendered).toContain("─");
+  });
+
+  test("human output for empty list renders '(no results)'", async () => {
+    fetchSpy.mockResolvedValue(new Response(JSON.stringify({ hits: [], found: 0, page: 1, per_page: 20 })));
+    await cli.parseAsync(["test", "use-agently", "-o", "human", "agents"]);
+
+    expect(out.stdout).toBe("(no results)");
+  });
+
   test("empty agents list", async () => {
     fetchSpy.mockResolvedValue(new Response(JSON.stringify({ hits: [], found: 0, page: 1, per_page: 20 })));
     await cli.parseAsync(["test", "use-agently", "-o", "json", "agents"]);

packages/use-agently/src/commands/doctor.test.ts

@@ -38,7 +38,7 @@ describe("doctor command", () => {
   });
 
   test("all checks pass - text output", async () => {
-    await cli.parseAsync(["test", "use-agently", "doctor", "--rpc", fixture.container.getRpcUrl()]);
+    await cli.parseAsync(["test", "use-agently", "-o", "text", "doctor", "--rpc", fixture.container.getRpcUrl()]);
 
     expect(out.yaml).toEqual({
       ok: true,

packages/use-agently/src/commands/init.test.ts

@@ -45,7 +45,7 @@ describe("init command", () => {
   });
 
   test("text output on new wallet", async () => {
-    await cli.parseAsync(["test", "use-agently", "init"]);
+    await cli.parseAsync(["test", "use-agently", "-o", "text", "init"]);
 
     expect(out.yaml).toEqual({
       address: TEST_ADDRESS,

packages/use-agently/src/commands/update.test.ts

@@ -55,7 +55,7 @@ describe("update command", () => {
   });
 
   test("text output - update available", async () => {
-    await cli.parseAsync(["test", "use-agently", "update"]);
+    await cli.parseAsync(["test", "use-agently", "-o", "text", "update"]);
 
     expect(out.yaml).toEqual({
       current: CURRENT_VERSION,

packages/use-agently/src/commands/view.test.ts

@@ -33,7 +33,7 @@ describe("view command", () => {
 
   test("displays agent details", async () => {
     fetchSpy = spyOn(globalThis, "fetch").mockResolvedValue(new Response(JSON.stringify(TEST_AGENT)));
-    await cli.parseAsync(["test", "use-agently", "view", "eip155:8453/erc8004:0x1234/1"]);
+    await cli.parseAsync(["test", "use-agently", "-o", "text", "view", "eip155:8453/erc8004:0x1234/1"]);
     const parsed = out.yaml as Record<string, unknown>;
     expect(parsed).toHaveProperty("name", "Echo Agent");
     expect(parsed).toHaveProperty("id", "eip155:8453/erc8004:0x1234/1");

packages/use-agently/src/commands/whoami.test.ts

@@ -9,7 +9,7 @@ describe("whoami command", () => {
   const out = captureOutput();
 
   test("text output", async () => {
-    await cli.parseAsync(["test", "use-agently", "whoami"]);
+    await cli.parseAsync(["test", "use-agently", "-o", "text", "whoami"]);
 
     expect(out.yaml).toEqual({
       namespace: "eip155",
@@ -25,4 +25,25 @@ describe("whoami command", () => {
       address: TEST_ADDRESS,
     });
   });
+
+  test("yaml output", async () => {
+    await cli.parseAsync(["test", "use-agently", "-o", "yaml", "whoami"]);
+
+    expect(out.yaml).toEqual({
+      namespace: "eip155",
+      address: TEST_ADDRESS,
+    });
+  });
+
+  test("human output renders a box containing the data", async () => {
+    await cli.parseAsync(["test", "use-agently", "-o", "human", "whoami"]);
+
+    const rendered = out.stdout;
+    expect(rendered).toContain("namespace");
+    expect(rendered).toContain("eip155");
+    expect(rendered).toContain("address");
+    expect(rendered).toContain(TEST_ADDRESS);
+    // boxen uses rounded corners
+    expect(rendered).toMatch(/[╭╰]/);
+  });
 });

packages/use-agently/src/output.ts

@@ -1,30 +1,61 @@
 import { Command } from "commander";
 import { stringify } from "yaml";
+import boxen from "boxen";
 
-export type OutputFormat = "json" | "text";
+export type OutputFormat = "json" | "yaml" | "text" | "human";
 
-export function renderText(data: unknown): string {
+export function renderYaml(data: unknown): string {
   return stringify(data, { lineWidth: 0 }).trimEnd();
 }
 
+/** @deprecated use renderYaml */
+export const renderText = renderYaml;
+
+/**
+ * Render a single value for human consumption.
+ * Strings are returned as-is; objects/arrays are wrapped in a rounded boxen box.
+ */
+export function renderHuman(data: unknown): string {
+  if (typeof data === "string") return data;
+  return boxen(renderYaml(data), { padding: { top: 0, bottom: 0, left: 1, right: 1 }, borderStyle: "round" });
+}
+
+/**
+ * Render a collection for human consumption.
+ * Each item is formatted as YAML and separated by a horizontal rule.
+ */
+export function renderHumanCollection(items: unknown[]): string {
+  if (items.length === 0) return "(no results)";
+  const separator = "─".repeat(40);
+  return items.map((item) => (typeof item === "string" ? item : renderYaml(item))).join(`\n${separator}\n`);
+}
+
 export function output(command: Command, data: unknown): void {
-  if (command.optsWithGlobals().output === "json") {
+  const format: OutputFormat = command.optsWithGlobals().output ?? "human";
+  if (format === "json") {
     console.log(JSON.stringify(data));
+  } else if (format === "human") {
+    console.log(renderHuman(data));
   } else {
-    console.log(renderText(data));
+    // "yaml" or "text" (backward-compat alias)
+    console.log(renderYaml(data));
   }
 }
 
 /**
  * Output a collection as NDJSON (one JSON object per line) in JSON mode,
- * or as YAML text in text mode.
+ * as YAML in yaml/text mode, or as a human-readable list in human mode.
  */
 export function outputCollection(command: Command, items: unknown[]): void {
-  if (command.optsWithGlobals().output === "json") {
+  const format: OutputFormat = command.optsWithGlobals().output ?? "human";
+  if (format === "json") {
     for (const item of items) {
       console.log(JSON.stringify(item));
     }
+  } else if (format === "human") {
+    console.log(renderHumanCollection(items));
   } else {
-    console.log(renderText(items));
+    // "yaml" or "text" (backward-compat alias)
+    console.log(renderYaml(items));
   }
 }