emoemu 0.1.0

package/src/utils/logger/index.ts

@@ -0,0 +1,217 @@
+/**
+ * General-Purpose Logger
+ *
+ * Writes debug logs to a file for debugging and monitoring.
+ * Log file is stored in the platform-specific config directory.
+ * Format matches RetroArch's log format for consistency.
+ */
+
+import { appendFileSync, writeFileSync } from 'fs';
+import { ensureDirectory } from '../ensureDirectory';
+import { rotateLogFile } from '../rotateLogFile';
+import { join } from 'path';
+import { getConfigDirectory } from '../paths';
+
+/** Log levels */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export * from './consts';
+
+import {
+  LOG_LEVEL_PRIORITY,
+  LOG_LEVEL_TAGS,
+  MAX_LOG_SIZE_BYTES,
+  MAX_BACKUP_FILES,
+  DATE_PAD_WIDTH,
+} from './consts';
+
+/** Get the default log directory */
+const getDefaultLogDirectory = (): string => join(getConfigDirectory(), 'logs');
+
+/**
+ * Format current date/time for timestamped log filename
+ * Format: emoemu__2026_01_22__02_53_37.log
+ */
+const formatLogTimestamp = (): string => {
+  const now = new Date();
+  const pad = (n: number): string => String(n).padStart(DATE_PAD_WIDTH, '0');
+  const year = now.getFullYear();
+  const month = pad(now.getMonth() + 1);
+  const day = pad(now.getDate());
+  const hour = pad(now.getHours());
+  const minute = pad(now.getMinutes());
+  const second = pad(now.getSeconds());
+  return `emoemu__${year}_${month}_${day}__${hour}_${minute}_${second}.log`;
+};
+
+/**
+ * Logger provides structured logging for application events.
+ * Output format matches RetroArch: [LEVEL] [Category]: message
+ */
+class Logger {
+  private logPath: string;
+  private minLevel: LogLevel = 'debug';
+  private enabled = false;
+  private initialized = false;
+  private logToStderr = false;
+  private logToFile = true;
+  private useTimestampedFile = false;
+  private customLogDir: string | null = null;
+
+  constructor() {
+    this.logPath = join(getDefaultLogDirectory(), 'emoemu.log');
+  }
+
+  /** Enable or disable logging */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  /** Check if logging is enabled */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /** Set minimum log level */
+  setMinLevel(level: LogLevel): void {
+    this.minLevel = level;
+  }
+
+  /** Enable logging to stderr (for --verbose mode) */
+  setLogToStderr(enabled: boolean): void {
+    this.logToStderr = enabled;
+  }
+
+  /** Set whether to write logs to file (true) or console (false) */
+  setLogToFile(enabled: boolean): void {
+    this.logToFile = enabled;
+  }
+
+  /** Set whether to use timestamped log files */
+  setUseTimestampedFile(enabled: boolean): void {
+    this.useTimestampedFile = enabled;
+  }
+
+  /** Set custom log directory */
+  setLogDirectory(dir: string): void {
+    this.customLogDir = dir || null;
+  }
+
+  /** Get the log file path */
+  getLogPath(): string {
+    return this.logPath;
+  }
+
+  /** Get the log directory */
+  getLogDirectory(): string {
+    return this.customLogDir || getDefaultLogDirectory();
+  }
+
+  /** Initialize the log file (creates directory and sets up log file) */
+  private initialize(): void {
+    if (this.initialized) {
+      return;
+    }
+
+    const logDir = this.getLogDirectory();
+
+    ensureDirectory(logDir);
+
+    // Set up log file path
+    if (this.useTimestampedFile) {
+      // Use timestamped filename
+      this.logPath = join(logDir, formatLogTimestamp());
+    } else {
+      // Use fixed filename, clear on startup
+      this.logPath = join(logDir, 'emoemu.log');
+      // Clear the log file by writing empty content
+      try {
+        writeFileSync(this.logPath, '');
+      } catch {
+        // Ignore errors
+      }
+    }
+
+    // Check if rotation is needed (only for non-timestamped files)
+    if (!this.useTimestampedFile) {
+      this.rotateIfNeeded();
+    }
+
+    this.initialized = true;
+  }
+
+  /** Rotate log file if it exceeds max size */
+  private rotateIfNeeded(): void {
+    rotateLogFile(this.logPath, MAX_LOG_SIZE_BYTES, MAX_BACKUP_FILES);
+  }
+
+  /** Write a log entry in RetroArch format */
+  private write(level: LogLevel, message: string, category?: string): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[this.minLevel]) {
+      return;
+    }
+
+    const levelTag = LOG_LEVEL_TAGS[level];
+    const logLine = category
+      ? `[${levelTag}] [${category}]: ${message}`
+      : `[${levelTag}] ${message}`;
+
+    // Write to stderr if verbose mode is enabled
+    if (this.logToStderr) {
+      process.stderr.write(logLine + '\n');
+    }
+
+    if (this.logToFile) {
+      // Write to file
+      this.initialize();
+      try {
+        appendFileSync(this.logPath, logLine + '\n');
+      } catch {
+        // Silently ignore write errors
+      }
+    } else {
+      // Output to console based on log level
+      switch (level) {
+        case 'debug':
+          console.debug(logLine);
+          break;
+        case 'info':
+          console.info(logLine);
+          break;
+        case 'warn':
+          console.warn(logLine);
+          break;
+        case 'error':
+          console.error(logLine);
+          break;
+      }
+    }
+  }
+
+  /** Log a debug message */
+  debug(message: string, category?: string): void {
+    this.write('debug', message, category);
+  }
+
+  /** Log an info message */
+  info(message: string, category?: string): void {
+    this.write('info', message, category);
+  }
+
+  /** Log a warning message */
+  warn(message: string, category?: string): void {
+    this.write('warn', message, category);
+  }
+
+  /** Log an error message */
+  error(message: string, category?: string): void {
+    this.write('error', message, category);
+  }
+}
+
+/** Singleton logger instance */
+export const logger = new Logger();

