@jango-blockchained/hoox-cli 0.5.1 → 0.5.6

package/src/utils/errors.test.ts

@@ -1,69 +0,0 @@
-import { describe, it, expect } from "bun:test";
-import { CLIError, ExitCode } from "./errors.js";
-
-// CommandItem is defined in errors.js and re-exported; avoid redeclare
-
-describe("ExitCode", () => {
-  it("has correct numeric values", () => {
-    expect(ExitCode.SUCCESS).toBe(0);
-    expect(ExitCode.ERROR).toBe(1);
-    expect(ExitCode.INVALID_USAGE).toBe(2);
-    expect(ExitCode.INFRA_UNAVAILABLE).toBe(3);
-  });
-
-  it("is a numeric enum with expected values", () => {
-    expect(ExitCode.SUCCESS).toBe(0);
-    expect(ExitCode.ERROR).toBe(1);
-    expect(ExitCode.INVALID_USAGE).toBe(2);
-    expect(ExitCode.INFRA_UNAVAILABLE).toBe(3);
-    // All values are distinct
-    const values = [
-      ExitCode.SUCCESS,
-      ExitCode.ERROR,
-      ExitCode.INVALID_USAGE,
-      ExitCode.INFRA_UNAVAILABLE,
-    ];
-    expect(new Set(values).size).toBe(4);
-  });
-});
-
-describe("CLIError", () => {
-  it("constructs with message and defaults", () => {
-    const err = new CLIError("something went wrong");
-    expect(err).toBeInstanceOf(Error);
-    expect(err).toBeInstanceOf(CLIError);
-    expect(err.name).toBe("CLIError");
-    expect(err.message).toBe("something went wrong");
-    expect(err.code).toBe(ExitCode.ERROR);
-    expect(err.details).toBeUndefined();
-    expect(err.recoverable).toBe(false);
-  });
-
-  it("constructs with all fields", () => {
-    const err = new CLIError(
-      "invalid input",
-      ExitCode.INVALID_USAGE,
-      "Expected --name to be a non-empty string",
-      true
-    );
-    expect(err.message).toBe("invalid input");
-    expect(err.code).toBe(ExitCode.INVALID_USAGE);
-    expect(err.details).toBe("Expected --name to be a non-empty string");
-    expect(err.recoverable).toBe(true);
-  });
-
-  it("supports INFRA_UNAVAILABLE code", () => {
-    const err = new CLIError(
-      "Cloudflare API unreachable",
-      ExitCode.INFRA_UNAVAILABLE,
-      "Check your network or try again later"
-    );
-    expect(err.code).toBe(3);
-    expect(err.recoverable).toBe(false);
-  });
-
-  it("has a string representation that includes the name", () => {
-    const err = new CLIError("fail");
-    expect(err.toString()).toBe("CLIError: fail");
-  });
-});

package/src/utils/errors.ts

@@ -1,23 +0,0 @@
-/**
- * CLIError — structured error class for the Hoox CLI.
- * Provides exit codes, optional details, and recoverable flag.
- */
-
-export const enum ExitCode {
-  SUCCESS = 0,
-  ERROR = 1,
-  INVALID_USAGE = 2,
-  INFRA_UNAVAILABLE = 3,
-}
-
-export class CLIError extends Error {
-  constructor(
-    message: string,
-    public readonly code: ExitCode = ExitCode.ERROR,
-    public readonly details?: string,
-    public readonly recoverable = false
-  ) {
-    super(message);
-    this.name = "CLIError";
-  }
-}

package/src/utils/formatters.test.ts

@@ -1,180 +0,0 @@
-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

@@ -1,269 +0,0 @@
-/**
- * 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";
-import { Command } from "commander";
-
-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`);
-  }
-}
-
-/**
- * Build the format options for output, reading global --json / --quiet flags.
- * Uses `optsWithGlobals()` to include options inherited from the top-level program.
- */
-export function getFormatOptions(cmd: Command): FormatOptions {
-  const opts = cmd.optsWithGlobals();
-  return { json: Boolean(opts.json), quiet: Boolean(opts.quiet) };
-}

package/src/utils/theme.ts

@@ -1,94 +0,0 @@
-/**
- * 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)}`;
-}