Add basic diagnostics with categorization

Author: b3ncr0w

.claude/settings.local.json

@@ -3,7 +3,8 @@
     "allow": [
       "Bash(ls:*)",
       "Bash(find:*)",
-      "Bash(grep:*)"
+      "Bash(grep:*)",
+      "mcp__ide__getDiagnostics"
     ],
     "deny": []
   }

Runtime/Scripts/BetaHubDiagnostics.cs

@@ -0,0 +1,194 @@
+using System;
+using UnityEngine;
+
+namespace BetaHub
+{
+    /// <summary>
+    /// Interface for contextual diagnostics providing error handling and logging capabilities.
+    /// </summary>
+    public interface IContextualDiagnostics
+    {
+        /// <summary>
+        /// Logs an informational message for an operation.
+        /// </summary>
+        /// <param name="operation">The operation name</param>
+        /// <param name="message">The message to log</param>
+        void LogInfo(string operation, string message);
+
+        /// <summary>
+        /// Logs a successful operation completion.
+        /// </summary>
+        /// <param name="operation">The operation name</param>
+        /// <param name="message">The success message</param>
+        void LogSuccess(string operation, string message);
+
+        /// <summary>
+        /// Logs progress information for a long-running operation.
+        /// </summary>
+        /// <param name="operation">The operation name</param>
+        /// <param name="message">The progress message</param>
+        void LogProgress(string operation, string message);
+
+        /// <summary>
+        /// Logs an error with automatic exception categorization and retry analysis.
+        /// </summary>
+        /// <param name="operation">The operation name</param>
+        /// <param name="ex">The exception that occurred</param>
+        void LogError(string operation, Exception ex);
+
+        /// <summary>
+        /// Logs an error with explicit categorization and retry information.
+        /// </summary>
+        /// <param name="operation">The operation name</param>
+        /// <param name="message">The error message</param>
+        /// <param name="category">The error category</param>
+        /// <param name="isRetryable">Whether the error is retryable</param>
+        void LogError(string operation, string message, BetaHubErrorCategory category = BetaHubErrorCategory.Unknown, bool isRetryable = false);
+    }
+
+    /// <summary>
+    /// Main entry point for BetaHub diagnostics. Provides contextual diagnostics services
+    /// for consistent error handling and logging across the plugin.
+    /// </summary>
+    public static class BetaHubDiagnostics
+    {
+        /// <summary>
+        /// Creates a contextual diagnostics service for a specific component or operation context.
+        /// </summary>
+        /// <param name="contextName">The name of the context (e.g., "Issue(abc123)", "GameRecorder", etc.)</param>
+        /// <returns>A contextual diagnostics service instance</returns>
+        public static IContextualDiagnostics ForContext(string contextName)
+        {
+            return new ContextualDiagnostics(contextName);
+        }
+    }
+
+    /// <summary>
+    /// Implementation of contextual diagnostics that provides consistent logging and error handling
+    /// for a specific context (component, operation, or scope).
+    /// </summary>
+    internal class ContextualDiagnostics : IContextualDiagnostics
+    {
+        private readonly string _contextName;
+
+        /// <summary>
+        /// Initializes a new instance of contextual diagnostics for the specified context.
+        /// </summary>
+        /// <param name="contextName">The context name to include in all log messages</param>
+        public ContextualDiagnostics(string contextName)
+        {
+            _contextName = contextName ?? throw new ArgumentNullException(nameof(contextName));
+        }
+
+        /// <summary>
+        /// Logs an informational message for an operation.
+        /// </summary>
+        /// <param name="operation">The operation name</param>
+        /// <param name="message">The message to log</param>
+        public void LogInfo(string operation, string message)
+        {
+            Debug.Log($"[INFO] {_contextName}.{operation}: {message}");
+        }
+
+        /// <summary>
+        /// Logs a successful operation completion.
+        /// </summary>
+        /// <param name="operation">The operation name</param>
+        /// <param name="message">The success message</param>
+        public void LogSuccess(string operation, string message)
+        {
+            Debug.Log($"[SUCCESS] {_contextName}.{operation}: {message}");
+        }
+
+        /// <summary>
+        /// Logs progress information for a long-running operation.
+        /// </summary>
+        /// <param name="operation">The operation name</param>
+        /// <param name="message">The progress message</param>
+        public void LogProgress(string operation, string message)
+        {
+            Debug.Log($"[PROGRESS] {_contextName}.{operation}: {message}");
+        }
+
+        /// <summary>
+        /// Logs an error with automatic exception categorization and retry analysis.
+        /// </summary>
+        /// <param name="operation">The operation name</param>
+        /// <param name="ex">The exception that occurred</param>
+        public void LogError(string operation, Exception ex)
+        {
+            var category = BetaHubErrorHelper.CategorizeException(ex);
+            var isRetryable = BetaHubErrorHelper.IsRetryable(ex);
+            LogError(operation, ex.Message, category, isRetryable);
+        }
+
+        /// <summary>
+        /// Logs an error with explicit categorization and retry information.
+        /// </summary>
+        /// <param name="operation">The operation name</param>
+        /// <param name="message">The error message</param>
+        /// <param name="category">The error category</param>
+        /// <param name="isRetryable">Whether the error is retryable</param>
+        public void LogError(string operation, string message, BetaHubErrorCategory category = BetaHubErrorCategory.Unknown, bool isRetryable = false)
+        {
+            string retryInfo = isRetryable ? " (Retryable)" : " (Not retryable)";
+            Debug.LogError($"[ERROR] {_contextName}.{operation} [{category}]: {message}{retryInfo}");
+        }
+    }
+
+    /// <summary>
+    /// Configuration class for BetaHub diagnostics behavior.
+    /// Allows customization of logging levels and formatting.
+    /// </summary>
+    public static class BetaHubDiagnosticsConfig
+    {
+        /// <summary>
+        /// Gets or sets whether to include timestamps in log messages.
+        /// Default: false (Unity Console already includes timestamps)
+        /// </summary>
+        public static bool IncludeTimestamps { get; set; } = false;
+
+        /// <summary>
+        /// Gets or sets whether to include stack traces in error logs.
+        /// Default: false (Unity Console shows stack traces separately)
+        /// </summary>
+        public static bool IncludeStackTraces { get; set; } = false;
+
+        /// <summary>
+        /// Gets or sets the minimum log level to output.
+        /// Can be used to reduce log verbosity in production builds.
+        /// </summary>
+        public static BetaHubLogLevel MinimumLogLevel { get; set; } = BetaHubLogLevel.Info;
+    }
+
+    /// <summary>
+    /// Log levels for BetaHub diagnostics.
+    /// </summary>
+    public enum BetaHubLogLevel
+    {
+        /// <summary>
+        /// Progress and detailed information
+        /// </summary>
+        Progress = 0,
+
+        /// <summary>
+        /// General information
+        /// </summary>
+        Info = 1,
+
+        /// <summary>
+        /// Success notifications
+        /// </summary>
+        Success = 2,
+
+        /// <summary>
+        /// Error messages only
+        /// </summary>
+        Error = 3,
+
+        /// <summary>
+        /// No logging
+        /// </summary>
+        None = 4
+    }
+}

