@jango-blockchained/hoox-cli 0.3.4

package/src/utils/formatters.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test";
+import {
+  formatSuccess,
+  formatError,
+  formatTable,
+  formatJson,
+  formatKeyValue,
+} from "./formatters.js";
+import { CLIError, ExitCode } from "./errors.js";
+
+/**
+ * Helper: captures everything written to process.stdout.write into a string.
+ * Returns a cleanup function that restores the original write.
+ */
+function captureStdout(): { output: () => string; restore: () => void } {
+  const chunks: string[] = [];
+  const originalWrite = process.stdout.write.bind(process.stdout);
+  const writeMock = mock((chunk: string | Buffer) => {
+    chunks.push(typeof chunk === "string" ? chunk : chunk.toString());
+    return true;
+  });
+  process.stdout.write = writeMock as unknown as typeof process.stdout.write;
+
+  return {
+    output: () => chunks.join(""),
+    restore: () => {
+      process.stdout.write = originalWrite;
+    },
+  };
+}
+
+describe("formatSuccess", () => {
+  let capture: ReturnType<typeof captureStdout>;
+
+  beforeEach(() => {
+    capture = captureStdout();
+  });
+
+  afterEach(() => {
+    capture.restore();
+  });
+
+  it("outputs human-formatted success", () => {
+    formatSuccess("Deploy complete");
+    const out = capture.output();
+    expect(out).toContain("✓");
+
+    // Check status indicator is present (just the checkmark)
+    expect(out).toContain("✓");
+    expect(out).not.toContain("✗");
+  });
+});
+
+describe("formatTable", () => {
+  let capture: ReturnType<typeof captureStdout>;
+
+  beforeEach(() => {
+    capture = captureStdout();
+  });
+
+  afterEach(() => {
+    capture.restore();
+  });
+
+  const sampleRows = [
+    { name: "alpha", status: "ok" },
+    { name: "beta-long", status: "error" },
+  ];
+
+  it("outputs human-formatted table with box drawing", () => {
+    formatTable(sampleRows);
+    const out = capture.output();
+    expect(out).toContain("┌");
+    expect(out).toContain("┬");
+    expect(out).toContain("┐");
+    expect(out).toContain("├");
+    expect(out).toContain("┼");
+    expect(out).toContain("┤");
+    expect(out).toContain("└");
+    expect(out).toContain("┴");
+    expect(out).toContain("┘");
+    expect(out).toContain("alpha");
+    expect(out).toContain("beta-long");
+    expect(out).toContain("ok");
+    expect(out).toContain("error");
+  });
+
+  it("outputs JSON array when json=true", () => {
+    formatTable(sampleRows, { json: true });
+    const out = capture.output();
+    const parsed = JSON.parse(out);
+    expect(parsed).toEqual(sampleRows);
+  });
+
+  it("outputs nothing when quiet=true", () => {
+    formatTable(sampleRows, { quiet: true });
+    expect(capture.output()).toBe("");
+  });
+
+  it("outputs (empty) for empty rows", () => {
+    formatTable([]);
+    const out = capture.output();
+    expect(out).toContain("(empty)");
+    expect(out).not.toContain("┌");
+  });
+});
+
+describe("formatJson", () => {
+  let capture: ReturnType<typeof captureStdout>;
+
+  beforeEach(() => {
+    capture = captureStdout();
+  });
+
+  afterEach(() => {
+    capture.restore();
+  });
+
+  it("outputs pretty JSON by default", () => {
+    formatJson({ key: "value" });
+    const out = capture.output();
+    const parsed = JSON.parse(out);
+    expect(parsed).toEqual({ key: "value" });
+    // Pretty-printed: contains newlines and indentation
+    expect(out).toContain("\n");
+    expect(out).toContain('"key"');
+  });
+
+  it("outputs compact JSON when quiet=true", () => {
+    formatJson({ key: "value" }, { quiet: true });
+    const out = capture.output();
+    const parsed = JSON.parse(out);
+    expect(parsed).toEqual({ key: "value" });
+    // Compact: single line of content (console.log appends newline)
+    expect(out.trim()).not.toContain("\n");
+  });
+
+  it("outputs pretty JSON when json=true", () => {
+    formatJson({ key: "value" }, { json: true });
+    const out = capture.output();
+    expect(out).toContain("\n");
+  });
+});
+
+describe("formatKeyValue", () => {
+  let capture: ReturnType<typeof captureStdout>;
+
+  beforeEach(() => {
+    capture = captureStdout();
+  });
+
+  afterEach(() => {
+    capture.restore();
+  });
+
+  const pairs = { Name: "alpha", Status: "running", Region: "us-east" };
+
+  it("outputs human-formatted key-value pairs", () => {
+    formatKeyValue(pairs);
+    const out = capture.output();
+    expect(out).toContain("Name");
+    expect(out).toContain("alpha");
+    expect(out).toContain("Status");
+    expect(out).toContain("running");
+    expect(out).toContain("Region");
+    expect(out).toContain("us-east");
+  });
+
+  it("outputs JSON object when json=true", () => {
+    formatKeyValue(pairs, { json: true });
+    const out = capture.output();
+    const parsed = JSON.parse(out);
+    expect(parsed).toEqual(pairs);
+  });
+
+  it("outputs nothing when quiet=true", () => {
+    formatKeyValue(pairs, { quiet: true });
+    expect(capture.output()).toBe("");
+  });
+});

