@drmxrcy/tcg-core 0.0.0-202602060542

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @drmxrcy/tcg-core - Core TCG Engine Framework
+ *
+ * A declarative, type-safe framework for building trading card game engines.
+ */
+
+export * from "./actions/action-definition";
+export * from "./actions/action-timing";
+export * from "./cards/card-definition";
+export * from "./cards/card-instance";
+export * from "./cards/computed-properties";
+export * from "./cards/modifiers";
+export * from "./engine";
+export * from "./engine/tracker-system";
+export * from "./filtering/card-filter";
+export * from "./filtering/card-query";
+export * from "./filtering/filter-matching";
+export * from "./flow";
+export * from "./game-definition";
+export * from "./history";
+export * from "./logging";
+export * from "./moves/create-move";
+export * from "./moves/move-enumeration";
+export * from "./moves/move-executor";
+export * from "./moves/move-system";
+export * from "./moves/standard-moves";
+export * from "./operations";
+export * from "./rng/seeded-rng";
+export * from "./targeting";
+export * from "./telemetry";
+export * from "./types";
+export * from "./zones";

package/src/logging/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Logging Module
+ *
+ * Production-grade structured logging for TCG Core.
+ *
+ * @example
+ * ```typescript
+ * import { Logger, LogLevel } from '@drmxrcy/tcg-core/logging';
+ *
+ * const logger = new Logger({
+ *   level: 'DEVELOPER',
+ *   pretty: true
+ * });
+ *
+ * logger.info('Game started', { players: 2 });
+ * logger.debug('Move validated', { moveId, validationResult });
+ * ```
+ */
+
+export { createPinoFormatter, formatMessage } from "./log-formatter";
+export { Logger } from "./logger";
+export {
+  type LogContext,
+  type LoggerOptions,
+  LogLevel,
+  type VerbosityPreset,
+} from "./types";

package/src/logging/log-formatter.ts

@@ -0,0 +1,187 @@
+/**
+ * Log Formatter
+ *
+ * Custom formatters for player-friendly log messages.
+ * Transforms internal engine events into readable output.
+ */
+
+import type { LogContext, VerbosityPreset } from "./types";
+
+/**
+ * Format log message for player-friendly output
+ *
+ * Transforms raw log messages and context into readable format
+ * based on the current verbosity level.
+ *
+ * @param message - Raw log message
+ * @param context - Log context with metadata
+ * @param level - Current verbosity preset
+ * @returns Formatted message string
+ */
+export function formatMessage(
+  message: string,
+  context: LogContext,
+  level: VerbosityPreset,
+): string {
+  // For SILENT, return empty (should never be called)
+  if (level === "SILENT") {
+    return "";
+  }
+
+  // NORMAL_PLAYER: Simple, clear messages
+  if (level === "NORMAL_PLAYER") {
+    return formatForNormalPlayer(message, context);
+  }
+
+  // ADVANCED_PLAYER: Include game mechanics details
+  if (level === "ADVANCED_PLAYER") {
+    return formatForAdvancedPlayer(message, context);
+  }
+
+  // DEVELOPER: Full internal details
+  return formatForDeveloper(message, context);
+}
+
+/**
+ * Format message for normal players
+ *
+ * Focus on basic game events without technical details.
+ * Examples: "Card played", "Turn ended", "Player drew 2 cards"
+ */
+function formatForNormalPlayer(message: string, context: LogContext): string {
+  let formatted = message;
+
+  // Add player context if available
+  if (context.playerId) {
+    formatted = `[Player ${context.playerId}] ${formatted}`;
+  }
+
+  // Add turn context if available
+  if (context.turn !== undefined) {
+    formatted = `[Turn ${context.turn}] ${formatted}`;
+  }
+
+  return formatted;
+}
+
+/**
+ * Format message for advanced players
+ *
+ * Include game mechanics and rule details.
+ * Examples: "Card played (cost: 3 mana)", "Phase transition: Main -> Combat"
+ */
+function formatForAdvancedPlayer(message: string, context: LogContext): string {
+  let formatted = message;
+
+  // Add comprehensive game state context
+  const contextParts: string[] = [];
+
+  if (context.turn !== undefined) {
+    contextParts.push(`Turn ${context.turn}`);
+  }
+
+  if (context.phase) {
+    contextParts.push(`Phase: ${context.phase}`);
+  }
+
+  if (context.playerId) {
+    contextParts.push(`Player: ${context.playerId}`);
+  }
+
+  if (contextParts.length > 0) {
+    formatted = `[${contextParts.join(" | ")}] ${formatted}`;
+  }
+
+  // Add duration for performance-sensitive operations
+  if (context.duration !== undefined) {
+    formatted += ` (${context.duration}ms)`;
+  }
+
+  return formatted;
+}
+
+/**
+ * Format message for developers
+ *
+ * Include all internal details for debugging.
+ * Examples: Full context object, stack traces, state diffs
+ */
+function formatForDeveloper(message: string, context: LogContext): string {
+  let formatted = message;
+
+  // Add full context breadcrumbs
+  const contextParts: string[] = [];
+
+  if (context.turn !== undefined) {
+    contextParts.push(`T${context.turn}`);
+  }
+
+  if (context.segment) {
+    contextParts.push(`S:${context.segment}`);
+  }
+
+  if (context.phase) {
+    contextParts.push(`P:${context.phase}`);
+  }
+
+  if (context.playerId) {
+    contextParts.push(`Player:${context.playerId}`);
+  }
+
+  if (context.moveId) {
+    contextParts.push(`Move:${context.moveId}`);
+  }
+
+  if (contextParts.length > 0) {
+    formatted = `[${contextParts.join("|")}] ${formatted}`;
+  }
+
+  // Add performance metrics
+  if (context.duration !== undefined) {
+    formatted += ` [${context.duration}ms]`;
+  }
+
+  if (context.patchCount !== undefined) {
+    formatted += ` [${context.patchCount} patches]`;
+  }
+
+  // Add error details
+  if (context.errorCode) {
+    formatted += ` [${context.errorCode}]`;
+  }
+
+  return formatted;
+}
+
+/**
+ * Create Pino formatter options
+ *
+ * Returns Pino transport configuration for pretty printing
+ * based on verbosity level.
+ *
+ * @param level - Verbosity preset
+ * @returns Pino transport options
+ */
+export function createPinoFormatter(level: VerbosityPreset): unknown {
+  // For SILENT, no formatter needed
+  if (level === "SILENT") {
+    return undefined;
+  }
+
+  // Configure pino-pretty for human-readable output
+  return {
+    target: "pino-pretty",
+    options: {
+      colorize: true,
+      translateTime: "HH:MM:ss.l",
+      ignore: "pid,hostname",
+      // Customize format based on level
+      messageFormat:
+        level === "DEVELOPER"
+          ? "{msg} {context}"
+          : level === "ADVANCED_PLAYER"
+            ? "{msg}"
+            : "{msg}",
+    },
+  };
+}

