uncaught 0.1.0

data/lib/uncaught/prompt_builder.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Uncaught
+  module PromptBuilder
+    module_function
+
+    # Build a structured Markdown prompt that can be pasted into an AI assistant
+    # to diagnose and fix the production error described by the event.
+    #
+    # Empty sections are omitted to keep the prompt concise.
+    #
+    # @param event [UncaughtEvent]
+    # @return [String]
+    def build(event)
+      sections = []
+
+      # ----- Intro -----------------------------------------------------------
+      sections << "I have a production bug in my application that I need help diagnosing and fixing.\n"
+
+      # ----- Error -----------------------------------------------------------
+      if event.error
+        location = extract_location(event.error.stack)
+        lines = ["## Error", ""]
+        lines << "- **Type:** #{event.error.type || 'Error'}"
+        lines << "- **Message:** #{event.error.message || '(no message)'}"
+        lines << "- **Location:** #{location}" if location
+        sections << lines.join("\n")
+      end
+
+      # ----- Stack Trace -----------------------------------------------------
+      stack_source = event.error&.resolved_stack || event.error&.stack
+      if stack_source && !stack_source.empty?
+        frames = stack_source.split("\n").first(15).map(&:rstrip).join("\n")
+        label = event.error&.resolved_stack ? "Stack Trace (source-mapped)" : "Stack Trace"
+        sections << "## #{label}\n\n```\n#{frames}\n```"
+      end
+
+      # ----- Failed Operation ------------------------------------------------
+      if event.operation
+        sections << format_operation(event.operation)
+      end
+
+      # ----- HTTP Request Context --------------------------------------------
+      if event.request
+        sections << format_request(event.request)
+      end
+
+      # ----- User Session (last 5 breadcrumbs) -------------------------------
+      if event.breadcrumbs && !event.breadcrumbs.empty?
+        sections << format_breadcrumbs(event.breadcrumbs)
+      end
+
+      # ----- Environment -----------------------------------------------------
+      if event.environment
+        sections << format_environment(event.environment)
+      end
+
+      # ----- Component Stack -------------------------------------------------
+      if event.error&.component_stack && !event.error.component_stack.empty?
+        sections << "## React Component Stack\n\n```\n#{event.error.component_stack.strip}\n```"
+      end
+
+      # ----- What I need -----------------------------------------------------
+      sections << [
+        "## What I need",
+        "",
+        "1. **Root cause analysis** -- explain why this error is occurring.",
+        "2. **A fix** -- provide the corrected code with an explanation of the changes.",
+        "3. **Prevention** -- suggest any guards or tests to prevent this from happening again."
+      ].join("\n")
+
+      sections.join("\n\n") + "\n"
+    end
+
+    # -------------------------------------------------------------------------
+    # Internal helpers
+    # -------------------------------------------------------------------------
+
+    # Extract the top-most location (file:line:col) from a stack trace string.
+    def extract_location(stack)
+      return nil unless stack
+
+      stack.split("\n").each do |line|
+        trimmed = line.strip
+
+        # V8: "    at fn (file:line:col)"
+        v8 = trimmed.match(/at\s+(?:.+?\s+\()?(.+?:\d+:\d+)\)?/)
+        return v8[1] if v8
+
+        # SpiderMonkey / JSC: "fn@file:line:col"
+        sm = trimmed.match(/@(.+?:\d+:\d+)/)
+        return sm[1] if sm
+
+        # Ruby: "/path/to/file.rb:42:in `method'"
+        rb = trimmed.match(%r{(.+?:\d+):in\s+})
+        return rb[1] if rb
+      end
+
+      nil
+    end
+
+    def format_operation(op)
+      lines = ["## Failed Operation", ""]
+      lines << "- **Provider:** #{op.provider}"
+      lines << "- **Type:** #{op.type}"
+      lines << "- **Method:** #{op.method}"
+      if op.params
+        lines << "- **Params:**"
+        lines << "```json"
+        lines << JSON.pretty_generate(op.params)
+        lines << "```"
+      end
+      lines << "- **Error Code:** #{op.error_code}" if op.error_code
+      lines << "- **Error Details:** #{op.error_details}" if op.error_details
+      lines.join("\n")
+    end
+
+    def format_request(req)
+      lines = ["## HTTP Request Context", ""]
+      lines << "- **Method:** #{req.method}" if req.method
+      lines << "- **URL:** #{req.url}" if req.url
+      if req.body
+        lines << "- **Body:**"
+        lines << "```json"
+        lines << (req.body.is_a?(String) ? req.body : JSON.pretty_generate(req.body))
+        lines << "```"
+      end
+      lines.join("\n")
+    end
+
+    def format_breadcrumbs(crumbs)
+      recent = crumbs.last(5)
+      lines = ["## User Session", ""]
+      recent.each do |crumb|
+        time = format_time(crumb.timestamp)
+        lines << "- `#{time}` **[#{crumb.type}]** #{crumb.message}"
+      end
+      lines.join("\n")
+    end
+
+    # Extract HH:MM:SS from an ISO timestamp.
+    def format_time(iso)
+      t = Time.parse(iso)
+      t.strftime("%H:%M:%S")
+    rescue
+      iso.to_s
+    end
+
+    def format_environment(env)
+      lines = ["## Environment", ""]
+      entries = [
+        ["Deploy Environment", env.deploy],
+        ["Framework", env.framework],
+        ["Framework Version", env.framework_version],
+        ["Runtime", env.runtime],
+        ["Runtime Version", env.runtime_version],
+        ["Platform", env.platform],
+        ["Browser", env.browser ? "#{env.browser} #{env.browser_version}".strip : nil],
+        ["OS", env.os],
+        ["Device", env.device_type],
+        ["Locale", env.locale],
+        ["Timezone", env.timezone],
+        ["URL", env.url]
+      ]
+      entries.each do |label, value|
+        lines << "- **#{label}:** #{value}" if value && !value.to_s.empty?
+      end
+      lines.join("\n")
+    end
+
+    private_class_method :extract_location, :format_operation, :format_request,
+                         :format_breadcrumbs, :format_time, :format_environment
+  end
+end