package/src/utils/formatters.ts

@@ -0,0 +1,252 @@
+/**
+ * Output formatters for the Hoox CLI.
+ * Each function respects --json / --quiet flags passed via FormatOptions.
+ * Human-readable mode uses ansis styling from the theme.
+ */
+
+import { CLIError, ExitCode } from "./errors.js";
+import { theme, icons, stripAnsi, hr } from "./theme.js";
+
+export interface FormatOptions {
+  json?: boolean;
+  quiet?: boolean;
+}
+
+// ── Progress bar ──────────────────────────────────────────────────
+
+const PROGRESS_BAR_WIDTH = 30;
+
+/**
+ * Render an inline progress bar string.
+ * @param current  Current step (0-based)
+ * @param total    Total steps
+ * @param opts     Width override
+ */
+export function renderProgressBar(
+  current: number,
+  total: number,
+  opts?: { width?: number }
+): string {
+  const width = opts?.width ?? PROGRESS_BAR_WIDTH;
+  const ratio = total > 0 ? Math.min(current / total, 1) : 0;
+  const filled = Math.round(width * ratio);
+  const empty = width - filled;
+  const pct = Math.round(ratio * 100);
+
+  const bar =
+    theme.accent("[") +
+    theme.success("█".repeat(filled)) +
+    theme.dim("░".repeat(empty)) +
+    theme.accent("]") +
+    ` ${pct}%`;
+
+  return bar;
+}
+
+/**
+ * Render a multi-line progress display for sequential steps.
+ * Returns lines suitable for overwriting via \r or manual clear.
+ */
+export function renderStepProgress(
+  steps: Array<{ name: string; status: "pending" | "running" | "done" | "failed" }>
+): string {
+  const iconMap: Record<string, string> = {
+    pending: theme.dim("○"),
+    running: theme.info("◌"),
+    done: theme.success("●"),
+    failed: theme.error("✗"),
+  };
+
+  return steps
+    .map((s) => `  ${iconMap[s.status]} ${theme.bold(s.name)}`)
+    .join("\n");
+}
+
+// ── Basic output ──────────────────────────────────────────────────
+
+/**
+ * Output a success message.
+ * - JSON mode:  {"success":true,"message":"..."}
+ * - Quiet mode: prints nothing
+ * - Human mode: green "✓ message"
+ */
+export function formatSuccess(message: string, opts?: FormatOptions): void {
+  if (opts?.quiet) return;
+
+  if (opts?.json) {
+    process.stdout.write(JSON.stringify({ success: true, message }) + "\n");
+    return;
+  }
+
+  process.stdout.write(`${theme.success(icons.success)} ${message}\n`);
+}
+
+/**
+ * Output an error message.
+ * - JSON mode:  {"success":false,"error":"...","code":1,"details":"..."}
+ * - Quiet mode: prints only the error message (no icon)
+ * - Human mode: red "✗ message" + optional details indented
+ */
+export function formatError(error: Error | string, opts?: FormatOptions): void {
+  const message = typeof error === "string" ? error : error.message;
+  const cliError = error instanceof CLIError ? error : null;
+
+  if (opts?.json) {
+    const output: Record<string, unknown> = {
+      success: false,
+      error: message,
+      code: cliError?.code ?? ExitCode.ERROR,
+    };
+    if (cliError?.details) {
+      output.details = cliError.details;
+    }
+    process.stdout.write(JSON.stringify(output) + "\n");
+    return;
+  }
+
+  if (opts?.quiet) {
+    process.stdout.write(`${message}\n`);
+    return;
+  }
+
+  process.stdout.write(`${theme.error(icons.error)} ${message}\n`);
+
+  if (cliError?.details) {
+    process.stdout.write(`  ${theme.dim(cliError.details)}\n`);
+  }
+}
+
+/**
+ * Output tabular data with enhanced box-drawing borders.
+ * - JSON mode:  JSON array of objects
+ * - Quiet mode: prints nothing
+ * - Human mode: themed box-drawn table with column headers
+ */
+export function formatTable(
+  rows: Record<string, string>[],
+  opts?: FormatOptions
+): void {
+  if (opts?.quiet) return;
+
+  if (opts?.json) {
+    process.stdout.write(JSON.stringify(rows, null, 2) + "\n");
+    return;
+  }
+
+  if (rows.length === 0) {
+    process.stdout.write(`${theme.dim("(empty)")}\n`);
+    return;
+  }
+
+  // Collect all keys in display order (first row defines column order)
+  const keys = Object.keys(rows[0]);
+
+  // Calculate column widths
+  const widths: Record<string, number> = {};
+  for (const key of keys) {
+    widths[key] = stripAnsi(key).length;
+    for (const row of rows) {
+      const value = row[key] ?? "";
+      const stripped = stripAnsi(value).length;
+      widths[key] = Math.max(widths[key], stripped);
+    }
+  }
+
+  // Build border segments
+  const topParts = keys.map((k) => "─".repeat(widths[k] + 2));
+  const topBorder = `┌${topParts.join("┬")}┐`;
+  const sepBorder = `├${topParts.join("┼")}┤`;
+  const botBorder = `└${topParts.join("┴")}┘`;
+
+  // Header row with themed styling
+  const headerCells = keys.map((k) =>
+    theme.bold(k.padEnd(widths[k])).toString()
+  );
+  const headerRow = `│ ${headerCells.join(" │ ")} │`;
+
+  // Data rows
+  const dataRows = rows.map((row) => {
+    const cells = keys.map((k) => {
+      const value = row[k] ?? "";
+      return value.padEnd(widths[k]);
+    });
+    return `│ ${cells.join(" │ ")} │`;
+  });
+
+  process.stdout.write(
+    `${theme.dim(topBorder)}\n` +
+      `${headerRow}\n` +
+      `${theme.dim(sepBorder)}\n` +
+      `${dataRows.join("\n")}\n` +
+      `${theme.dim(botBorder)}\n`
+  );
+}
+
+/**
+ * Output arbitrary data as JSON.
+ * - JSON / Quiet mode: JSON stringified (compact or pretty)
+ * - Human mode:    JSON with 2-space indent
+ */
+export function formatJson(data: unknown, opts?: FormatOptions): void {
+  const json = opts?.quiet
+    ? JSON.stringify(data)
+    : JSON.stringify(data, null, 2);
+
+  process.stdout.write(`${json}\n`);
+}
+
+/**
+ * Output key-value pairs.
+ * - JSON mode:  JSON object
+ * - Quiet mode: prints nothing
+ * - Human mode: "label: value" with themed labels
+ */
+export function formatKeyValue(
+  pairs: Record<string, string>,
+  opts?: FormatOptions
+): void {
+  if (opts?.quiet) return;
+
+  if (opts?.json) {
+    process.stdout.write(JSON.stringify(pairs, null, 2) + "\n");
+    return;
+  }
+
+  const maxKeyLen = Math.max(...Object.keys(pairs).map((k) => stripAnsi(k).length));
+
+  for (const [key, value] of Object.entries(pairs)) {
+    const paddedKey = key.padEnd(maxKeyLen);
+    process.stdout.write(`  ${theme.key(paddedKey)} ${theme.dim(":")} ${value}\n`);
+  }
+}
+
+/**
+ * Output a section header with decorative separator.
+ */
+export function formatHeader(text: string, opts?: FormatOptions): void {
+  if (opts?.quiet) return;
+  if (opts?.json) return;
+
+  process.stdout.write(`\n${theme.heading(text)}\n`);
+  process.stdout.write(`${hr()}\n`);
+}
+
+/**
+ * Output a bullet-point list with optional icon per item.
+ */
+export function formatList(
+  items: string[],
+  opts?: { icon?: string; json?: boolean; quiet?: boolean }
+): void {
+  if (opts?.quiet) return;
+
+  if (opts?.json) {
+    process.stdout.write(JSON.stringify(items, null, 2) + "\n");
+    return;
+  }
+
+  const icon = opts?.icon ?? icons.arrow;
+  for (const item of items) {
+    process.stdout.write(`  ${icon} ${item}\n`);
+  }
+}

