@whatalo/cli-kit 1.0.0

package/dist/output/index.cjs

@@ -0,0 +1,276 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/output/index.ts
+var output_exports = {};
+__export(output_exports, {
+  WhataloAuthError: () => WhataloAuthError,
+  WhataloConfigError: () => WhataloConfigError,
+  WhataloNetworkError: () => WhataloNetworkError,
+  WhataloValidationError: () => WhataloValidationError,
+  banner: () => banner,
+  code: () => code,
+  createSpinner: () => createSpinner,
+  error: () => error,
+  failMissingNonTTYFlags: () => failMissingNonTTYFlags,
+  handleCliError: () => handleCliError,
+  info: () => info,
+  link: () => link,
+  renderInfoPanel: () => renderInfoPanel,
+  renderTable: () => renderTable,
+  renderTasks: () => renderTasks,
+  success: () => success,
+  table: () => table,
+  warn: () => warn,
+  withErrorHandler: () => withErrorHandler
+});
+module.exports = __toCommonJS(output_exports);
+
+// src/output/format.ts
+var import_chalk = __toESM(require("chalk"), 1);
+function banner(title, version) {
+  console.log();
+  console.log(`  ${import_chalk.default.bold.cyan(title)} ${import_chalk.default.dim(`v${version}`)}`);
+  console.log();
+}
+function success(message) {
+  console.log(`  ${import_chalk.default.green("\u2713")} ${message}`);
+}
+function error(message) {
+  console.log(`  ${import_chalk.default.red("\u2717")} ${message}`);
+}
+function warn(message) {
+  console.log(`  ${import_chalk.default.yellow("\u26A0")} ${message}`);
+}
+function info(message) {
+  console.log(`  ${import_chalk.default.blue("\u2139")} ${message}`);
+}
+function link(url) {
+  return import_chalk.default.underline.cyan(url);
+}
+function code(text) {
+  return import_chalk.default.dim("`") + import_chalk.default.bold(text) + import_chalk.default.dim("`");
+}
+function table(headers, rows) {
+  if (headers.length === 0) return;
+  const widths = headers.map(
+    (h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length))
+  );
+  const headerLine = headers.map((h, i) => h.padEnd(widths[i] ?? h.length)).join("  ");
+  console.log(`  ${import_chalk.default.bold(headerLine)}`);
+  const separator = widths.map((w) => "\u2500".repeat(w)).join("  ");
+  console.log(`  ${separator}`);
+  for (const row of rows) {
+    const line = row.map((cell, i) => cell.padEnd(widths[i] ?? cell.length)).join("  ");
+    console.log(`  ${line}`);
+  }
+}
+var STATUS_ICONS = {
+  pending: import_chalk.default.dim("\u25CB"),
+  running: import_chalk.default.cyan("\u25C9"),
+  success: import_chalk.default.green("\u2713"),
+  error: import_chalk.default.red("\u2717"),
+  warning: import_chalk.default.yellow("\u26A0"),
+  skipped: import_chalk.default.dim("\u2013")
+};
+function renderTasks(tasks) {
+  for (const task of tasks) {
+    const icon = STATUS_ICONS[task.status];
+    const label = task.status === "error" ? import_chalk.default.red(task.label) : task.status === "warning" ? import_chalk.default.yellow(task.label) : task.status === "skipped" ? import_chalk.default.dim(task.label) : task.label;
+    console.log(`  ${icon} ${label}`);
+    if (task.detail) {
+      console.log(`    ${import_chalk.default.dim(task.detail)}`);
+    }
+  }
+}
+function renderInfoPanel(title, sections) {
+  console.log();
+  console.log(`  ${import_chalk.default.bold(title)}`);
+  console.log(`  ${"\u2550".repeat(title.length)}`);
+  for (const section of sections) {
+    console.log();
+    console.log(`  ${import_chalk.default.bold.dim(section.heading)}`);
+    const maxKeyLen = Math.max(...section.rows.map((r) => r.key.length));
+    for (const row of section.rows) {
+      console.log(
+        `    ${import_chalk.default.dim(row.key.padEnd(maxKeyLen))}  ${row.value}`
+      );
+    }
+  }
+  console.log();
+}
+function renderTable(options) {
+  table(options.headers, options.rows);
+}
+
+// src/output/spinner.ts
+var import_chalk2 = __toESM(require("chalk"), 1);
+var SPINNER_FRAMES = ["\u25D2", "\u25D0", "\u25D3", "\u25D1"];
+var FRAME_INTERVAL_MS = 100;
+function createSpinner(message) {
+  let frameIndex = 0;
+  let stopped = false;
+  const timer = setInterval(() => {
+    if (stopped) return;
+    const frame = SPINNER_FRAMES[frameIndex % SPINNER_FRAMES.length];
+    process.stdout.write(`\x1B[2K\r  ${import_chalk2.default.magenta(frame)} ${message}`);
+    frameIndex++;
+  }, FRAME_INTERVAL_MS);
+  const firstFrame = SPINNER_FRAMES[0];
+  process.stdout.write(`  ${import_chalk2.default.magenta(firstFrame)} ${message}`);
+  return {
+    stop(finalMessage) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      process.stdout.write(`\x1B[2K\r`);
+      if (finalMessage) {
+        console.log(`  ${import_chalk2.default.green("\u2713")} ${finalMessage}`);
+      }
+    }
+  };
+}
+
+// src/output/errors.ts
+var WhataloAuthError = class extends Error {
+  constructor(message = "Authentication required") {
+    super(message);
+    this.name = "WhataloAuthError";
+  }
+};
+var WhataloConfigError = class extends Error {
+  suggestion;
+  constructor(message, suggestion) {
+    super(message);
+    this.name = "WhataloConfigError";
+    this.suggestion = suggestion;
+  }
+};
+var WhataloNetworkError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "WhataloNetworkError";
+    this.statusCode = statusCode;
+  }
+};
+var WhataloValidationError = class extends Error {
+  field;
+  constructor(message, field) {
+    super(message);
+    this.name = "WhataloValidationError";
+    this.field = field;
+  }
+};
+
+// src/output/error-handler.ts
+function withErrorHandler(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      handleCliError(err);
+    }
+  };
+}
+function handleCliError(error2) {
+  if (error2 instanceof WhataloAuthError) {
+    error(error2.message);
+    info("Run `whatalo login` to re-authenticate.");
+    process.exit(1);
+  }
+  if (error2 instanceof WhataloConfigError) {
+    error(error2.message);
+    if (error2.suggestion) {
+      info(`Fix: ${error2.suggestion}`);
+    }
+    process.exit(2);
+  }
+  if (error2 instanceof WhataloNetworkError) {
+    error("Could not connect to Whatalo API.");
+    if (error2.statusCode === 429) {
+      warn("Rate limit reached. Wait a moment and try again.");
+    } else {
+      info("Check your internet connection and try again.");
+    }
+    if (error2.message && error2.message !== "Could not connect to Whatalo API.") {
+      info(`Details: ${error2.message}`);
+    }
+    process.exit(1);
+  }
+  if (error2 instanceof WhataloValidationError) {
+    error(error2.message);
+    if (error2.field) {
+      info(`Field: ${error2.field}`);
+    }
+    process.exit(1);
+  }
+  error("An unexpected error occurred.");
+  if (error2 instanceof Error) {
+    info(`Details: ${error2.message}`);
+  }
+  info(
+    "If this persists, run `whatalo info --json` and report the issue."
+  );
+  process.exit(1);
+}
+
+// src/output/non-tty.ts
+function failMissingNonTTYFlags(requiredFlags, options) {
+  if (process.stdout.isTTY) return;
+  const missing = requiredFlags.filter((flag) => !options[flag]);
+  if (missing.length > 0) {
+    throw new WhataloValidationError(
+      `${missing.map((f) => `--${f}`).join(", ")} required in non-interactive environments (CI/CD).`,
+      missing[0]
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WhataloAuthError,
+  WhataloConfigError,
+  WhataloNetworkError,
+  WhataloValidationError,
+  banner,
+  code,
+  createSpinner,
+  error,
+  failMissingNonTTYFlags,
+  handleCliError,
+  info,
+  link,
+  renderInfoPanel,
+  renderTable,
+  renderTasks,
+  success,
+  table,
+  warn,
+  withErrorHandler
+});

package/dist/output/index.d.cts

@@ -0,0 +1,149 @@
+/**
+ * Terminal output formatting helpers.
+ * All functions write to stdout. link() and code() return formatted strings
+ * so callers can embed them inside larger messages.
+ */
+/**
+ * Prints a styled banner with the CLI tool name and current version.
+ * Adds blank lines above and below for visual separation.
+ */
+declare function banner(title: string, version: string): void;
+/** Prints a green checkmark success message */
+declare function success(message: string): void;
+/** Prints a red cross error message */
+declare function error(message: string): void;
+/** Prints a yellow warning message */
+declare function warn(message: string): void;
+/** Prints a blue informational message */
+declare function info(message: string): void;
+/**
+ * Returns a styled, underlined URL suitable for terminal hyperlinks.
+ * Use inside success(), info(), or console.log() calls.
+ */
+declare function link(url: string): string;
+/**
+ * Returns an inline monospace-style code fragment.
+ * Use inside larger messages: info(`Run ${code("whatalo login")} to start.`)
+ */
+declare function code(text: string): string;
+/**
+ * Renders a simple text table with a bold header row and separator line.
+ * Column widths are computed from the widest value in each column.
+ *
+ * @param headers - Column header labels
+ * @param rows    - Data rows; each inner array must align with headers
+ */
+declare function table(headers: string[], rows: string[][]): void;
+type TaskStatus = "pending" | "running" | "success" | "error" | "warning" | "skipped";
+/**
+ * Renders a multi-step task list with status indicators.
+ * Used by validate, init, and other multi-step commands.
+ */
+declare function renderTasks(tasks: Array<{
+    label: string;
+    status: TaskStatus;
+    detail?: string;
+}>): void;
+/**
+ * Renders a key-value info panel with titled sections.
+ * Used by `whatalo info` for structured project display.
+ */
+declare function renderInfoPanel(title: string, sections: Array<{
+    heading: string;
+    rows: Array<{
+        key: string;
+        value: string;
+    }>;
+}>): void;
+/**
+ * Renders a table with headers and aligned columns.
+ * Truncates cells to fit within maxWidth when specified.
+ */
+declare function renderTable(options: {
+    headers: string[];
+    rows: string[][];
+    maxWidth?: number;
+}): void;
+
+/**
+ * Lightweight terminal spinner using raw ANSI escape codes.
+ *
+ * Unlike @clack/prompts spinner, this correctly overwrites a single line
+ * when used inside long-running polling loops (e.g. Device Flow).
+ */
+interface Spinner {
+    /** Stops the spinner and replaces the animated line with a static message */
+    stop(finalMessage?: string): void;
+}
+/**
+ * Creates and immediately starts an animated terminal spinner.
+ *
+ * Uses `process.stdout.write` with carriage return (`\r`) and ANSI
+ * clear-line (`\x1b[2K`) to overwrite a single line. This avoids the
+ * "repeating lines" issue that occurs with @clack/prompts spinner
+ * when the event loop yields between frames (e.g. during HTTP polling).
+ *
+ * @param message - The message to display while the spinner is running
+ * @returns A Spinner handle with a stop() method
+ *
+ * @example
+ * const s = createSpinner("Building plugin...");
+ * await runBuild();
+ * s.stop("Build complete");
+ */
+declare function createSpinner(message: string): Spinner;
+
+/**
+ * Custom error classes for structured CLI error handling.
+ * Each error type maps to a specific recovery action shown to the developer.
+ */
+declare class WhataloAuthError extends Error {
+    constructor(message?: string);
+}
+declare class WhataloConfigError extends Error {
+    suggestion?: string;
+    constructor(message: string, suggestion?: string);
+}
+declare class WhataloNetworkError extends Error {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+declare class WhataloValidationError extends Error {
+    field?: string;
+    constructor(message: string, field?: string);
+}
+
+/**
+ * Unified error handler for all CLI commands.
+ * Catches any thrown error, formats it with actionable suggestions,
+ * and exits with the appropriate code.
+ */
+/**
+ * Wraps a CLI command action with structured error handling.
+ * Use as the `.action()` callback for Commander commands.
+ *
+ * @example
+ * program.command("validate").action(withErrorHandler(async () => { ... }));
+ */
+declare function withErrorHandler<T extends unknown[]>(fn: (...args: T) => Promise<void>): (...args: T) => Promise<void>;
+/**
+ * Formats and displays a CLI error, then exits with the correct code.
+ * Exit codes: 1 = recoverable error, 2 = fatal/config error.
+ */
+declare function handleCliError(error: unknown): never;
+
+/**
+ * Non-TTY flag enforcement for CI/CD environments.
+ * Prevents silent failures in pipelines by requiring explicit flags
+ * for commands that would otherwise need interactive confirmation.
+ */
+/**
+ * Fail fast if running in non-TTY and required flags are missing.
+ * Used by commands that need confirmation (deploy, env pull).
+ *
+ * @param requiredFlags - Flag names that must be present in non-TTY
+ * @param options - Parsed command options from Commander
+ */
+declare function failMissingNonTTYFlags(requiredFlags: string[], options: Record<string, unknown>): void;
+
+export { type Spinner, type TaskStatus, WhataloAuthError, WhataloConfigError, WhataloNetworkError, WhataloValidationError, banner, code, createSpinner, error, failMissingNonTTYFlags, handleCliError, info, link, renderInfoPanel, renderTable, renderTasks, success, table, warn, withErrorHandler };

package/dist/output/index.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Terminal output formatting helpers.
+ * All functions write to stdout. link() and code() return formatted strings
+ * so callers can embed them inside larger messages.
+ */
+/**
+ * Prints a styled banner with the CLI tool name and current version.
+ * Adds blank lines above and below for visual separation.
+ */
+declare function banner(title: string, version: string): void;
+/** Prints a green checkmark success message */
+declare function success(message: string): void;
+/** Prints a red cross error message */
+declare function error(message: string): void;
+/** Prints a yellow warning message */
+declare function warn(message: string): void;
+/** Prints a blue informational message */
+declare function info(message: string): void;
+/**
+ * Returns a styled, underlined URL suitable for terminal hyperlinks.
+ * Use inside success(), info(), or console.log() calls.
+ */
+declare function link(url: string): string;
+/**
+ * Returns an inline monospace-style code fragment.
+ * Use inside larger messages: info(`Run ${code("whatalo login")} to start.`)
+ */
+declare function code(text: string): string;
+/**
+ * Renders a simple text table with a bold header row and separator line.
+ * Column widths are computed from the widest value in each column.
+ *
+ * @param headers - Column header labels
+ * @param rows    - Data rows; each inner array must align with headers
+ */
+declare function table(headers: string[], rows: string[][]): void;
+type TaskStatus = "pending" | "running" | "success" | "error" | "warning" | "skipped";
+/**
+ * Renders a multi-step task list with status indicators.
+ * Used by validate, init, and other multi-step commands.
+ */
+declare function renderTasks(tasks: Array<{
+    label: string;
+    status: TaskStatus;
+    detail?: string;
+}>): void;
+/**
+ * Renders a key-value info panel with titled sections.
+ * Used by `whatalo info` for structured project display.
+ */
+declare function renderInfoPanel(title: string, sections: Array<{
+    heading: string;
+    rows: Array<{
+        key: string;
+        value: string;
+    }>;
+}>): void;
+/**
+ * Renders a table with headers and aligned columns.
+ * Truncates cells to fit within maxWidth when specified.
+ */
+declare function renderTable(options: {
+    headers: string[];
+    rows: string[][];
+    maxWidth?: number;
+}): void;
+
+/**
+ * Lightweight terminal spinner using raw ANSI escape codes.
+ *
+ * Unlike @clack/prompts spinner, this correctly overwrites a single line
+ * when used inside long-running polling loops (e.g. Device Flow).
+ */
+interface Spinner {
+    /** Stops the spinner and replaces the animated line with a static message */
+    stop(finalMessage?: string): void;
+}
+/**
+ * Creates and immediately starts an animated terminal spinner.
+ *
+ * Uses `process.stdout.write` with carriage return (`\r`) and ANSI
+ * clear-line (`\x1b[2K`) to overwrite a single line. This avoids the
+ * "repeating lines" issue that occurs with @clack/prompts spinner
+ * when the event loop yields between frames (e.g. during HTTP polling).
+ *
+ * @param message - The message to display while the spinner is running
+ * @returns A Spinner handle with a stop() method
+ *
+ * @example
+ * const s = createSpinner("Building plugin...");
+ * await runBuild();
+ * s.stop("Build complete");
+ */
+declare function createSpinner(message: string): Spinner;
+
+/**
+ * Custom error classes for structured CLI error handling.
+ * Each error type maps to a specific recovery action shown to the developer.
+ */
+declare class WhataloAuthError extends Error {
+    constructor(message?: string);
+}
+declare class WhataloConfigError extends Error {
+    suggestion?: string;
+    constructor(message: string, suggestion?: string);
+}
+declare class WhataloNetworkError extends Error {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+declare class WhataloValidationError extends Error {
+    field?: string;
+    constructor(message: string, field?: string);
+}
+
+/**
+ * Unified error handler for all CLI commands.
+ * Catches any thrown error, formats it with actionable suggestions,
+ * and exits with the appropriate code.
+ */
+/**
+ * Wraps a CLI command action with structured error handling.
+ * Use as the `.action()` callback for Commander commands.
+ *
+ * @example
+ * program.command("validate").action(withErrorHandler(async () => { ... }));
+ */
+declare function withErrorHandler<T extends unknown[]>(fn: (...args: T) => Promise<void>): (...args: T) => Promise<void>;
+/**
+ * Formats and displays a CLI error, then exits with the correct code.
+ * Exit codes: 1 = recoverable error, 2 = fatal/config error.
+ */
+declare function handleCliError(error: unknown): never;
+
+/**
+ * Non-TTY flag enforcement for CI/CD environments.
+ * Prevents silent failures in pipelines by requiring explicit flags
+ * for commands that would otherwise need interactive confirmation.
+ */
+/**
+ * Fail fast if running in non-TTY and required flags are missing.
+ * Used by commands that need confirmation (deploy, env pull).
+ *
+ * @param requiredFlags - Flag names that must be present in non-TTY
+ * @param options - Parsed command options from Commander
+ */
+declare function failMissingNonTTYFlags(requiredFlags: string[], options: Record<string, unknown>): void;
+
+export { type Spinner, type TaskStatus, WhataloAuthError, WhataloConfigError, WhataloNetworkError, WhataloValidationError, banner, code, createSpinner, error, failMissingNonTTYFlags, handleCliError, info, link, renderInfoPanel, renderTable, renderTasks, success, table, warn, withErrorHandler };