emoemu 0.1.0

package/src/utils/index.ts

@@ -0,0 +1,113 @@
+/**
+ * Utility Module Exports
+ *
+ * General-purpose utilities used across the application.
+ */
+
+// Constants
+export * from './consts';
+
+// Data format utilities
+export {
+  isGzipped,
+  isZstd,
+  isZlib,
+  detectCompressionFormat,
+  decompress,
+} from './compression';
+export type { CompressionFormat } from './compression';
+export { formatPlayTime, formatRuntimeSeconds } from './format';
+
+// Platform path utilities
+export {
+  getConfigDirectory,
+  getDefaultConfigPath,
+  getConfigPaths,
+} from './paths';
+
+// INI file parsing utilities
+export {
+  parseIniLine,
+  parseIniContent,
+  formatIniValue,
+  updateIniLine,
+  parseIniBool,
+  parseIniNumber,
+  parseIniInt,
+  parseIniNullableNumber,
+} from './ini';
+export type { IniKeyValue, IniValue } from './ini';
+
+// Buffer reading utilities
+export {
+  readUint16LE,
+  readInt16LE,
+  applySignedAnalogToDpad,
+  analogToDpad,
+  hatToDpad,
+  applyDpadToButtons,
+} from './buffer';
+export type { DpadState } from './buffer';
+
+// Color utilities
+export {
+  extractRgb15Components,
+  expand5to8,
+  rgb15ToRgb24,
+  calculateLuminance,
+  calculateLuminance8,
+  rgb15ToLuminance,
+  rgbToGrayscale,
+  findClosestEmoji,
+  getGrayscaleEmoji,
+  rgb15ToEmoji,
+  rgb15ToGrayscaleEmoji,
+  rgb24ToEmoji,
+  rgb24ToGrayscaleEmoji,
+  rgbToAnsi256,
+  buildGammaLUT,
+  colorDistanceSquared,
+  EMOJI_COLORS,
+} from './color';
+export type { EmojiColor } from './color';
+
+// CRC32 checksum utilities
+export { crc32, calculateFileCrc32 } from './crc32';
+
+// PNG encoding utilities
+export {
+  PNG_SIGNATURE,
+  createPngChunk,
+  rgbToIndexed,
+} from './png';
+export type { IndexedResult } from './png';
+
+// Kitty graphics protocol utilities
+export {
+  buildKittyImageSequence,
+  buildKittyDeleteSequence,
+  buildCursorPositionSequence,
+  HIDE_CURSOR,
+  SHOW_CURSOR,
+} from './kitty';
+
+// Filesystem utilities
+export { ensureDirectory } from './ensureDirectory';
+
+// Error message extraction
+export { getErrorMessage } from './getErrorMessage';
+
+// Typed error factory
+export { createTypedError } from './typedError';
+
+// Log rotation
+export { rotateLogFile } from './rotateLogFile';
+
+// Terminal utilities
+export {
+  getTerminalDimensions,
+  cleanupStdin,
+  exitAlternateScreen,
+  cleanupInkInstance,
+  pressAnyKeyToContinue,
+} from './terminal';

package/src/utils/ini/index.ts