package/src/logging/logger.ts

@@ -0,0 +1,276 @@
+/**
+ * Logger Class
+ *
+ * Core logging implementation wrapping Pino with TCG-specific features.
+ * Provides structured logging with configurable verbosity levels.
+ */
+
+import pino, { type Logger as PinoLogger } from "pino";
+import { type LogContext, type LoggerOptions, LogLevel } from "./types";
+
+/**
+ * Logger
+ *
+ * Structured logger with verbosity control and child logger support.
+ *
+ * Features:
+ * - Zero-overhead SILENT mode
+ * - Child loggers with namespace isolation
+ * - Structured context merging
+ * - Preset-based verbosity levels
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger({ level: 'DEVELOPER', pretty: true });
+ *
+ * logger.info('Game started', { players: 2 });
+ * logger.debug('Move executed', { moveId: 'playCard', duration: 15 });
+ *
+ * const childLogger = logger.child('flow');
+ * childLogger.info('Phase transition', { from: 'main', to: 'combat' });
+ * ```
+ */
+export class Logger {
+  private pinoLogger: PinoLogger | null;
+  private currentLevel: LogLevel;
+  private namespace?: string;
+
+  /**
+   * Create a new Logger instance
+   *
+   * @param options - Logger configuration
+   */
+  constructor(options: LoggerOptions = {}) {
+    const level = options.level ?? "SILENT";
+
+    // Map preset/level to numeric LogLevel
+    this.currentLevel = this.mapToLogLevel(level);
+
+    // For SILENT mode, skip Pino initialization entirely (zero overhead)
+    if (this.currentLevel === LogLevel.SILENT) {
+      this.pinoLogger = null;
+      return;
+    }
+
+    // Map to Pino level strings
+    const pinoLevel = this.mapToPinoLevel(this.currentLevel);
+
+    // Configure Pino
+    const { level: _, ...restOptions } = options;
+    const pinoOptions: pino.LoggerOptions = {
+      level: pinoLevel,
+      ...restOptions,
+    };
+
+    // Add pretty printing if requested
+    if (options.pretty !== false) {
+      pinoOptions.transport = {
+        target: "pino-pretty",
+        options: {
+          colorize: true,
+          translateTime: "HH:MM:ss.l",
+          ignore: "pid,hostname",
+        },
+      };
+    }
+
+    // Create Pino logger
+    this.pinoLogger = pino(pinoOptions);
+  }
+
+  /**
+   * Map preset or numeric level to LogLevel enum
+   */
+  private mapToLogLevel(level: string | LogLevel): LogLevel {
+    if (typeof level === "number") {
+      return level;
+    }
+
+    // Map preset strings to LogLevel
+    const presetMap: Record<string, LogLevel> = {
+      SILENT: LogLevel.SILENT,
+      NORMAL_PLAYER: LogLevel.INFO,
+      ADVANCED_PLAYER: LogLevel.DEBUG,
+      DEVELOPER: LogLevel.TRACE,
+    };
+
+    return presetMap[level] ?? LogLevel.SILENT;
+  }
+
+  /**
+   * Map LogLevel to Pino level string
+   */
+  private mapToPinoLevel(level: LogLevel): pino.Level | "silent" {
+    const levelMap: Record<LogLevel, pino.Level | "silent"> = {
+      [LogLevel.SILENT]: "silent",
+      [LogLevel.ERROR]: "error",
+      [LogLevel.WARN]: "warn",
+      [LogLevel.INFO]: "info",
+      [LogLevel.DEBUG]: "debug",
+      [LogLevel.TRACE]: "trace",
+    };
+
+    return levelMap[level] ?? "silent";
+  }
+
+  /**
+   * Check if a specific level is enabled
+   */
+  private isLevelEnabled(level: LogLevel): boolean {
+    return this.currentLevel >= level;
+  }
+
+  /**
+   * Merge namespace into context
+   */
+  private mergeContext(context?: LogContext): LogContext {
+    if (!this.namespace) {
+      return context ?? {};
+    }
+
+    return {
+      namespace: this.namespace,
+      ...context,
+    };
+  }
+
+  /**
+   * Log trace message (TRACE level)
+   *
+   * Most verbose logging for internal operations.
+   * Use for: operation details, state diffs, decision trees
+   *
+   * @param message - Log message
+   * @param context - Structured context
+   */
+  trace(message: string, context?: LogContext): void {
+    // Zero-overhead check for SILENT mode
+    if (!(this.pinoLogger && this.isLevelEnabled(LogLevel.TRACE))) {
+      return;
+    }
+
+    this.pinoLogger.trace(this.mergeContext(context), message);
+  }
+
+  /**
+   * Log debug message (DEBUG level)
+   *
+   * Detailed information for debugging and analysis.
+   * Use for: rule evaluations, condition checks, mechanics
+   *
+   * @param message - Log message
+   * @param context - Structured context
+   */
+  debug(message: string, context?: LogContext): void {
+    // Zero-overhead check for SILENT mode
+    if (!(this.pinoLogger && this.isLevelEnabled(LogLevel.DEBUG))) {
+      return;
+    }
+
+    this.pinoLogger.debug(this.mergeContext(context), message);
+  }
+
+  /**
+   * Log info message (INFO level)
+   *
+   * Standard informational messages about game events.
+   * Use for: move execution, phase transitions, game events
+   *
+   * @param message - Log message
+   * @param context - Structured context
+   */
+  info(message: string, context?: LogContext): void {
+    // Zero-overhead check for SILENT mode
+    if (!(this.pinoLogger && this.isLevelEnabled(LogLevel.INFO))) {
+      return;
+    }
+
+    this.pinoLogger.info(this.mergeContext(context), message);
+  }
+
+  /**
+   * Log warning message (WARN level)
+   *
+   * Warning conditions that don't prevent execution.
+   * Use for: failed conditions, invalid moves, edge cases
+   *
+   * @param message - Log message
+   * @param context - Structured context
+   */
+  warn(message: string, context?: LogContext): void {
+    // Zero-overhead check for SILENT mode
+    if (!(this.pinoLogger && this.isLevelEnabled(LogLevel.WARN))) {
+      return;
+    }
+
+    this.pinoLogger.warn(this.mergeContext(context), message);
+  }
+
+  /**
+   * Log error message (ERROR level)
+   *
+   * Error conditions requiring attention.
+   * Use for: exceptions, failures, critical errors
+   *
+   * @param message - Log message
+   * @param context - Structured context
+   */
+  error(message: string, context?: LogContext): void {
+    // Zero-overhead check for SILENT mode
+    if (!(this.pinoLogger && this.isLevelEnabled(LogLevel.ERROR))) {
+      return;
+    }
+
+    this.pinoLogger.error(this.mergeContext(context), message);
+  }
+
+  /**
+   * Create child logger with namespace
+   *
+   * Child loggers inherit configuration but add a namespace
+   * to all log entries for filtering and organization.
+   *
+   * @param namespace - Namespace identifier (e.g., 'flow', 'zones')
+   * @returns New Logger instance with namespace
+   *
+   * @example
+   * ```typescript
+   * const logger = new Logger({ level: 'DEBUG' });
+   * const flowLogger = logger.child('flow');
+   *
+   * flowLogger.info('Phase transition');
+   * // Output: [flow] Phase transition
+   * ```
+   */
+  child(namespace: string): Logger {
+    // For SILENT mode, return a new SILENT logger
+    if (!this.pinoLogger) {
+      return new Logger({ level: "SILENT" });
+    }
+
+    // Create child with Pino child logger
+    const childLogger = new Logger({ level: this.currentLevel });
+    childLogger.pinoLogger = this.pinoLogger.child({ namespace });
+    childLogger.namespace = namespace;
+
+    return childLogger;
+  }
+
+  /**
+   * Get current log level
+   *
+   * @returns Current LogLevel
+   */
+  getLevel(): LogLevel {
+    return this.currentLevel;
+  }
+
+  /**
+   * Check if logger is in SILENT mode
+   *
+   * @returns True if no logging will occur
+   */
+  isSilent(): boolean {
+    return this.currentLevel === LogLevel.SILENT;
+  }
+}