package/src/utils/paths/consts.ts

@@ -0,0 +1,18 @@
+import type { ThumbnailType } from '.';
+
+/**
+ * Characters that must be replaced with underscore in RetroArch thumbnail filenames.
+ * These characters are not allowed in playlist labels used as filenames:
+ * & * / : < > ? \ | "
+ */
+export const THUMBNAIL_FORBIDDEN_CHARS = /[&*\/:<>?\\|"]/g;
+
+/** Directory names for each thumbnail type (RetroArch-compatible) */
+export const THUMBNAIL_TYPE_DIRS: Record<ThumbnailType, string> = {
+  boxart: 'Named_Boxarts',
+  snap: 'Named_Snaps',
+  title: 'Named_Titles',
+};
+
+/** All thumbnail types in display priority order (snap > title > boxart) */
+export const THUMBNAIL_TYPES: ThumbnailType[] = ['snap', 'title', 'boxart'];

package/src/utils/paths/index.ts

@@ -0,0 +1,151 @@
+/**
+ * Platform Path Utilities
+ *
+ * Platform-specific directory resolution following standard conventions:
+ * - macOS: ~/Library/Application Support/emoemu
+ * - Linux: ~/.config/emoemu (or $XDG_CONFIG_HOME/emoemu)
+ * - Windows: %APPDATA%\emoemu
+ */
+
+import { join } from 'path';
+import { homedir, platform } from 'os';
+import { pipe, filter, isTruthy } from 'remeda';
+
+export * from './consts';
+
+import { THUMBNAIL_FORBIDDEN_CHARS, THUMBNAIL_TYPE_DIRS } from './consts';
+
+/**
+ * Expand a path, resolving ~ to the user's home directory.
+ * Useful for config values that may contain ~ shorthand.
+ *
+ * @param path Path that may start with ~
+ * @returns Expanded path with ~ replaced by home directory
+ */
+export const expandPath = (path: string): string => {
+  if (path.startsWith("~")) {
+    return join(homedir(), path.slice(1));
+  }
+  return path;
+};
+
+/**
+ * Get the platform-specific config directory path
+ */
+export const getConfigDirectory = (): string => {
+  switch (platform()) {
+    case 'darwin':
+      return join(homedir(), 'Library', 'Application Support', 'emoemu');
+    case 'win32':
+      return join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'emoemu');
+    default:
+      // Linux and other Unix-like systems
+      return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'emoemu');
+  }
+};
+
+/**
+ * Get the default config file path for the current platform
+ * RetroArch-compatible location: {config_dir}/config/emoemu.cfg
+ */
+export const getDefaultConfigPath = (): string => join(getConfigDirectory(), 'config', 'emoemu.cfg');
+
+/**
+ * Get the default playlists directory path for the current platform
+ * RetroArch-compatible location: {config_dir}/playlists
+ */
+export const getDefaultPlaylistsDirectory = (): string => join(getConfigDirectory(), 'playlists');
+
+/**
+ * Get the default save states directory path for the current platform
+ * RetroArch-compatible location: {config_dir}/states
+ */
+export const getDefaultSavestatesDirectory = (): string => join(getConfigDirectory(), 'states');
+
+/**
+ * Get the default save files (battery saves) directory path for the current platform
+ * RetroArch-compatible location: {config_dir}/saves
+ */
+export const getDefaultSavefilesDirectory = (): string => join(getConfigDirectory(), 'saves');
+
+/**
+ * Get the default thumbnails directory path for the current platform
+ * RetroArch-compatible location: {config_dir}/thumbnails
+ */
+export const getDefaultThumbnailsDirectory = (): string => join(getConfigDirectory(), 'thumbnails');
+
+/**
+ * Get the default logs directory path for the current platform
+ * Location: {config_dir}/logs
+ */
+export const getDefaultLogsDirectory = (): string => join(getConfigDirectory(), 'logs');
+
+
+/**
+ * Sanitize a filename for RetroArch thumbnail compatibility.
+ * Replaces forbidden characters with underscores.
+ */
+export const sanitizeThumbnailFilename = (name: string): string =>
+  name.replace(THUMBNAIL_FORBIDDEN_CHARS, '_');
+
+/**
+ * RetroArch thumbnail types.
+ * Each type is stored in a separate subdirectory under the system's thumbnail folder.
+ *
+ * - boxart: Box art / cover images (Named_Boxarts/)
+ * - snap: In-game screenshots (Named_Snaps/)
+ * - title: Title screen images (Named_Titles/)
+ */
+export type ThumbnailType = 'boxart' | 'snap' | 'title';
+
+
+/**
+ * Get the path to a ROM's thumbnail.
+ *
+ * RetroArch stores thumbnails in: {thumbnails_dir}/{System Name}/{Type}/{Label}.png
+ * where Type is one of: Named_Boxarts, Named_Snaps, Named_Titles
+ *
+ * @param systemName RetroArch system name (e.g., "Nintendo - Nintendo Entertainment System")
+ * @param romLabel ROM label/title (will be sanitized)
+ * @param type Thumbnail type: 'boxart', 'snap', or 'title' (default: 'snap')
+ * @returns Full path to the thumbnail PNG
+ */
+export const getThumbnailPath = (
+  systemName: string,
+  romLabel: string,
+  type: ThumbnailType = 'snap'
+): string => {
+  const sanitizedLabel = sanitizeThumbnailFilename(romLabel);
+  const typeDir = THUMBNAIL_TYPE_DIRS[type];
+  return join(getDefaultThumbnailsDirectory(), systemName, typeDir, `${sanitizedLabel}.png`);
+};
+
+/**
+ * Get paths to all thumbnail types for a ROM.
+ * Useful for checking if any thumbnail exists or for cleanup.
+ *
+ * @param systemName RetroArch system name
+ * @param romLabel ROM label/title (will be sanitized)
+ * @returns Object with paths for each thumbnail type
+ */
+export const getAllThumbnailPaths = (
+  systemName: string,
+  romLabel: string
+): Record<ThumbnailType, string> => ({
+  boxart: getThumbnailPath(systemName, romLabel, 'boxart'),
+  snap: getThumbnailPath(systemName, romLabel, 'snap'),
+  title: getThumbnailPath(systemName, romLabel, 'title'),
+});
+
+/**
+ * Get all possible config file paths in order of precedence (highest first)
+ */
+export const getConfigPaths = (customPath?: string): string[] => pipe(
+  [
+    customPath,                              // 1. Custom path from --config flag
+    process.env.EMOEMU_CONFIG,               // 2. Environment variable
+    join(process.cwd(), 'emoemu.cfg'),       // 3. Current working directory
+    getDefaultConfigPath(),                  // 4. Platform-specific default
+  ],
+  filter(isTruthy)
+);

