@enactprotocol/cli 1.2.8 → 2.0.0

package/src/utils/index.ts

@@ -0,0 +1,107 @@
+/**
+ * CLI utilities
+ */
+
+// Output formatting
+export {
+  colors,
+  symbols,
+  success,
+  error,
+  warning,
+  info,
+  dim,
+  newline,
+  header,
+  keyValue,
+  listItem,
+  table,
+  json,
+  jsonCompact,
+  formatError,
+  errorWithDetails,
+  suggest,
+  status,
+  clearLine,
+  type TableColumn,
+} from "./output";
+
+// Spinner and prompts
+export {
+  createSpinner,
+  withSpinner,
+  intro,
+  outro,
+  confirm,
+  text,
+  password,
+  select,
+  isCancel,
+  cancel,
+  log,
+  logInfo,
+  logSuccess,
+  logWarning,
+  logError,
+  logStep,
+  type SpinnerInstance,
+} from "./spinner";
+
+// Exit codes
+export {
+  EXIT_SUCCESS,
+  EXIT_FAILURE,
+  EXIT_USAGE,
+  EXIT_DATAERR,
+  EXIT_NOINPUT,
+  EXIT_NOUSER,
+  EXIT_NOHOST,
+  EXIT_UNAVAILABLE,
+  EXIT_SOFTWARE,
+  EXIT_OSERR,
+  EXIT_OSFILE,
+  EXIT_CANTCREAT,
+  EXIT_IOERR,
+  EXIT_TEMPFAIL,
+  EXIT_PROTOCOL,
+  EXIT_NOPERM,
+  EXIT_CONFIG,
+  EXIT_TOOL_NOT_FOUND,
+  EXIT_MANIFEST_ERROR,
+  EXIT_EXECUTION_ERROR,
+  EXIT_TIMEOUT,
+  EXIT_TRUST_ERROR,
+  EXIT_REGISTRY_ERROR,
+  EXIT_AUTH_ERROR,
+  EXIT_VALIDATION_ERROR,
+  EXIT_NETWORK_ERROR,
+  EXIT_CONTAINER_ERROR,
+  getExitCodeDescription,
+  exit,
+  exitSuccess,
+  exitFailure,
+} from "./exit-codes";
+
+// Error handling
+export {
+  CliError,
+  ToolNotFoundError,
+  ManifestError,
+  ValidationError,
+  AuthError,
+  NetworkError,
+  RegistryError,
+  TrustError,
+  TimeoutError,
+  ExecutionError,
+  ContainerError,
+  FileNotFoundError,
+  PermissionError,
+  ConfigError,
+  UsageError,
+  handleError,
+  withErrorHandling,
+  categorizeError,
+  ErrorMessages,
+  printErrorWithSuggestions,
+} from "./errors";

package/src/utils/output.ts