@@ -0,0 +1,200 @@
+/**
+ * INI File Parser Utilities
+ *
+ * Generic utilities for parsing and writing INI-style configuration files.
+ * Compatible with RetroArch config format.
+ */
+
+import { pipe, filter, map, isNonNull, fromEntries } from 'remeda';
+
+/**
+ * Parsed key-value pair from an INI line
+ */
+export interface IniKeyValue {
+  key: string;
+  value: string;
+}
+
+/**
+ * Supported value types for INI files
+ */
+export type IniValue = string | number | boolean | null;
+
+/**
+ * Parse a config file line and extract key-value pair.
+ * Format: key = "value" or key = value
+ *
+ * @param line A single line from the config file
+ * @returns Parsed key-value pair, or null for comments/empty lines
+ */
+export const parseIniLine = (line: string): IniKeyValue | null => {
+  const trimmed = line.trim();
+
+  // Skip comments and empty lines
+  if (trimmed === '' || trimmed.startsWith('#')) {
+    return null;
+  }
+
+  // Match: key = "value" or key = value
+  const match = trimmed.match(/^([a-z_][a-z0-9_]*)\s*=\s*(.*)$/i);
+  if (!match) {
+    return null;
+  }
+
+  const key = match[1].toLowerCase();
+  let value = match[2].trim();
+
+  // Remove quotes if present
+  if ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))) {
+    value = value.slice(1, -1);
+  }
+
+  return { key, value };
+};
+
+/**
+ * Parse INI file content into a key-value record.
+ * Only includes lines that match the provided valid keys.
+ *
+ * @param content File content to parse
+ * @param validKeys Set of valid keys to include (others are ignored)
+ * @returns Record of key-value pairs
+ */
+export const parseIniContent = (
+  content: string,
+  validKeys: Set<string>
+): Record<string, string> => {
+  const entries = pipe(
+    content.split('\n'),
+    map(parseIniLine),
+    filter(isNonNull),
+    filter(({ key }) => validKeys.has(key)),
+    map(({ key, value }) => [key, value] as const),
+  );
+  return fromEntries(entries) as Record<string, string>;
+};
+
+/**
+ * Format a value for writing to an INI file.
+ *
+ * @param value The value to format
+ * @returns Formatted string representation
+ */
+export const formatIniValue = (value: IniValue): string => {
+  if (value === null) {
+    return 'null';
+  }
+  if (typeof value === 'string') {
+    // Always quote strings for consistency
+    return `"${value}"`;
+  }
+  if (typeof value === 'boolean') {
+    return value ? 'true' : 'false';
+  }
+  return String(value);
+};
+
+/**
+ * Update a single setting in INI file content.
+ * If the setting exists (commented or not), updates its value.
+ * If the setting is commented, uncomments it.
+ * If the setting doesn't exist, appends it at the end.
+ *
+ * @param content Current file content
+ * @param key The config key to update
+ * @param value The new value (already formatted)
+ * @returns Updated file content
+ */
+export const updateIniLine = (content: string, key: string, value: string): string => {
+  const lines = content.split('\n');
+
+  // Pattern to match the key (commented or not): # key = value OR key = value
+  const keyPattern = new RegExp(`^(\\s*#\\s*)?${key}\\s*=.*$`, 'i');
+
+  let found = false;
+  const updatedLines = lines.map((line) => {
+    if (keyPattern.test(line)) {
+      found = true;
+      // Replace with uncommented version
+      return `${key} = ${value}`;
+    }
+    return line;
+  });
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- mutated inside .map() callback
+  if (!found) {
+    // Append at the end (before final empty line if present)
+    const lastLine = updatedLines[updatedLines.length - 1];
+    if (lastLine === '') {
+      updatedLines.splice(updatedLines.length - 1, 0, `${key} = ${value}`);
+    } else {
+      updatedLines.push(`${key} = ${value}`);
+    }
+  }
+
+  return updatedLines.join('\n');
+};
+
+/**
+ * Comment out a setting in INI file content.
+ * If the setting exists (uncommented), comments it out.
+ * If the setting is already commented or doesn't exist, leaves content unchanged.
+ *
+ * @param content Current file content
+ * @param key The config key to comment out
+ * @returns Updated file content
+ */
+export const commentOutIniLine = (content: string, key: string): string => {
+  const lines = content.split('\n');
+
+  // Pattern to match the uncommented key: key = value (not already commented)
+  const keyPattern = new RegExp(`^\\s*${key}\\s*=.*$`, 'i');
+
+  const updatedLines = lines.map((line) => {
+    if (keyPattern.test(line)) {
+      // Comment out the line, preserving the value for reference
+      return `# ${line.trim()}`;
+    }
+    return line;
+  });
+
+  return updatedLines.join('\n');
+};
+
+/**
+ * Parse a string value into a boolean.
+ * Recognizes: true, 1, yes (case-insensitive)
+ */
+export const parseIniBool = (value: string): boolean =>
+  value.toLowerCase() === 'true' || value === '1' || value.toLowerCase() === 'yes';
+
+/**
+ * Parse a string value into a number.
+ * Returns the default value if parsing fails.
+ */
+export const parseIniNumber = (value: string, defaultValue: number): number => {
+  const num = parseFloat(value);
+  return isNaN(num) ? defaultValue : num;
+};
+
+/**
+ * Parse a string value into an integer.
+ * Returns the default value if parsing fails.
+ */
+export const parseIniInt = (value: string, defaultValue: number): number => {
+  const num = parseInt(value, 10);
+  return isNaN(num) ? defaultValue : num;
+};
+
+/**
+ * Parse a nullable number value.
+ * Returns null for empty string, "null", or "auto".
+ */
+export const parseIniNullableNumber = (value: string): number | null => {
+  if (value === '' || value === 'null' || value === 'auto') {
+    return null;
+  }
+  const num = parseInt(value, 10);
+  return isNaN(num) ? null : num;
+};