package/src/utils/png/consts.ts

@@ -0,0 +1,34 @@
+/** PNG chunk header size: length (4) + type (4) */
+export const PNG_CHUNK_HEADER_SIZE = 8;
+
+/** PNG chunk footer size: CRC32 (4) */
+export const PNG_CHUNK_FOOTER_SIZE = 4;
+
+/** PNG chunk overhead: header + footer */
+export const PNG_CHUNK_OVERHEAD = 12;
+
+/** Offset for chunk type in PNG chunk buffer */
+export const PNG_CHUNK_TYPE_OFFSET = 4;
+
+/** Offset for chunk data in PNG chunk buffer */
+export const PNG_CHUNK_DATA_OFFSET = 8;
+
+/** Size of chunk type field */
+export const PNG_CHUNK_TYPE_SIZE = 4;
+
+/** Maximum colors in indexed PNG palette */
+export const PNG_MAX_PALETTE_COLORS = 256;
+
+/** Size of RGB triplet in palette */
+export const RGB_TRIPLET_SIZE = 3;
+
+/** Maximum palette buffer size (256 colors * 3 bytes) */
+export const PNG_PALETTE_BUFFER_SIZE = 768;
+
+// Bit manipulation constants for byte operations
+
+/** Bit shift for second byte (green channel in RGB24) */
+export const BYTE_SHIFT_1 = 8;
+
+/** Bit shift for third byte (red channel in RGB24) */
+export const BYTE_SHIFT_2 = 16;