Runtime/Scripts/ErrorHandler.cs.meta renamed to Runtime/Scripts/BetaHubDiagnostics.cs.meta

@@ -0,0 +1,150 @@
+using System;
+using System.IO;
+using UnityEngine;
+
+namespace BetaHub
+{
+    /// <summary>
+    /// Categories of errors that can occur in the BetaHub plugin operations.
+    /// Used for consistent error handling and retry logic across all components.
+    /// </summary>
+    public enum BetaHubErrorCategory
+    {
+        /// <summary>
+        /// Unknown or uncategorized error type
+        /// </summary>
+        Unknown,
+
+        /// <summary>
+        /// Network-related errors (HTTP requests, connectivity issues)
+        /// Generally retryable with appropriate backoff
+        /// </summary>
+        Network,
+
+        /// <summary>
+        /// Authentication and authorization failures
+        /// Usually not retryable without user intervention
+        /// </summary>
+        Authentication,
+
+        /// <summary>
+        /// File system access errors (file not found, permission denied, etc.)
+        /// Usually not retryable unless temporary lock issues
+        /// </summary>
+        FileAccess,
+
+        /// <summary>
+        /// Input validation errors (invalid parameters, malformed data)
+        /// Not retryable without fixing the input
+        /// </summary>
+        Validation,
+
+        /// <summary>
+        /// Timeout errors (operation took too long)
+        /// Often retryable with longer timeout or retry logic
+        /// </summary>
+        Timeout,
+
+        /// <summary>
+        /// Server-side errors (5xx HTTP status codes)
+        /// May be retryable depending on the specific error
+        /// </summary>
+        ServerError
+    }
+
+    /// <summary>
+    /// Utility class for error categorization and retry logic determination.
+    /// </summary>
+    public static class BetaHubErrorHelper
+    {
+        /// <summary>
+        /// Categorizes an exception into a BetaHubErrorCategory for consistent error handling.
+        /// </summary>
+        /// <param name="ex">The exception to categorize</param>
+        /// <returns>The appropriate error category</returns>
+        public static BetaHubErrorCategory CategorizeException(Exception ex)
+        {
+            return ex switch
+            {
+                TimeoutException => BetaHubErrorCategory.Timeout,
+                UnauthorizedAccessException => BetaHubErrorCategory.Authentication,
+                FileNotFoundException or DirectoryNotFoundException => BetaHubErrorCategory.FileAccess,
+                IOException ioEx when ioEx.Message.Contains("being used by another process") => BetaHubErrorCategory.FileAccess,
+                IOException => BetaHubErrorCategory.FileAccess,
+                ArgumentException or ArgumentNullException => BetaHubErrorCategory.Validation,
+                InvalidOperationException invalidOp when invalidOp.Message.Contains("HTTP") => BetaHubErrorCategory.Network,
+                InvalidOperationException invalidOp when invalidOp.Message.Contains("401") => BetaHubErrorCategory.Authentication,
+                InvalidOperationException invalidOp when invalidOp.Message.Contains("403") => BetaHubErrorCategory.Authentication,
+                InvalidOperationException invalidOp when invalidOp.Message.Contains("5") && invalidOp.Message.Contains("HTTP") => BetaHubErrorCategory.ServerError,
+                _ => BetaHubErrorCategory.Unknown
+            };
+        }
+
+        /// <summary>
+        /// Determines if an error category is generally retryable.
+        /// </summary>
+        /// <param name="category">The error category to check</param>
+        /// <returns>True if the error type is generally retryable</returns>
+        public static bool IsRetryable(BetaHubErrorCategory category)
+        {
+            return category switch
+            {
+                BetaHubErrorCategory.Network => true,
+                BetaHubErrorCategory.Timeout => true,
+                BetaHubErrorCategory.ServerError => true,
+                BetaHubErrorCategory.FileAccess => false, // Usually permanent unless lock issues
+                BetaHubErrorCategory.Authentication => false,
+                BetaHubErrorCategory.Validation => false,
+                BetaHubErrorCategory.Unknown => false,
+                _ => false
+            };
+        }
+
+        /// <summary>
+        /// Gets a human-readable description of an error category.
+        /// </summary>
+        /// <param name="category">The error category</param>
+        /// <returns>A descriptive string for the category</returns>
+        public static string GetCategoryDescription(BetaHubErrorCategory category)
+        {
+            return category switch
+            {
+                BetaHubErrorCategory.Network => "Network connectivity or HTTP error",
+                BetaHubErrorCategory.Authentication => "Authentication or authorization failure",
+                BetaHubErrorCategory.FileAccess => "File system access error",
+                BetaHubErrorCategory.Validation => "Input validation error",
+                BetaHubErrorCategory.Timeout => "Operation timeout",
+                BetaHubErrorCategory.ServerError => "Server-side error",
+                BetaHubErrorCategory.Unknown => "Unknown error",
+                _ => "Unrecognized error category"
+            };
+        }
+
+        /// <summary>
+        /// Determines if a specific exception instance is retryable based on both category and content.
+        /// </summary>
+        /// <param name="ex">The exception to analyze</param>
+        /// <returns>True if this specific exception instance should be retried</returns>
+        public static bool IsRetryable(Exception ex)
+        {
+            var category = CategorizeException(ex);
+            
+            // Special cases where category-level retry logic might be overridden
+            switch (category)
+            {
+                case BetaHubErrorCategory.FileAccess:
+                    // File access might be retryable if it's a temporary lock
+                    return ex.Message.Contains("being used by another process") || 
+                           ex.Message.Contains("access denied") ||
+                           ex is UnauthorizedAccessException;
+                
+                case BetaHubErrorCategory.ServerError:
+                    // Some server errors shouldn't be retried (e.g., 501 Not Implemented)
+                    return !ex.Message.Contains("501") && !ex.Message.Contains("505");
+                
+                default:
+                    return IsRetryable(category);
+            }
+        }
+    }
+}