@@ -0,0 +1,242 @@
+/**
+ * Output utilities for CLI
+ *
+ * Provides consistent formatting, colors, and output helpers
+ */
+
+import pc from "picocolors";
+
+// ============================================================================
+// Colors and Formatting
+// ============================================================================
+
+export const colors = {
+  // Status colors
+  success: pc.green,
+  error: pc.red,
+  warning: pc.yellow,
+  info: pc.blue,
+  dim: pc.dim,
+  bold: pc.bold,
+
+  // Semantic colors
+  command: pc.cyan,
+  path: pc.underline,
+  value: pc.yellow,
+  key: pc.bold,
+  version: pc.magenta,
+};
+
+// ============================================================================
+// Symbols
+// ============================================================================
+
+export const symbols = {
+  success: pc.green("✓"),
+  error: pc.red("✗"),
+  warning: pc.yellow("⚠"),
+  info: pc.blue("ℹ"),
+  arrow: pc.dim("→"),
+  bullet: pc.dim("•"),
+  check: pc.green("✔"),
+  cross: pc.red("✘"),
+};
+
+// ============================================================================
+// Output Functions
+// ============================================================================
+
+/**
+ * Print a success message
+ */
+export function success(message: string): void {
+  console.log(`${symbols.success} ${message}`);
+}
+
+/**
+ * Print an error message
+ */
+export function error(message: string): void {
+  console.error(`${symbols.error} ${colors.error(message)}`);
+}
+
+/**
+ * Print a warning message
+ */
+export function warning(message: string): void {
+  console.warn(`${symbols.warning} ${colors.warning(message)}`);
+}
+
+/**
+ * Print an info message
+ */
+export function info(message: string): void {
+  console.log(`${symbols.info} ${message}`);
+}
+
+/**
+ * Print a dim/subtle message
+ */
+export function dim(message: string): void {
+  console.log(colors.dim(message));
+}
+
+/**
+ * Print a newline
+ */
+export function newline(): void {
+  console.log();
+}
+
+/**
+ * Print a header
+ */
+export function header(text: string): void {
+  console.log();
+  console.log(colors.bold(text));
+  console.log(colors.dim("─".repeat(text.length)));
+}
+
+/**
+ * Print a key-value pair
+ */
+export function keyValue(key: string, value: string, indent = 0): void {
+  const padding = " ".repeat(indent);
+  console.log(`${padding}${colors.key(key)}: ${value}`);
+}
+
+/**
+ * Print a list item
+ */
+export function listItem(text: string, indent = 0): void {
+  const padding = " ".repeat(indent);
+  console.log(`${padding}${symbols.bullet} ${text}`);
+}
+
+// ============================================================================
+// Tables
+// ============================================================================
+
+export interface TableColumn {
+  key: string;
+  header: string;
+  width?: number;
+  align?: "left" | "right" | "center";
+}
+
+/**
+ * Print a simple table
+ */
+export function table<T extends Record<string, unknown>>(data: T[], columns: TableColumn[]): void {
+  if (data.length === 0) {
+    dim("  No items to display");
+    return;
+  }
+
+  // Calculate column widths
+  const widths = columns.map((col) => {
+    const headerWidth = col.header.length;
+    const maxDataWidth = Math.max(...data.map((row) => String(row[col.key] ?? "").length));
+    return col.width ?? Math.max(headerWidth, maxDataWidth);
+  });
+
+  // Print header
+  const headerLine = columns
+    .map((col, i) => pad(col.header, widths[i] ?? col.header.length, col.align))
+    .join("  ");
+  console.log(colors.bold(headerLine));
+  console.log(colors.dim("─".repeat(headerLine.length)));
+
+  // Print rows
+  for (const row of data) {
+    const line = columns
+      .map((col, i) => pad(String(row[col.key] ?? ""), widths[i] ?? 10, col.align))
+      .join("  ");
+    console.log(line);
+  }
+}
+
+function pad(text: string, width: number, align: "left" | "right" | "center" = "left"): string {
+  const padding = width - text.length;
+  if (padding <= 0) return text.slice(0, width);
+
+  switch (align) {
+    case "right":
+      return " ".repeat(padding) + text;
+    case "center": {
+      const left = Math.floor(padding / 2);
+      const right = padding - left;
+      return " ".repeat(left) + text + " ".repeat(right);
+    }
+    default:
+      return text + " ".repeat(padding);
+  }
+}
+
+// ============================================================================
+// JSON Output
+// ============================================================================
+
+/**
+ * Print data as JSON (for --json flag)
+ */
+export function json(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+/**
+ * Print data as compact JSON
+ */
+export function jsonCompact(data: unknown): void {
+  console.log(JSON.stringify(data));
+}
+
+// ============================================================================
+// Error Formatting
+// ============================================================================
+
+/**
+ * Format an error for display
+ */
+export function formatError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return String(err);
+}
+
+/**
+ * Print an error with details
+ */
+export function errorWithDetails(message: string, details?: string): void {
+  error(message);
+  if (details) {
+    console.error(colors.dim(`  ${details}`));
+  }
+}
+
+/**
+ * Print a suggestion after an error
+ */
+export function suggest(message: string): void {
+  console.log();
+  console.log(`${colors.info("Suggestion:")} ${message}`);
+}
+
+// ============================================================================
+// Progress / Status
+// ============================================================================
+
+/**
+ * Print a status line that can be updated
+ */
+export function status(message: string): void {
+  process.stdout.write(`\r${symbols.info} ${message}`);
+}
+
+/**
+ * Clear the current line
+ */
+export function clearLine(): void {
+  process.stdout.write("\r\x1b[K");
+}

package/src/utils/spinner.ts

