movehat 0.1.1 → 0.1.2

package/src/ui/formatters.ts

@@ -0,0 +1,246 @@
+import { colors } from './colors.js';
+import { symbols } from './symbols.js';
+
+/**
+ * Border color options for boxes
+ */
+export type BorderColor = 'dim' | 'primary' | 'success' | 'error' | 'warning';
+
+/**
+ * Box formatting options
+ */
+export interface BoxOptions {
+  /** Padding inside the box (default: 1) */
+  padding?: number;
+  /** Margin outside the box (default: 0) */
+  margin?: number;
+  /** Border color (default: 'dim') */
+  borderColor?: BorderColor;
+}
+
+/**
+ * Create a box around text with Unicode borders
+ *
+ * @param content - Text content to box (supports multiline)
+ * @param options - Box formatting options
+ * @returns Formatted box string
+ *
+ * @example
+ * const message = box('Update available: 1.0.0 → 1.1.0');
+ * console.log(message);
+ * // ┌────────────────────────────────┐
+ * // │ Update available: 1.0.0 → 1.1.0│
+ * // └────────────────────────────────┘
+ *
+ * @example
+ * const warning = box(
+ *   'This feature is deprecated\nUse the new API instead',
+ *   { borderColor: 'warning', padding: 2 }
+ * );
+ */
+export const box = (
+  content: string,
+  options: BoxOptions = {}
+): string => {
+  const { padding = 1, margin = 0, borderColor = 'dim' } = options;
+
+  const lines = content.split('\n');
+  const maxWidth = Math.max(...lines.map(l => l.length));
+  const innerWidth = maxWidth + padding * 2;
+
+  const marginStr = ' '.repeat(margin);
+  const paddingStr = ' '.repeat(padding);
+
+  const colorFn = colors[borderColor] || colors.dim;
+
+  const top = marginStr + colorFn(symbols.boxTopLeft + symbols.boxTop.repeat(innerWidth) + symbols.boxTopRight);
+  const bottom = marginStr + colorFn(symbols.boxBottomLeft + symbols.boxBottom.repeat(innerWidth) + symbols.boxBottomRight);
+
+  const middle = lines.map(line => {
+    const padded = line.padEnd(maxWidth);
+    return marginStr + colorFn(symbols.boxLeft) + paddingStr + padded + paddingStr + colorFn(symbols.boxRight);
+  });
+
+  return [top, ...middle, bottom].join('\n');
+};
+
+/**
+ * List formatting options
+ */
+export interface ListOptions {
+  /** Number of spaces to indent (default: 0) */
+  indent?: number;
+  /** Starting number for numbered lists (default: 1) */
+  startFrom?: number;
+  /** Custom symbol for bullet lists */
+  symbol?: string;
+}
+
+/**
+ * Create a numbered list
+ *
+ * @param items - Array of items to list
+ * @param options - List formatting options
+ * @returns Formatted numbered list string
+ *
+ * @example
+ * const steps = numberedList([
+ *   'cd my-project',
+ *   'npm install',
+ *   'npm test'
+ * ]);
+ * console.log(steps);
+ * // 1. cd my-project
+ * // 2. npm install
+ * // 3. npm test
+ */
+export const numberedList = (
+  items: string[],
+  options: ListOptions = {}
+): string => {
+  const { indent = 0, startFrom = 1 } = options;
+  const prefix = ' '.repeat(indent);
+
+  return items
+    .map((item, idx) => `${prefix}${startFrom + idx}. ${item}`)
+    .join('\n');
+};
+
+/**
+ * Create a bulleted list
+ *
+ * @param items - Array of items to list
+ * @param options - List formatting options
+ * @returns Formatted bulleted list string
+ *
+ * @example
+ * const features = bulletList([
+ *   'Feature A',
+ *   'Feature B',
+ *   'Feature C'
+ * ]);
+ * console.log(features);
+ * // • Feature A
+ * // • Feature B
+ * // • Feature C
+ *
+ * @example
+ * const tasks = bulletList(
+ *   ['Task 1', 'Task 2'],
+ *   { indent: 2, symbol: '→' }
+ * );
+ */
+export const bulletList = (
+  items: string[],
+  options: ListOptions = {}
+): string => {
+  const { indent = 0, symbol = symbols.bullet } = options;
+  const prefix = ' '.repeat(indent);
+
+  return items
+    .map(item => `${prefix}${symbol} ${item}`)
+    .join('\n');
+};
+
+/**
+ * Indent text block by a specified number of spaces
+ *
+ * @param text - Text to indent (supports multiline)
+ * @param spaces - Number of spaces to indent
+ * @returns Indented text
+ *
+ * @example
+ * const code = 'function test() {\n  return true;\n}';
+ * console.log(indent(code, 4));
+ * //     function test() {
+ * //       return true;
+ * //     }
+ */
+export const indent = (text: string, spaces: number): string => {
+  const prefix = ' '.repeat(spaces);
+  return text.split('\n').map(line => prefix + line).join('\n');
+};
+
+/**
+ * Create a horizontal divider line
+ *
+ * @param width - Width of the divider (default: 60)
+ * @param char - Character to use (default: symbols.line)
+ * @returns Formatted divider string
+ *
+ * @example
+ * console.log(divider());
+ * // ────────────────────────────────────────────────────────────
+ *
+ * @example
+ * console.log(divider(40, '='));
+ * // ========================================
+ */
+export const divider = (
+  width: number = 60,
+  char: string = symbols.line
+): string => {
+  return colors.dim(char.repeat(width));
+};
+
+/**
+ * Format file path with dimmed parent directories
+ * Highlights the filename while dimming the directory path
+ *
+ * @param filePath - Full file path
+ * @returns Formatted path string
+ *
+ * @example
+ * console.log(formatPath('/Users/name/project/src/file.ts'));
+ * // /Users/name/project/src/file.ts
+ * // (where the directory is dimmed and filename is bright)
+ */
+export const formatPath = (filePath: string): string => {
+  const parts = filePath.split('/');
+  const fileName = parts.pop() || '';
+  const dirPath = parts.join('/');
+
+  return colors.dim(dirPath + '/') + fileName;
+};
+
+/**
+ * Create a section header with divider
+ * Combines a bold title with a horizontal line
+ *
+ * @param title - Section title
+ * @param options - Formatting options
+ * @returns Formatted section header
+ *
+ * @example
+ * console.log(sectionHeader('Fork Details'));
+ * //
+ * // Fork Details
+ * // ────────────────────────────────────────────────────────────
+ */
+export const sectionHeader = (
+  title: string,
+  options: { width?: number; char?: string } = {}
+): string => {
+  const { width = 60, char = symbols.line } = options;
+  return `\n${colors.brandBright(title)}\n${divider(width, char)}`;
+};
+
+/**
+ * Format a command for display with dimmed prompt
+ * Useful for showing example commands to users
+ *
+ * @param command - Command string
+ * @returns Formatted command with $ prompt
+ *
+ * @example
+ * console.log(formatCommand('movehat compile'));
+ * // $ movehat compile
+ * // (where $ is dimmed)
+ *
+ * @example
+ * console.log(formatCommand('npm install'));
+ * // $ npm install
+ */
+export const formatCommand = (command: string): string => {
+  return `${colors.dim('$')} ${command}`;
+};