package/src/utils/theme.ts

@@ -0,0 +1,94 @@
+/**
+ * Hoox CLI theme — ansis color palette, icons, and visual primitives.
+ * Used by formatters and commands for consistent terminal output.
+ */
+
+import ansis from "ansis";
+
+// ── Color primitives ──────────────────────────────────────────────
+const green = ansis.green;
+const red = ansis.red;
+const yellow = ansis.yellow;
+const blue = ansis.blue;
+const cyan = ansis.cyan;
+const magenta = ansis.magenta;
+const dim = ansis.dim;
+const bold = ansis.bold;
+const italic = ansis.italic;
+const underline = ansis.underline;
+const gray = ansis.gray;
+const white = ansis.white;
+const black = ansis.black;
+const bgGreen = ansis.bgGreen;
+const bgRed = ansis.bgRed;
+const bgYellow = ansis.bgYellow;
+const bgBlue = ansis.bgBlue;
+
+// ── Semantic theme ────────────────────────────────────────────────
+export const theme = {
+  success: green,
+  error: red,
+  warning: yellow,
+  info: blue,
+  accent: cyan,
+  highlight: magenta,
+  dim,
+  bold,
+  italic,
+  underline,
+  gray,
+  white,
+  black,
+  heading: bold.cyan,
+  label: dim,
+  subtle: gray,
+  muted: dim.gray,
+  value: bold.white,
+  key: dim.yellow,
+
+  // Status-specific
+  statusOk: bgGreen.black(" OK "),
+  statusWarn: bgYellow.black(" WARN "),
+  statusError: bgRed.white(" FAIL "),
+  statusInfo: bgBlue.white(" INFO "),
+
+  // Decorations
+  separator: dim("─"),
+  pipe: dim("│"),
+  corner: dim("┌┐└┘"),
+};
+
+// ── Icons ─────────────────────────────────────────────────────────
+export const icons = {
+  success: "✓",
+  error: "✗",
+  warning: "!",
+  info: "i",
+  arrow: "->",
+  spinner: ["-", "\\", "|", "/"],
+  dot: "●",
+  check: "v",
+  cross: "x",
+};
+
+// ── Display helpers ───────────────────────────────────────────────
+
+/** Strip ANSI escape codes from a string. */
+export function stripAnsi(str: string): string {
+  return ansis.strip(str);
+}
+
+/** Render a horizontal rule using the separator character. */
+export function hr(width: number = 60): string {
+  return theme.separator.repeat(width);
+}
+
+/** Format a key-value pair for aligned output. */
+export function kv(key: string, value: string): string {
+  return `${theme.key(key)} ${theme.dim(":")} ${theme.value(value)}`;
+}
+
+/** Format a labeled value. */
+export function tagged(label: string, value: string): string {
+  return `${theme.key(label)} ${theme.dim(":")} ${theme.value(value)}`;
+}