@@ -0,0 +1,214 @@
+/**
+ * Spinner utility using @clack/prompts
+ *
+ * Provides loading spinners for long-running operations
+ */
+
+import * as p from "@clack/prompts";
+
+export interface SpinnerInstance {
+  start: (message?: string) => void;
+  stop: (message?: string, code?: number) => void;
+  message: (message: string) => void;
+}
+
+/**
+ * Create a spinner for long-running operations
+ */
+export function createSpinner(): SpinnerInstance {
+  const spinner = p.spinner();
+
+  return {
+    start(message = "Loading...") {
+      spinner.start(message);
+    },
+    stop(message?: string, code = 0) {
+      spinner.stop(message, code);
+    },
+    message(message: string) {
+      spinner.message(message);
+    },
+  };
+}
+
+/**
+ * Run an async operation with a spinner
+ */
+export async function withSpinner<T>(
+  message: string,
+  fn: () => Promise<T>,
+  successMessage?: string
+): Promise<T> {
+  const spinner = createSpinner();
+  spinner.start(message);
+
+  try {
+    const result = await fn();
+    spinner.stop(successMessage ?? message);
+    return result;
+  } catch (error) {
+    spinner.stop(`Failed: ${message}`, 1);
+    throw error;
+  }
+}
+
+/**
+ * Show a simple intro banner
+ */
+export function intro(message: string): void {
+  p.intro(message);
+}
+
+/**
+ * Show an outro message
+ */
+export function outro(message: string): void {
+  p.outro(message);
+}
+
+/**
+ * Prompt for confirmation
+ */
+export async function confirm(message: string, initialValue = false): Promise<boolean> {
+  const result = await p.confirm({
+    message,
+    initialValue,
+  });
+
+  if (p.isCancel(result)) {
+    return false;
+  }
+
+  return result;
+}
+
+/**
+ * Prompt for text input
+ */
+export async function text(
+  message: string,
+  options?: {
+    placeholder?: string;
+    defaultValue?: string;
+    validate?: (value: string) => string | undefined;
+  }
+): Promise<string | null> {
+  const textOptions: {
+    message: string;
+    placeholder?: string;
+    defaultValue?: string;
+    validate?: (value: string) => string | undefined;
+  } = {
+    message,
+  };
+
+  if (options?.placeholder) {
+    textOptions.placeholder = options.placeholder;
+  }
+  if (options?.defaultValue) {
+    textOptions.defaultValue = options.defaultValue;
+  }
+  if (options?.validate) {
+    textOptions.validate = options.validate;
+  }
+
+  const result = await p.text(textOptions);
+
+  if (p.isCancel(result)) {
+    return null;
+  }
+
+  return result;
+}
+
+/**
+ * Prompt for password input (masked)
+ */
+export async function password(message: string): Promise<string | null> {
+  const result = await p.password({
+    message,
+  });
+
+  if (p.isCancel(result)) {
+    return null;
+  }
+
+  return result;
+}
+
+/**
+ * Prompt for selection from options
+ */
+export async function select<T extends string>(
+  message: string,
+  options: Array<{ value: T; label: string; hint?: string }>
+): Promise<T | null> {
+  const result = await p.select({
+    message,
+    // biome-ignore lint/suspicious/noExplicitAny: clack types are strict about optional props
+    options: options as any,
+  });
+
+  if (p.isCancel(result)) {
+    return null;
+  }
+
+  return result as T;
+}
+
+/**
+ * Check if user cancelled
+ */
+export function isCancel(value: unknown): boolean {
+  return p.isCancel(value);
+}
+
+/**
+ * Cancel and exit
+ */
+export function cancel(message = "Operation cancelled"): never {
+  p.cancel(message);
+  process.exit(0);
+}
+
+/**
+ * Log a message (respects CI mode)
+ */
+export function log(message: string): void {
+  p.log.message(message);
+}
+
+/**
+ * Log an info message
+ */
+export function logInfo(message: string): void {
+  p.log.info(message);
+}
+
+/**
+ * Log a success message
+ */
+export function logSuccess(message: string): void {
+  p.log.success(message);
+}
+
+/**
+ * Log a warning
+ */
+export function logWarning(message: string): void {
+  p.log.warn(message);
+}
+
+/**
+ * Log an error
+ */
+export function logError(message: string): void {
+  p.log.error(message);
+}
+
+/**
+ * Log a step
+ */
+export function logStep(message: string): void {
+  p.log.step(message);
+}