package/src/ui/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Movehat UI Module
+ *
+ * Provides a comprehensive set of UI utilities for the CLI including:
+ * - Colors and gradients (picocolors wrapper)
+ * - Cross-platform symbols (figures wrapper)
+ * - Structured logging system
+ * - Spinners for async operations (ora wrapper)
+ * - Table formatting (cli-table3 wrapper)
+ * - Text formatting utilities
+ *
+ * @example
+ * // Named imports (recommended)
+ * import { logger, spinner, createTable } from './ui/index.js';
+ *
+ * logger.info('Starting compilation...');
+ * const spin = spinner({ text: 'Compiling...' });
+ * // ... async work ...
+ * spin.succeed('Compilation complete!');
+ *
+ * @example
+ * // Namespace import
+ * import { ui } from './ui/index.js';
+ *
+ * ui.logger.info('Starting...');
+ * ui.logger.success('Done!');
+ */
+
+// Re-export everything from submodules for named imports
+export * from './colors.js';
+export * from './symbols.js';
+export * from './logger.js';
+export * from './spinner.js';
+export * from './table.js';
+export * from './formatters.js';
+
+// Also export as namespace for convenience
+import * as _colors from './colors.js';
+import * as _symbols from './symbols.js';
+import * as _logger from './logger.js';
+import * as _spinner from './spinner.js';
+import * as _table from './table.js';
+import * as _formatters from './formatters.js';
+
+/**
+ * Unified UI namespace
+ * Provides all UI utilities in a single namespace object
+ *
+ * @example
+ * import { ui } from './ui/index.js';
+ *
+ * ui.logger.info('Processing...');
+ * ui.logger.success('Done!');
+ */
+export const ui = {
+  colors: _colors,
+  symbols: _symbols,
+  logger: _logger,
+  spinner: _spinner,
+  table: _table,
+  formatters: _formatters,
+};