package/src/logging/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Logging Types
+ *
+ * Type definitions for the TCG Core logging system.
+ * Provides structured logging with configurable verbosity levels.
+ */
+
+/**
+ * Log Level Enum
+ *
+ * Numeric levels for log filtering (lower = more critical)
+ * - SILENT (0): No logging
+ * - ERROR (1): Error conditions only
+ * - WARN (2): Warning conditions
+ * - INFO (3): Informational messages
+ * - DEBUG (4): Debug-level messages
+ * - TRACE (5): Trace-level messages (most verbose)
+ */
+export enum LogLevel {
+  SILENT = 0,
+  ERROR = 1,
+  WARN = 2,
+  INFO = 3,
+  DEBUG = 4,
+  TRACE = 5,
+}
+
+/**
+ * Verbosity Preset
+ *
+ * Named presets for different user types:
+ * - SILENT: No logging (production default)
+ * - NORMAL_PLAYER: Basic game events (INFO level)
+ * - ADVANCED_PLAYER: Detailed mechanics (DEBUG level)
+ * - DEVELOPER: Full internal details (TRACE level)
+ */
+export type VerbosityPreset =
+  | "SILENT"
+  | "NORMAL_PLAYER"
+  | "ADVANCED_PLAYER"
+  | "DEVELOPER";
+
+/**
+ * Log Context
+ *
+ * Structured context information attached to log entries.
+ * Provides rich metadata for filtering, searching, and analysis.
+ *
+ * Common fields:
+ * - moveId: Move being executed
+ * - playerId: Player performing action
+ * - phase: Current game phase
+ * - turn: Current turn number
+ * - timestamp: Event timestamp
+ *
+ * Games can add custom fields via index signature.
+ */
+export type LogContext = {
+  /** Move identifier */
+  moveId?: string;
+  /** Player identifier */
+  playerId?: string;
+  /** Current game phase */
+  phase?: string;
+  /** Current game segment */
+  segment?: string;
+  /** Current turn number */
+  turn?: number;
+  /** Event timestamp */
+  timestamp?: number;
+  /** Error message (for error logs) */
+  error?: string;
+  /** Stack trace (for error logs) */
+  stack?: string;
+  /** Error code (for structured errors) */
+  errorCode?: string;
+  /** Operation duration in milliseconds */
+  duration?: number;
+  /** Number of patches generated */
+  patchCount?: number;
+  /** Custom context fields */
+  [key: string]: unknown;
+};
+
+/**
+ * Logger Options
+ *
+ * Configuration for Logger instances.
+ *
+ * @example
+ * ```typescript
+ * // Use preset for convenience
+ * const options: LoggerOptions = {
+ *   level: 'DEVELOPER',
+ *   pretty: true
+ * };
+ *
+ * // Or use numeric level for fine control
+ * const options: LoggerOptions = {
+ *   level: LogLevel.DEBUG,
+ *   pretty: false,
+ *   destination: process.stdout
+ * };
+ * ```
+ */
+export type LoggerOptions = {
+  /**
+   * Log level or verbosity preset
+   *
+   * Controls which messages are logged:
+   * - String presets: SILENT, NORMAL_PLAYER, ADVANCED_PLAYER, DEVELOPER
+   * - Numeric levels: LogLevel.SILENT through LogLevel.TRACE
+   *
+   * Default: 'SILENT' (no logging)
+   */
+  level?: VerbosityPreset | LogLevel;
+
+  /**
+   * Enable pretty printing
+   *
+   * When true, formats logs for human readability.
+   * When false, outputs JSON for machine consumption.
+   *
+   * Default: true
+   */
+  pretty?: boolean;
+
+  /**
+   * Log destination
+   *
+   * Where to write log output:
+   * - process.stdout (default)
+   * - process.stderr
+   * - Writable stream
+   * - File descriptor
+   *
+   * Default: process.stdout
+   */
+  destination?: unknown;
+
+  /**
+   * Additional Pino options
+   *
+   * Advanced configuration passed directly to Pino.
+   * See Pino documentation for available options.
+   */
+  [key: string]: unknown;
+};