data/lib/uncaught/rate_limiter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Uncaught
+  # Sliding-window rate limiter.
+  #
+  # Enforces:
+  #   - A global maximum of events per 60-second window.
+  #   - A per-fingerprint maximum of events per 60-second window.
+  #
+  # Thread-safe via Mutex.
+  class RateLimiter
+    # Window duration in seconds.
+    WINDOW_SECONDS = 60
+
+    # @param global_max          [Integer] Max events across all fingerprints. Defaults to 30.
+    # @param per_fingerprint_max [Integer] Max events for a single fingerprint. Defaults to 5.
+    def initialize(global_max: 30, per_fingerprint_max: 5)
+      @global_max = global_max
+      @per_fingerprint_max = per_fingerprint_max
+      @global_timestamps = []
+      @buckets = {}
+      @mutex = Mutex.new
+    end
+
+    # Returns true if the event identified by fingerprint is allowed through,
+    # false if it should be dropped.
+    #
+    # @param fingerprint [String]
+    # @return [Boolean]
+    def should_allow?(fingerprint)
+      @mutex.synchronize do
+        now = Time.now.to_f
+
+        # --- Global limit ---
+        prune!(@global_timestamps, now)
+        return false if @global_timestamps.size >= @global_max
+
+        # --- Per-fingerprint limit ---
+        @buckets[fingerprint] ||= []
+        fp_timestamps = @buckets[fingerprint]
+        prune!(fp_timestamps, now)
+        return false if fp_timestamps.size >= @per_fingerprint_max
+
+        # Record this event
+        @global_timestamps << now
+        fp_timestamps << now
+
+        # Periodic cleanup: remove empty buckets
+        if @buckets.size > 1000
+          @buckets.delete_if { |_k, v| v.empty? }
+        end
+
+        true
+      end
+    end
+
+    private
+
+    # Remove timestamps older than the sliding window from an array (in-place).
+    def prune!(timestamps, now)
+      cutoff = now - WINDOW_SECONDS
+      timestamps.shift while timestamps.any? && timestamps.first <= cutoff
+    end
+  end
+end