package/src/ui/logger.ts

@@ -0,0 +1,226 @@
+import { colors } from './colors.js';
+import { coloredSymbol, symbols } from './symbols.js';
+
+/**
+ * Available log levels
+ */
+export type LogLevel = 'info' | 'success' | 'error' | 'warning' | 'debug';
+
+/**
+ * Logger configuration options
+ */
+export interface LoggerConfig {
+  /** Suppress all output when true */
+  silent?: boolean;
+  /** Minimum log level to display */
+  level?: LogLevel;
+  /** Include timestamps in log messages */
+  timestamp?: boolean;
+}
+
+/**
+ * Internal logger state
+ */
+let config: LoggerConfig = {
+  silent: false,
+  level: 'info',
+  timestamp: false,
+};
+
+/**
+ * Configure logger globally
+ *
+ * @param newConfig - Partial configuration to merge with current config
+ *
+ * @example
+ * // Silence all logs for testing
+ * configureLogger({ silent: true });
+ *
+ * // Enable timestamps
+ * configureLogger({ timestamp: true });
+ */
+export const configureLogger = (newConfig: Partial<LoggerConfig>): void => {
+  config = { ...config, ...newConfig };
+};
+
+/**
+ * Format message with optional indentation
+ */
+const formatMessage = (message: string, indent: number = 0): string => {
+  const prefix = ' '.repeat(indent);
+  return message.split('\n').map(line => prefix + line).join('\n');
+};
+
+/**
+ * Info message (cyan)
+ * Use for general information and status updates
+ *
+ * @param message - Message to log
+ * @param indent - Number of spaces to indent (default: 0)
+ *
+ * @example
+ * logger.info('Starting compilation...');
+ * logger.info('Network: testnet', 2);
+ */
+export const info = (message: string, indent: number = 0): void => {
+  if (config.silent) return;
+  const formatted = formatMessage(message, indent);
+  console.log(`${coloredSymbol('info')} ${formatted}`);
+};
+
+/**
+ * Success message (green)
+ * Use for completed operations and positive outcomes
+ *
+ * @param message - Message to log
+ * @param indent - Number of spaces to indent (default: 0)
+ *
+ * @example
+ * logger.success('Compilation finished!');
+ * logger.success('All tests passed', 2);
+ */
+export const success = (message: string, indent: number = 0): void => {
+  if (config.silent) return;
+  const formatted = formatMessage(message, indent);
+  console.log(`${coloredSymbol('success')} ${formatted}`);
+};
+
+/**
+ * Error message (red)
+ * Use for errors and failures
+ *
+ * @param message - Message to log
+ * @param indent - Number of spaces to indent (default: 0)
+ *
+ * @example
+ * logger.error('Compilation failed');
+ * logger.error('File not found: config.ts', 2);
+ */
+export const error = (message: string, indent: number = 0): void => {
+  if (config.silent) return;
+  const formatted = formatMessage(message, indent);
+  console.error(`${coloredSymbol('error')} ${formatted}`);
+};
+
+/**
+ * Warning message (yellow)
+ * Use for warnings and deprecated features
+ *
+ * @param message - Message to log
+ * @param indent - Number of spaces to indent (default: 0)
+ *
+ * @example
+ * logger.warning('Deprecated API used');
+ * logger.warning('This feature will be removed in v2.0', 2);
+ */
+export const warning = (message: string, indent: number = 0): void => {
+  if (config.silent) return;
+  const formatted = formatMessage(message, indent);
+  console.warn(`${coloredSymbol('warning')} ${formatted}`);
+};
+
+/**
+ * Plain message without symbol
+ * Use for continuation lines or when symbol is not appropriate
+ *
+ * @param message - Message to log
+ *
+ * @example
+ * logger.info('Fork Details:');
+ * logger.plain('   Chain ID: 126');
+ * logger.plain('   Network: testnet');
+ */
+export const plain = (message: string): void => {
+  if (config.silent) return;
+  console.log(message);
+};
+
+/**
+ * Empty line
+ * Use for visual spacing between sections
+ *
+ * @example
+ * logger.success('Build complete');
+ * logger.newline();
+ * logger.info('Next steps:');
+ */
+export const newline = (): void => {
+  if (config.silent) return;
+  console.log();
+};
+
+/**
+ * Section header (bold, brand color)
+ * Use for major section dividers
+ *
+ * @param title - Section title
+ *
+ * @example
+ * logger.section('Fork Details');
+ * logger.kv('Chain ID', '126', 2);
+ * logger.kv('Network', 'testnet', 2);
+ */
+export const section = (title: string): void => {
+  if (config.silent) return;
+  console.log(`\n${colors.brandBright(title)}`);
+};
+
+/**
+ * Key-value pair
+ * Use for displaying structured data
+ *
+ * @param key - The key/label
+ * @param value - The value
+ * @param indent - Number of spaces to indent (default: 0)
+ *
+ * @example
+ * logger.kv('Network', 'testnet', 2);
+ * logger.kv('Chain ID', '126', 2);
+ */
+export const kv = (key: string, value: string, indent: number = 0): void => {
+  if (config.silent) return;
+  const prefix = ' '.repeat(indent);
+  console.log(`${prefix}${colors.dim(key)}: ${value}`);
+};
+
+/**
+ * List item with bullet
+ * Use for lists and enumerated items
+ *
+ * @param text - Item text
+ * @param indent - Number of spaces to indent (default: 0)
+ *
+ * @example
+ * logger.info('Next steps:');
+ * logger.item('cd my-project', 2);
+ * logger.item('npm install', 2);
+ * logger.item('npm test', 2);
+ */
+export const item = (text: string, indent: number = 0): void => {
+  if (config.silent) return;
+  const prefix = ' '.repeat(indent);
+  console.log(`${prefix}${symbols.bullet} ${text}`);
+};
+
+/**
+ * Logger namespace export
+ * Provides all logging functions in a single namespace
+ *
+ * @example
+ * import { logger } from './ui/index.js';
+ *
+ * logger.info('Starting...');
+ * logger.success('Done!');
+ */
+export const logger = {
+  configure: configureLogger,
+  info,
+  success,
+  error,
+  warning,
+  plain,
+  newline,
+  section,
+  kv,
+  item,
+};