package/src/utils/kitty/consts.ts

@@ -0,0 +1,13 @@
+// Kitty graphics protocol chunk size for base64 data
+export const KITTY_CHUNK_SIZE = 4096;
+
+// Detection timeout in ms
+export const KITTY_GRAPHICS_DETECT_TIMEOUT_MS = 100;
+export const KITTY_GRAPHICS_RESPONSE_CLEAR_DELAY_MS = 10;
+
+// Kitty graphics protocol query - request image ID support
+export const KITTY_GRAPHICS_QUERY = '\x1b_Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA\x1b\\';
+
+// Escape sequences for cursor visibility
+export const HIDE_CURSOR = '\x1b[?25l';
+export const SHOW_CURSOR = '\x1b[?25h';

package/src/utils/kitty/index.ts

@@ -0,0 +1,181 @@
+/**
+ * Kitty Graphics Protocol Utilities
+ *
+ * Shared utilities for building Kitty graphics protocol escape sequences
+ * for displaying images in terminal dialogs.
+ */
+
+export * from './consts';
+
+import {
+  KITTY_CHUNK_SIZE,
+  KITTY_GRAPHICS_DETECT_TIMEOUT_MS,
+  KITTY_GRAPHICS_RESPONSE_CLEAR_DELAY_MS,
+  KITTY_GRAPHICS_QUERY,
+} from './consts';
+
+// Cached detection result (null = not yet detected)
+let kittyGraphicsSupportedCache: boolean | null = null;
+
+/**
+ * Detect if the terminal supports Kitty graphics protocol.
+ *
+ * Uses protocol query to detect support, with fast paths for Kitty terminal.
+ * Results are cached for subsequent calls.
+ */
+export const detectKittyGraphicsSupport = async (): Promise<boolean> => {
+  // Return cached result if available
+  if (kittyGraphicsSupportedCache !== null) {
+    return kittyGraphicsSupportedCache;
+  }
+
+  // Fast path: KITTY_WINDOW_ID is set by Kitty terminal (always supports its own protocol)
+  if (process.env['KITTY_WINDOW_ID']) {
+    kittyGraphicsSupportedCache = true;
+    return true;
+  }
+
+  // Fast path: TERM=xterm-kitty indicates Kitty terminal
+  if (process.env['TERM'] === 'xterm-kitty') {
+    kittyGraphicsSupportedCache = true;
+    return true;
+  }
+
+  // Only query if stdin is a TTY
+  if (!process.stdin.isTTY) {
+    kittyGraphicsSupportedCache = false;
+    return false;
+  }
+
+  // Query the terminal using Kitty graphics protocol
+  // We need to temporarily configure stdin to receive the response
+  return new Promise((resolve) => {
+    let responded = false;
+    let responseData = '';
+
+    // Save current stdin state
+    const wasRaw = process.stdin.isRaw;
+    const wasPaused = process.stdin.isPaused();
+
+    // Configure stdin to receive terminal response
+    process.stdin.setRawMode(true);
+    if (wasPaused) {
+      process.stdin.resume();
+    }
+
+    // Restore stdin state helper
+    const restoreStdin = () => {
+      process.stdin.setRawMode(wasRaw);
+      if (wasPaused) {
+        process.stdin.pause();
+      }
+    };
+
+    // Temporary handler to check for Kitty graphics response
+    const checkResponse = (data: Buffer) => {
+      const str = data.toString();
+      responseData += str;
+
+      // Kitty graphics protocol responds with: \x1b_G...;\x1b\\
+      // We look for the graphics response pattern
+      if (responseData.includes('\x1b_G') && responseData.includes('\x1b\\')) {
+        responded = true;
+        process.stdin.removeListener('data', checkResponse);
+        restoreStdin();
+
+        // Give time for any additional response data to clear
+        setTimeout(() => {
+          kittyGraphicsSupportedCache = true;
+          resolve(true);
+        }, KITTY_GRAPHICS_RESPONSE_CLEAR_DELAY_MS);
+      }
+    };
+
+    process.stdin.on('data', checkResponse);
+
+    // Send graphics query
+    process.stdout.write(KITTY_GRAPHICS_QUERY);
+
+    // Timeout - no response means not supported
+    setTimeout(() => {
+      if (!responded) {
+        process.stdin.removeListener('data', checkResponse);
+        restoreStdin();
+        kittyGraphicsSupportedCache = false;
+        resolve(false);
+      }
+    }, KITTY_GRAPHICS_DETECT_TIMEOUT_MS);
+  });
+};
+
+/**
+ * Get the cached Kitty graphics support status.
+ * Returns null if detection hasn't been run yet.
+ */
+export const getKittyGraphicsSupported = (): boolean | null => kittyGraphicsSupportedCache;
+
+/**
+ * Reset the cached Kitty graphics detection result.
+ * Useful for testing or when terminal capabilities might have changed.
+ */
+export const resetKittyGraphicsDetection = (): void => {
+  kittyGraphicsSupportedCache = null;
+};
+
+/**
+ * Build Kitty graphics protocol escape sequence for displaying an image.
+ *
+ * @param base64Data Base64-encoded PNG image data
+ * @param cols Display width in terminal columns
+ * @param rows Display height in terminal rows
+ * @param imageId Unique image ID for cleanup
+ * @returns Escape sequence string to write to stdout
+ */
+export const buildKittyImageSequence = (
+  base64Data: string,
+  cols: number,
+  rows: number,
+  imageId: number
+): string => {
+  const chunks: string[] = [];
+
+  for (let i = 0; i < base64Data.length; i += KITTY_CHUNK_SIZE) {
+    const chunk = base64Data.slice(i, i + KITTY_CHUNK_SIZE);
+    const isFirst = i === 0;
+    const isLast = i + KITTY_CHUNK_SIZE >= base64Data.length;
+
+    let control: string;
+    if (isFirst) {
+      // a=T: transmit and display, f=100: PNG format, q=2: suppress response
+      // c=cols, r=rows: display size in cells
+      // C=1: do not move cursor
+      control = `a=T,f=100,i=${imageId},q=2,c=${cols},r=${rows},C=1,m=${isLast ? 0 : 1}`;
+    } else {
+      control = `m=${isLast ? 0 : 1}`;
+    }
+
+    chunks.push(`\x1b_G${control};${chunk}\x1b\\`);
+  }
+
+  return chunks.join('');
+};
+
+/**
+ * Build escape sequence to delete a Kitty image by ID.
+ *
+ * @param imageId The image ID to delete
+ * @returns Escape sequence string to write to stdout
+ */
+export const buildKittyDeleteSequence = (imageId: number): string =>
+  `\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\`;
+
+/**
+ * Build escape sequence to position cursor for image rendering.
+ *
+ * @param row Terminal row (1-indexed)
+ * @param col Terminal column (1-indexed)
+ * @returns Escape sequence string to write to stdout
+ */
+export const buildCursorPositionSequence = (row: number, col: number): string =>
+  `\x1b[${row};${col}H`;
+

package/src/utils/logger/consts.ts

@@ -0,0 +1,35 @@
+import type { LogLevel } from '.';
+
+/** Kilobyte in bytes */
+export const KILOBYTE = 1024;
+
+/** Megabyte in bytes */
+export const MEGABYTE = KILOBYTE * KILOBYTE;
+
+/** Maximum log file size factor (5 MB) */
+export const MAX_LOG_SIZE_MB = 5;
+
+/** Maximum log file size before rotation */
+export const MAX_LOG_SIZE_BYTES = MAX_LOG_SIZE_MB * MEGABYTE;
+
+/** Number of backup files to keep */
+export const MAX_BACKUP_FILES = 3;
+
+/** Padding width for date components */
+export const DATE_PAD_WIDTH = 2;
+
+/** Log level priority for filtering */
+export const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+/** Log level display names (RetroArch style) */
+export const LOG_LEVEL_TAGS: Record<LogLevel, string> = {
+  debug: 'DEBUG',
+  info: 'INFO',
+  warn: 'WARN',
+  error: 'ERROR',
+};