data/lib/uncaught/sanitizer.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Uncaught
+  module Sanitizer
+    # Default key patterns that are always redacted.
+    DEFAULT_SENSITIVE_KEYS = %w[
+      password passwd secret token apikey api_key authorization
+      credit_card creditcard card_number cvv ssn social_security
+      private_key access_token refresh_token session_id cookie
+    ].freeze
+
+    # Headers that are always stripped regardless of key matching.
+    SENSITIVE_HEADERS = Set.new(%w[authorization cookie set-cookie]).freeze
+
+    REDACTED = "[REDACTED]"
+    MAX_STRING_LENGTH = 2048
+
+    module_function
+
+    # Deep-clone and sanitise obj, redacting values whose keys match
+    # sensitive patterns.
+    #
+    # - Handles circular references (returns "[Circular]").
+    # - Truncates strings longer than 2048 characters.
+    # - Never mutates the original object.
+    #
+    # @param obj             [Object]  The value to sanitise.
+    # @param additional_keys [Array<String>] Extra key patterns to redact.
+    # @return [Object]
+    def sanitize(obj, additional_keys = [])
+      pattern = build_key_pattern(additional_keys)
+      seen = Set.new
+      walk(obj, pattern, seen, nil)
+    end
+
+    # Build a single Regexp that matches any of the sensitive key patterns
+    # (case-insensitive).
+    def build_key_pattern(additional_keys = [])
+      all_keys = DEFAULT_SENSITIVE_KEYS + (additional_keys || [])
+      escaped = all_keys.map { |k| Regexp.escape(k) }
+      Regexp.new(escaped.join("|"), Regexp::IGNORECASE)
+    end
+
+    def walk(value, pattern, seen, key)
+      # Redact if the current key is sensitive
+      if key && pattern.match?(key.to_s)
+        return REDACTED
+      end
+
+      case value
+      when nil
+        nil
+      when String
+        if value.length > MAX_STRING_LENGTH
+          value[0, MAX_STRING_LENGTH] + "...[truncated]"
+        else
+          value.dup
+        end
+      when Integer, Float, TrueClass, FalseClass
+        value
+      when Symbol
+        value.to_s
+      when Time, DateTime
+        value.iso8601(3)
+      when Array
+        obj_id = value.object_id
+        return "[Circular]" if seen.include?(obj_id)
+
+        seen.add(obj_id)
+        result = value.map { |item| walk(item, pattern, seen, nil) }
+        seen.delete(obj_id)
+        result
+      when Hash
+        obj_id = value.object_id
+        return "[Circular]" if seen.include?(obj_id)
+
+        seen.add(obj_id)
+        result = {}
+        value.each do |k, v|
+          str_key = k.to_s
+          # Always strip sensitive headers
+          if SENSITIVE_HEADERS.include?(str_key.downcase)
+            result[k] = REDACTED
+          else
+            result[k] = walk(v, pattern, seen, str_key)
+          end
+        end
+        seen.delete(obj_id)
+        result
+      when Struct
+        obj_id = value.object_id
+        return "[Circular]" if seen.include?(obj_id)
+
+        seen.add(obj_id)
+        result = value.class.new
+        value.members.each do |member|
+          member_val = value[member]
+          sanitized = walk(member_val, pattern, seen, member.to_s)
+          result[member] = sanitized
+        end
+        seen.delete(obj_id)
+        result
+      else
+        # For other objects, try to convert to string
+        value.to_s
+      end
+    end
+
+    private_class_method :build_key_pattern, :walk
+  end
+end