package/src/ui/spinner.ts

@@ -0,0 +1,171 @@
+import ora, { type Ora, type Options as OraOptions } from 'ora';
+import { shouldUseColor } from './colors.js';
+
+/**
+ * Spinner color options
+ */
+export type SpinnerColor = 'yellow' | 'green' | 'cyan' | 'red' | 'blue' | 'magenta' | 'white' | 'gray';
+
+/**
+ * Spinner configuration options
+ */
+export interface SpinnerOptions {
+  /** Text to display next to the spinner */
+  text: string;
+  /** Spinner color (default: 'yellow' for Movehat brand) */
+  color?: SpinnerColor;
+  /** Spinner animation type (default: 'dots') */
+  spinner?: OraOptions['spinner'];
+  /** Number of spaces to indent (default: 0) */
+  indent?: number;
+}
+
+/**
+ * Create and start a spinner
+ * Automatically disabled in non-TTY environments (CI, pipes)
+ *
+ * @param options - Spinner configuration
+ * @returns Ora spinner instance
+ *
+ * @example
+ * const spin = spinner({ text: 'Compiling contracts...' });
+ * await longRunningTask();
+ * spin.succeed('Compilation complete!');
+ *
+ * @example
+ * const spin = spinner({ text: 'Fetching data...', color: 'cyan' });
+ * try {
+ *   await fetchData();
+ *   spin.succeed('Data fetched!');
+ * } catch (error) {
+ *   spin.fail('Failed to fetch data');
+ * }
+ */
+export const spinner = (options: SpinnerOptions): Ora => {
+  const { text, color = 'yellow', spinner = 'dots', indent = 0 } = options;
+
+  const prefixSpaces = ' '.repeat(indent);
+
+  const oraOptions: OraOptions = {
+    text: prefixSpaces + text,
+    color,
+    spinner,
+    // Disable spinner if not TTY (CI environments, piped output)
+    isEnabled: shouldUseColor() && Boolean(process.stdout.isTTY),
+  };
+
+  return ora(oraOptions).start();
+};
+
+/**
+ * Execute async task with spinner
+ * Handles success/error automatically and always cleans up
+ *
+ * @param startText - Initial spinner text
+ * @param task - Async function to execute
+ * @param successText - Text to show on success (optional, defaults to startText without '...')
+ * @param errorText - Text to show on error (optional, defaults to error message)
+ * @param indent - Number of spaces to indent (default: 0)
+ * @returns Promise resolving to task result
+ *
+ * @example
+ * const data = await withSpinner(
+ *   'Fetching network data...',
+ *   async () => await fetchData(),
+ *   'Data fetched successfully'
+ * );
+ *
+ * @example
+ * await withSpinner(
+ *   'Creating fork...',
+ *   async () => await createFork(),
+ *   'Fork created!',
+ *   'Failed to create fork'
+ * );
+ */
+export const withSpinner = async <T>(
+  startText: string,
+  task: () => Promise<T>,
+  successText?: string,
+  errorText?: string,
+  indent: number = 0
+): Promise<T> => {
+  const spin = spinner({ text: startText, indent });
+
+  try {
+    const result = await task();
+    spin.succeed(successText || startText.replace(/\.\.\.?$/, ''));
+    return result;
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    spin.fail(errorText || `Failed: ${errMsg}`);
+    throw error;
+  }
+};
+
+/**
+ * Spinner chain for sequential operations
+ * Manages multiple spinners in sequence
+ */
+export interface SpinnerChain {
+  /**
+   * Add and execute a step in the chain
+   */
+  add<T>(text: string, task: () => Promise<T>, indent?: number): Promise<T>;
+
+  /**
+   * Complete the chain (cleanup)
+   */
+  complete(): void;
+}
+
+/**
+ * Create a sequential spinner chain
+ * Useful for multi-step processes like initialization
+ *
+ * @returns SpinnerChain interface
+ *
+ * @example
+ * const steps = createSpinnerChain();
+ *
+ * await steps.add('Creating directories...', async () => {
+ *   await mkdir(projectPath);
+ * });
+ *
+ * await steps.add('Copying templates...', async () => {
+ *   await copyFiles();
+ * });
+ *
+ * await steps.add('Installing dependencies...', async () => {
+ *   await npmInstall();
+ * });
+ *
+ * steps.complete();
+ */
+export const createSpinnerChain = (): SpinnerChain => {
+  let currentSpinner: Ora | null = null;
+
+  return {
+    async add<T>(
+      text: string,
+      task: () => Promise<T>,
+      indent: number = 0
+    ): Promise<T> {
+      currentSpinner = spinner({ text, indent });
+      try {
+        const result = await task();
+        currentSpinner.succeed();
+        return result;
+      } catch (error) {
+        currentSpinner.fail();
+        throw error;
+      }
+    },
+
+    complete() {
+      if (currentSpinner) {
+        currentSpinner.stop();
+      }
+    },
+  };
+};