package/src/utils/png/index.ts

@@ -0,0 +1,131 @@
+/**
+ * PNG Encoding Utilities
+ *
+ * Shared utilities for PNG chunk creation and color indexing,
+ * used by both the main Kitty renderer and the worker thread.
+ */
+
+import {
+  PNG_CHUNK_OVERHEAD,
+  PNG_CHUNK_TYPE_OFFSET,
+  PNG_CHUNK_DATA_OFFSET,
+  PNG_CHUNK_TYPE_SIZE,
+  PNG_MAX_PALETTE_COLORS,
+  RGB_TRIPLET_SIZE,
+  PNG_PALETTE_BUFFER_SIZE,
+  BYTE_SHIFT_1,
+  BYTE_SHIFT_2,
+} from './consts';
+
+export * from './consts';
+
+import { crc32 } from '../crc32';
+
+// Re-export crc32 for backwards compatibility
+export { crc32 };
+
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+// PNG file signature (magic bytes)
+export const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * Create a PNG chunk with the given type and data.
+ * PNG chunks have the format: length (4) + type (4) + data + crc32 (4)
+ */
+export const createPngChunk = (type: string, data: Buffer): Buffer => {
+  const chunk = Buffer.alloc(PNG_CHUNK_OVERHEAD + data.length);
+  chunk.writeUInt32BE(data.length, 0);
+  chunk.write(type, PNG_CHUNK_TYPE_OFFSET, PNG_CHUNK_TYPE_SIZE, 'ascii');
+  data.copy(chunk, PNG_CHUNK_DATA_OFFSET);
+  const crcData = Buffer.alloc(PNG_CHUNK_TYPE_SIZE + data.length);
+  crcData.write(type, 0, PNG_CHUNK_TYPE_SIZE, 'ascii');
+  data.copy(crcData, PNG_CHUNK_TYPE_SIZE);
+  chunk.writeUInt32BE(crc32(crcData), PNG_CHUNK_DATA_OFFSET + data.length);
+  return chunk;
+};
+
+/**
+ * Result of RGB to indexed color conversion
+ */
+export interface IndexedResult {
+  indices: Uint8Array;
+  palette: Uint8Array;  // RGB triplets
+  colorCount: number;
+}
+
+// Internal buffers for worker-style buffer management
+let internalIndexedBuffer: Uint8Array | null = null;
+let internalPaletteBuffer: Uint8Array | null = null;
+
+/**
+ * Convert RGB buffer to indexed format (max 256 colors).
+ * Returns null if more than 256 unique colors.
+ *
+ * @param rgb RGB pixel data (3 bytes per pixel)
+ * @param width Image width
+ * @param height Image height
+ * @param indexedBuffer Optional pre-allocated buffer for indices (will allocate if not provided)
+ * @param paletteBuffer Optional pre-allocated buffer for palette (will allocate if not provided)
+ */
+export const rgbToIndexed = (
+  rgb: Uint8Array,
+  width: number,
+  height: number,
+  indexedBuffer?: Uint8Array,
+  paletteBuffer?: Uint8Array
+): IndexedResult | null => {
+  const pixelCount = width * height;
+
+  // Use provided buffers or manage internal ones
+  let indices: Uint8Array;
+  let palette: Uint8Array;
+
+  if (indexedBuffer && paletteBuffer) {
+    indices = indexedBuffer;
+    palette = paletteBuffer;
+  } else {
+    // Reuse internal buffers (worker-style)
+    if (!internalIndexedBuffer || internalIndexedBuffer.length < pixelCount) {
+      internalIndexedBuffer = new Uint8Array(pixelCount);
+    }
+    if (!internalPaletteBuffer || internalPaletteBuffer.length < PNG_PALETTE_BUFFER_SIZE) {
+      internalPaletteBuffer = new Uint8Array(PNG_PALETTE_BUFFER_SIZE);
+    }
+    indices = internalIndexedBuffer;
+    palette = internalPaletteBuffer;
+  }
+
+  // Map RGB color (as 24-bit int) to palette index
+  const colorMap = new Map<number, number>();
+  let colorCount = 0;
+
+  for (let i = 0; i < pixelCount; i++) {
+    const rgbIdx = i * RGB_TRIPLET_SIZE;
+    const r = rgb[rgbIdx];
+    const g = rgb[rgbIdx + 1];
+    const b = rgb[rgbIdx + 2];
+    const colorKey = (r << BYTE_SHIFT_2) | (g << BYTE_SHIFT_1) | b;
+
+    let paletteIdx = colorMap.get(colorKey);
+    if (paletteIdx === undefined) {
+      if (colorCount >= PNG_MAX_PALETTE_COLORS) {
+        // Too many colors, fall back to RGB
+        return null;
+      }
+      paletteIdx = colorCount;
+      colorMap.set(colorKey, paletteIdx);
+      palette[colorCount * RGB_TRIPLET_SIZE] = r;
+      palette[colorCount * RGB_TRIPLET_SIZE + 1] = g;
+      palette[colorCount * RGB_TRIPLET_SIZE + 2] = b;
+      colorCount++;
+    }
+
+    indices[i] = paletteIdx;
+  }
+
+  return {
+    indices,
+    palette: palette.subarray(0, colorCount * RGB_TRIPLET_SIZE),
+    colorCount,
+  };
+};