data/lib/uncaught/transport.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "tempfile"
+
+module Uncaught
+  # Local file transport that writes events to the .uncaught/ directory.
+  #
+  # Uses atomic writes via Tempfile + File.rename.
+  # Updates issues.json index.
+  # Optionally writes to SQLite if the sqlite3 gem is available.
+  class LocalFileTransport
+    # @param config [Configuration]
+    def initialize(config)
+      @config = config
+      @base_dir = config.local_output_dir || File.join(Dir.pwd, ".uncaught")
+      @mutex = Mutex.new
+      @initialised = false
+    end
+
+    # Send an event to the local file system.
+    #
+    # @param event [UncaughtEvent]
+    def send_event(event)
+      ensure_initialised!
+
+      fp = event.fingerprint
+      event_dir = File.join(@base_dir, "events", fp)
+      FileUtils.mkdir_p(event_dir)
+
+      event_hash = event_to_hash(event)
+      event_json = JSON.pretty_generate(event_hash)
+
+      # --- Write timestamped event file (atomic: .tmp -> rename) ----------
+      ts = event.timestamp.gsub(/[:.]/,  "-")
+      event_file = "event-#{ts}.json"
+      event_path = File.join(event_dir, event_file)
+      atomic_write(event_path, event_json)
+
+      # --- Write / overwrite latest.json ---------------------------------
+      latest_path = File.join(event_dir, "latest.json")
+      atomic_write(latest_path, event_json)
+
+      # --- Write fix-prompt Markdown file --------------------------------
+      prompt_file = "#{fp}.md"
+      prompt_path = File.join(@base_dir, "fix-prompts", prompt_file)
+      atomic_write(prompt_path, event.fix_prompt || "")
+
+      # --- Update issues.json index -------------------------------------
+      update_issues_index(event, event_file, prompt_file)
+
+      # --- Also write to SQLite -----------------------------------------
+      write_to_sqlite(event)
+    rescue => e
+      # Never crash the host app.
+      debug_log("LocalFileTransport#send_event failed: #{e.message}")
+    end
+
+    # Flush queued events (no-op for local file transport).
+    def flush
+      # Local file transport writes synchronously per-event; nothing to flush.
+    end
+
+    private
+
+    def ensure_initialised!
+      return if @initialised
+
+      @mutex.synchronize do
+        return if @initialised
+
+        FileUtils.mkdir_p(File.join(@base_dir, "events"))
+        FileUtils.mkdir_p(File.join(@base_dir, "fix-prompts"))
+        ensure_gitignore
+        @initialised = true
+      end
+    end
+
+    def ensure_gitignore
+      gitignore_path = File.join(Dir.pwd, ".gitignore")
+      content = File.exist?(gitignore_path) ? File.read(gitignore_path) : ""
+      unless content.include?(".uncaught")
+        File.open(gitignore_path, "a") do |f|
+          f.write("\n# Uncaught local error store\n.uncaught/\n")
+        end
+      end
+    rescue
+      # Non-critical -- swallow.
+    end
+
+    # Atomic write via tempfile + rename.
+    def atomic_write(path, content)
+      tmp_path = "#{path}.tmp"
+      File.write(tmp_path, content, encoding: "UTF-8")
+      File.rename(tmp_path, path)
+    end
+
+    # Read, update, and atomically write the issues.json index.
+    def update_issues_index(event, event_file, prompt_file)
+      @mutex.synchronize do
+        index_path = File.join(@base_dir, "issues.json")
+
+        issues = []
+        if File.exist?(index_path)
+          begin
+            issues = JSON.parse(File.read(index_path))
+          rescue
+            issues = []
+          end
+        end
+
+        user_id = event.user&.id || event.user&.email || "anonymous"
+        existing = issues.find { |i| i["fingerprint"] == event.fingerprint }
+
+        if existing
+          existing["count"] = (existing["count"] || 0) + 1
+          existing["lastSeen"] = event.timestamp
+          existing["latestEventFile"] = event_file
+          existing["fixPromptFile"] = prompt_file
+          unless (existing["affectedUsers"] || []).include?(user_id)
+            existing["affectedUsers"] = (existing["affectedUsers"] || []) + [user_id]
+          end
+          # Re-open if previously resolved
+          if existing["status"] == "resolved"
+            existing["status"] = "open"
+          end
+        else
+          issues << {
+            "fingerprint" => event.fingerprint,
+            "title" => event.error.message,
+            "errorType" => event.error.type,
+            "count" => 1,
+            "affectedUsers" => [user_id],
+            "firstSeen" => event.timestamp,
+            "lastSeen" => event.timestamp,
+            "status" => "open",
+            "fixPromptFile" => prompt_file,
+            "latestEventFile" => event_file,
+            "release" => event.release,
+            "environment" => event.environment&.deploy
+          }
+        end
+
+        atomic_write(index_path, JSON.pretty_generate(issues))
+      end
+    end
+
+    # Attempt to write to SQLite (best-effort).
+    def write_to_sqlite(event)
+      require "sqlite3"
+      db_path = File.join(@base_dir, "uncaught.db")
+      db = SQLite3::Database.new(db_path)
+
+      db.execute(<<~SQL)
+        CREATE TABLE IF NOT EXISTS events (
+          event_id TEXT PRIMARY KEY,
+          timestamp TEXT NOT NULL,
+          fingerprint TEXT NOT NULL,
+          level TEXT NOT NULL,
+          error_type TEXT,
+          error_message TEXT,
+          stack TEXT,
+          fix_prompt TEXT,
+          created_at TEXT DEFAULT (datetime('now'))
+        )
+      SQL
+
+      db.execute(<<~SQL, [
+        event.event_id, event.timestamp, event.fingerprint, event.level,
+        event.error.type, event.error.message, event.error.stack,
+        event.fix_prompt
+      ])
+        INSERT OR REPLACE INTO events
+          (event_id, timestamp, fingerprint, level, error_type, error_message, stack, fix_prompt)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      SQL
+
+      db.close
+    rescue LoadError
+      # sqlite3 gem not available -- skip.
+    rescue => e
+      debug_log("SQLite write failed: #{e.message}")
+    end
+
+    # Convert an UncaughtEvent struct to a JSON-compatible hash using camelCase
+    # keys to match the TypeScript SDK output format.
+    def event_to_hash(event)
+      hash = {
+        "eventId" => event.event_id,
+        "timestamp" => event.timestamp,
+        "level" => event.level,
+        "fingerprint" => event.fingerprint,
+        "error" => error_to_hash(event.error),
+        "breadcrumbs" => (event.breadcrumbs || []).map { |b| breadcrumb_to_hash(b) },
+        "fixPrompt" => event.fix_prompt || "",
+        "sdk" => sdk_to_hash(event.sdk)
+      }
+
+      hash["projectKey"] = event.project_key if event.project_key
+      hash["release"] = event.release if event.release
+      hash["request"] = request_to_hash(event.request) if event.request
+      hash["operation"] = operation_to_hash(event.operation) if event.operation
+      hash["environment"] = environment_to_hash(event.environment) if event.environment
+      hash["user"] = user_to_hash(event.user) if event.user
+      hash["userFeedback"] = event.user_feedback if event.user_feedback
+
+      hash
+    end
+
+    def error_to_hash(err)
+      return {} unless err
+
+      h = { "message" => err.message, "type" => err.type }
+      h["stack"] = err.stack if err.stack
+      h["resolvedStack"] = err.resolved_stack if err.resolved_stack
+      h["componentStack"] = err.component_stack if err.component_stack
+      h
+    end
+
+    def breadcrumb_to_hash(b)
+      return {} unless b
+
+      h = {
+        "type" => b.type,
+        "category" => b.category,
+        "message" => b.message,
+        "timestamp" => b.timestamp
+      }
+      h["data"] = b.data if b.data
+      h["level"] = b.level if b.level
+      h
+    end
+
+    def sdk_to_hash(sdk)
+      return {} unless sdk
+
+      { "name" => sdk.name, "version" => sdk.version }
+    end
+
+    def request_to_hash(req)
+      return nil unless req
+
+      h = {}
+      h["method"] = req.method if req.method
+      h["url"] = req.url if req.url
+      h["headers"] = req.headers if req.headers
+      h["body"] = req.body if req.body
+      h["query"] = req.query if req.query
+      h
+    end
+
+    def operation_to_hash(op)
+      return nil unless op
+
+      h = {}
+      h["provider"] = op.provider if op.provider
+      h["type"] = op.type if op.type
+      h["method"] = op.method if op.method
+      h["params"] = op.params if op.params
+      h["errorCode"] = op.error_code if op.error_code
+      h["errorDetails"] = op.error_details if op.error_details
+      h
+    end
+
+    def environment_to_hash(env)
+      return nil unless env
+
+      h = {}
+      h["framework"] = env.framework if env.framework
+      h["frameworkVersion"] = env.framework_version if env.framework_version
+      h["runtime"] = env.runtime if env.runtime
+      h["runtimeVersion"] = env.runtime_version if env.runtime_version
+      h["platform"] = env.platform if env.platform
+      h["os"] = env.os if env.os
+      h["browser"] = env.browser if env.browser
+      h["browserVersion"] = env.browser_version if env.browser_version
+      h["deviceType"] = env.device_type if env.device_type
+      h["locale"] = env.locale if env.locale
+      h["timezone"] = env.timezone if env.timezone
+      h["url"] = env.url if env.url
+      h["deploy"] = env.deploy if env.deploy
+      h
+    end
+
+    def user_to_hash(usr)
+      return nil unless usr
+
+      h = {}
+      h["id"] = usr.id if usr.id
+      h["email"] = usr.email if usr.email
+      h["username"] = usr.username if usr.username
+      h["sessionId"] = usr.session_id if usr.session_id
+      h
+    end
+
+    def debug_log(msg)
+      $stderr.puts("[uncaught] #{msg}") if @config&.debug
+    end
+  end
+
+  # Console transport for development/debugging.
+  class ConsoleTransport
+    def initialize(config)
+      @config = config
+    end
+
+    def send_event(event)
+      title = "[uncaught] #{event.error.type}: #{event.error.message}"
+      $stderr.puts("--- #{title} ---")
+      $stderr.puts("Error: #{event.error.message}")
+      $stderr.puts("Stack: #{event.error.stack}") if event.error.stack
+      $stderr.puts("Event ID: #{event.event_id}")
+      $stderr.puts("Fingerprint: #{event.fingerprint}")
+      $stderr.puts("Breadcrumbs: #{event.breadcrumbs.inspect}")
+      $stderr.puts("Fix Prompt:\n#{event.fix_prompt}") if event.fix_prompt && !event.fix_prompt.empty?
+      $stderr.puts("---")
+    rescue
+      # Never throw from transport.
+    end
+
+    def flush
+      # Nothing to flush for console transport.
+    end
+  end
+
+  # Factory method to create the appropriate transport.
+  #
+  # @param config [Configuration]
+  # @return [LocalFileTransport, ConsoleTransport]
+  def self.create_transport(config)
+    mode = config.transport || "local"
+    case mode
+    when "console"
+      ConsoleTransport.new(config)
+    else
+      LocalFileTransport.new(config)
+    end
+  end
+end