package/src/utils/readJsonFile/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Read and parse a JSON file, returning null if it doesn't exist or fails to parse.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+
+export const readJsonFile = (path: string): unknown => {
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as unknown;
+  } catch {
+    return null;
+  }
+};

package/src/utils/rotateLogFile/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Log file rotation utility.
+ *
+ * Rotates a log file when it exceeds a maximum size, keeping a
+ * configurable number of backup files (e.g., log.1, log.2, log.3).
+ */
+
+import { existsSync, statSync, renameSync, unlinkSync } from 'fs';
+
+/**
+ * Rotate a log file if it exceeds maxSizeBytes.
+ * Keeps up to maxBackups numbered backups (log.1, log.2, ...).
+ */
+export const rotateLogFile = (logPath: string, maxSizeBytes: number, maxBackups: number): void => {
+  if (!existsSync(logPath)) {
+    return;
+  }
+
+  try {
+    const stats = statSync(logPath);
+
+    if (stats.size < maxSizeBytes) {
+      return;
+    }
+
+    // Rotate existing backups
+    for (let i = maxBackups - 1; i >= 1; i--) {
+      const oldPath = `${logPath}.${i}`;
+      const newPath = `${logPath}.${i + 1}`;
+      if (existsSync(oldPath)) {
+        if (i === maxBackups - 1) {
+          unlinkSync(oldPath);
+        } else {
+          renameSync(oldPath, newPath);
+        }
+      }
+    }
+
+    // Move current log to .1
+    renameSync(logPath, `${logPath}.1`);
+  } catch {
+    // Ignore rotation errors
+  }
+};

package/src/utils/safeClose/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Safely close a resource, ignoring any errors during cleanup.
+ */
+export const safeClose = (resource: { close: () => void }): void => {
+  try {
+    resource.close();
+  } catch {
+    // Ignore errors during cleanup
+  }
+};

package/src/utils/terminal/consts.ts

@@ -0,0 +1,8 @@
+/** Default terminal width in columns */
+export const DEFAULT_TERMINAL_WIDTH = 80;
+
+/** Default terminal height in rows */
+export const DEFAULT_TERMINAL_HEIGHT = 24;
+
+/** Delay in milliseconds for stdin release after Ink cleanup */
+export const INK_CLEANUP_DELAY_MS = 100;