bugsage 0.2.0

data/docs/images/README.md

@@ -0,0 +1,38 @@
+# Image assets
+
+## Logo & social
+
+| File | Shows |
+|------|--------|
+| `BugSage_Logo.png` | Project logo / wordmark banner (magnifying-glass bug + BugSage) |
+| `BugSage_Social_Preview.png` | GitHub / social Open Graph image — logo, tagline, feature grid, dashboard preview |
+
+### Set the GitHub Social Preview
+
+GitHub does not auto-detect this file. After committing:
+
+1. Open [Repository Settings → General → Social preview](https://github.com/MONARCHKOLI/bugsage/settings)
+2. Upload `docs/images/BugSage_Social_Preview.png`
+3. Save
+
+GitHub recommends about **1280×640** px (minimum ~640×320). This asset also works when sharing the repo on X, LinkedIn, and Slack.
+
+## Screenshots
+
+PNG captures used by the root [README.md](../README.md) **Screenshots** section. Most were taken from [`examples/sample_app`](../examples/sample_app).
+
+| File | Shows |
+|------|--------|
+| `NoMethodError2.png` | Exception page for `GET /boom` |
+| `NoMethodError.png` | Dashboard detail + AI Suggestions for `NoMethodError` |
+| `BadRequest.png` | Dashboard detail for captured `HTTP 400 Response` |
+| `BadRequest2.png` | Raw JSON body still returned by `GET /bad_request` |
+
+## Still useful to add
+
+| File | Suggested capture |
+|------|-------------------|
+| `cli-usage.png` | Terminal output for `bugsage version` / `bugsage install` |
+| `ai-suggestions-chat.png` | Optional: Quick Fix result + follow-up chat with code patch |
+
+Tips: crop to the relevant UI, avoid secrets, keep width readable on GitHub (~1200–1600px).

data/docs/releases/README.md

@@ -0,0 +1,21 @@
+# BugSage release notes
+
+Human-readable GitHub Release bodies live here. Create one file per version:
+
+```text
+docs/releases/vX.Y.Z.md
+```
+
+Publish with:
+
+```bash
+gh release create vX.Y.Z \
+  --title "BugSage vX.Y.Z" \
+  --notes-file docs/releases/vX.Y.Z.md
+```
+
+See [RELEASE_CHECKLIST.md](../RELEASE_CHECKLIST.md) § GitHub Release.
+
+## Releases
+
+- [v0.2.0](v0.2.0.md)

data/docs/releases/v0.2.0.md

@@ -0,0 +1,40 @@
+# BugSage v0.2.0
+
+**Release date:** 2026-07-13
+
+## What's New
+
+- AI-powered Rails exception analysis (OpenAI / Cursor on demand, Quick Fix + chat, surgical code patches)
+- Dashboard improvements (`/bugsage` session UI, fix actions, clear session)
+- Better configuration (`config.bugsage`, env-based enablement, safer environment defaults)
+- Zero-config Rails install (`AutoConfigurator`, `bugsage install`, optional generator)
+- Inline Rails console on the error page and dashboard
+- Improved documentation (README, Getting Started, Configuration, AI, Troubleshooting, screenshots)
+- GitHub Actions CI (RSpec, RuboCop, bundler-audit, gem build)
+- Security policy (`SECURITY.md`)
+- Architecture documentation (`ARCHITECTURE.md`) and roadmap (`ROADMAP.md`)
+
+## Install
+
+```ruby
+# Gemfile
+gem "bugsage", "~> 0.2.0"
+```
+
+```bash
+bundle install
+bin/rails server
+# Trigger an error in development, then open http://localhost:3000/bugsage
+```
+
+Optional AI keys:
+
+```bash
+export OPENAI_API_KEY=sk-...
+# or
+export CURSOR_API_KEY=crsr_...
+```
+
+## Full changelog
+
+See [CHANGELOG.md — 0.2.0](../../CHANGELOG.md#020---2026-07-13).

data/exe/bugsage

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/bugsage"
+require_relative "../lib/bugsage/cli"
+
+Bugsage::CLI.start(ARGV)

data/lib/bugsage/ai_analyzer.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bugsage
+  class AiAnalyzer
+    SYSTEM_PROMPT = <<~PROMPT
+      You are BugSage, a Ruby on Rails debugging assistant.
+      Refine the provided rule-based analysis using the exception details and request context.
+      Respond with JSON only using this schema:
+      {
+        "root_cause": "string",
+        "fixes": ["string", "string"],
+        "confidence": 0,
+        "notes": "string",
+        "code_patch": {
+          "action": "replace_lines | delete_lines | insert_before | no_change",
+          "start_line": 0,
+          "end_line": 0,
+          "replacement": "string"
+        }
+      }
+      Keep fixes concrete and actionable. Confidence must be an integer from 0 to 100.
+
+      You receive numbered source code from the real file. Rules for code_patch:
+      - Read the FULL source context before suggesting changes.
+      - Use absolute line numbers from the numbered source (the line marked with >>).
+      - NEVER duplicate code that already exists in the file.
+      - Change ONLY the lines required to fix the error.
+      - To remove a line (e.g. stray raise, debug code), use delete_lines with empty replacement.
+      - To replace lines, use replace_lines with start_line/end_line covering only affected lines.
+      - If the file already contains the correct fix, use no_change.
+      - Do not repeat existing assignments, finds, or renders.
+      - replacement must be only the new Ruby code for the affected lines, without markdown fences.
+    PROMPT
+
+    def self.enhance(suggestion, exception, context = {}, config: Bugsage.configuration, client: nil)
+      new(config: config, client: client).enhance(suggestion, exception, context)
+    end
+
+    def initialize(config: Bugsage.configuration, client: nil)
+      @config = config
+      @client = client
+    end
+
+    # Returns [suggestion, ai_error_message]
+    def enhance(suggestion, exception, context)
+      return [suggestion, nil] unless @config.ai_configured?
+
+      response = client.complete(
+        system_prompt: SYSTEM_PROMPT,
+        user_prompt: build_prompt(suggestion, exception, context)
+      )
+      [merge_suggestion(suggestion, parse_response(response, suggestion: suggestion)), nil]
+    rescue StandardError => e
+      log_failure(e)
+      [suggestion, e.message]
+    end
+
+    private
+
+    def client
+      @client ||= @config.ai_client || build_client
+    end
+
+    def build_client
+      AiSupport.build_client(@config)
+    end
+
+    def build_prompt(suggestion, exception, context)
+      backtrace = TraceCleaner.clean(exception.backtrace).first(8).join("\n")
+      request_context = context.empty? ? "none" : JSON.pretty_generate(context)
+      file_path, line_number = CodeContext.extract_location(suggestion.location)
+      source_context = CodeContext.numbered_source(file_path, line_number) if file_path && line_number
+      source_block = source_context ? source_context[:source] : "unavailable"
+
+      <<~PROMPT
+        Exception class: #{exception.class.name}
+        Exception message: #{exception.message}
+        Location: #{suggestion.location}
+        Error line: #{line_number}
+        Backtrace:
+        #{backtrace}
+
+        Request context:
+        #{request_context}
+
+        Numbered source code:
+        #{source_block}
+
+        Rule-based analysis:
+        Issue: #{suggestion.issue}
+        Root cause: #{suggestion.root_cause}
+        Fixes: #{suggestion.fixes.join("; ")}
+        Confidence: #{suggestion.confidence}
+      PROMPT
+    end
+
+    def parse_response(response, suggestion:)
+      payload = JSON.parse(extract_json(response))
+      _file_path, line_number = CodeContext.extract_location(suggestion.location)
+      patch = CodePatch.from_ai(payload, error_line: line_number || 1)
+
+      {
+        root_cause: payload["root_cause"].to_s.strip,
+        fixes: Array(payload["fixes"]).map { |fix| fix.to_s.strip }.reject(&:empty?),
+        confidence: normalize_confidence(payload["confidence"]),
+        notes: payload["notes"].to_s.strip,
+        code_patch: patch&.to_h
+      }
+    end
+
+    def merge_suggestion(suggestion, ai_result)
+      return suggestion if ai_result[:fixes].empty? && ai_result[:root_cause].empty? && ai_result[:code_patch].nil?
+
+      suggestion.with_ai_enhancement(
+        root_cause: ai_result[:root_cause].empty? ? suggestion.root_cause : ai_result[:root_cause],
+        fixes: merge_fixes(suggestion.fixes, ai_result[:fixes]),
+        confidence: ai_result[:confidence] || suggestion.confidence,
+        ai_notes: ai_result[:notes].empty? ? nil : ai_result[:notes],
+        code_patch: ai_result[:code_patch]
+      )
+    end
+
+    def merge_fixes(rule_fixes, ai_fixes)
+      combined = ai_fixes + rule_fixes
+      combined.uniq(&:downcase)
+    end
+
+    def normalize_confidence(value)
+      number = Integer(value)
+      number.clamp(0, 100)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def extract_json(response)
+      AiSupport.extract_json(response)
+    end
+
+    def log_failure(error)
+      AiSupport.log_failure("AI enhancement failed", error)
+    end
+  end
+end

data/lib/bugsage/ai_chat.rb

@@ -0,0 +1,388 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bugsage
+  class AiChat
+    extend JsonEndpoint
+
+    ENDPOINT = "/bugsage/ai-chat"
+
+    SYSTEM_PROMPT = <<~PROMPT
+      You are BugSage, a Ruby on Rails debugging assistant chatting with a developer
+      about a specific caught exception.
+
+      Respond with JSON only using this schema:
+      {
+        "reply": "conversational answer shown in chat",
+        "code_patch": null | {
+          "action": "replace_lines | delete_lines | insert_before | no_change",
+          "start_line": 0,
+          "end_line": 0,
+          "replacement": "string"
+        }
+      }
+
+      Rules:
+      - reply must explain your answer clearly and concisely.
+      - Include code_patch ONLY when the developer asks for a code change, asks to
+        revise the current suggested fix, or agrees to an alternative approach
+        (for example commenting out a line instead of deleting it).
+      - When they want to comment out a line, use replace_lines with the commented
+        Ruby code in replacement (e.g. "# raise "debug""), not delete_lines.
+      - Use absolute line numbers from the numbered source (the line marked with >>).
+      - NEVER duplicate code that already exists in the file.
+      - Change ONLY the lines required for the requested fix.
+      - Set code_patch to null when answering questions without changing the fix.
+      - replacement must be only the new Ruby code for affected lines, without markdown fences.
+    PROMPT
+
+    def self.handle_request(env)
+      return not_found unless Bugsage.configuration.ai_configured?
+
+      payload = parse_request_body(env)
+      context = AiPanel.load_context(payload)
+      return json_response(error_response(Bugsage.t("errors.ai_context_not_available"))) unless context
+
+      message = payload["message"].to_s.strip
+      return json_response(error_response(Bugsage.t("errors.enter_message"))) if message.empty?
+
+      history = normalize_history(payload["history"])
+      result = chat(context, message, history)
+
+      updated_history = history + [
+        { "role" => "user", "content" => message },
+        { "role" => "assistant", "content" => result[:reply] }
+      ]
+
+      persist_chat_patch!(context, result[:code_patch], payload["index"]) if result[:code_patch]
+
+      json_response(
+        ok: true,
+        reply: result[:reply],
+        history: updated_history,
+        code_patch: result[:code_patch],
+        code_fix: result[:code_fix]
+      )
+    rescue StandardError => e
+      log_failure(e)
+      json_response(error_response(e.message))
+    end
+
+    def self.chat(context, message, history)
+      client = build_client
+      user_prompt = build_chat_prompt(context, message, history)
+      response = client.complete(system_prompt: SYSTEM_PROMPT, user_prompt: user_prompt)
+      parse_chat_response(response, context[:suggestion])
+    end
+
+    def self.build_chat_prompt(context, message, history)
+      context_block = build_context_block(context)
+      conversation = history.map do |entry|
+        "#{entry["role"].capitalize}: #{entry["content"]}"
+      end.join("\n\n")
+
+      parts = [context_block]
+      parts << "Conversation so far:\n#{conversation}" unless conversation.empty?
+      parts << "Developer: #{message}"
+      parts.join("\n\n")
+    end
+
+    def self.parse_chat_response(response, suggestion)
+      payload = JSON.parse(extract_json(response))
+      _file_path, line_number = CodeContext.extract_location(suggestion.location)
+      code_patch = parse_code_patch(payload, line_number)
+
+      reply = payload["reply"].to_s.strip
+      reply = payload["notes"].to_s.strip if reply.empty?
+
+      {
+        reply: reply.empty? ? Bugsage.t("errors.default_chat_reply") : reply,
+        code_patch: code_patch,
+        code_fix: CodePatch.preview_for(code_patch)
+      }
+    end
+
+    def self.parse_code_patch(payload, line_number)
+      patch_data = payload["code_patch"]
+      return nil if patch_data.nil? || (patch_data.respond_to?(:empty?) && patch_data.empty?)
+
+      patch = CodePatch.from_ai(payload, error_line: line_number || 1)
+      patch&.to_h
+    end
+
+    def self.persist_chat_patch!(context, code_patch, index)
+      return unless code_patch.is_a?(Hash) && !code_patch.empty?
+
+      suggestion = context[:suggestion]
+      updated = suggestion.with_ai_enhancement(
+        root_cause: suggestion.root_cause,
+        fixes: suggestion.fixes,
+        confidence: suggestion.confidence,
+        ai_notes: suggestion.ai_notes,
+        code_patch: code_patch
+      )
+
+      if index
+        Store.update_at(index.to_i, updated)
+      elsif Store.all.any?
+        Store.update_at(0, updated)
+      end
+    end
+
+    def self.build_context_block(context, source_context = nil)
+      suggestion = context[:suggestion]
+      exception = context[:exception]
+      file_path, line_number = CodeContext.extract_location(suggestion.location)
+      source_context ||= CodeContext.numbered_source(file_path, line_number) if file_path && line_number
+      source_block = source_context ? source_context[:source] : "unavailable"
+      patch_json = suggestion.code_patch ? JSON.generate(suggestion.code_patch) : "none"
+
+      <<~PROMPT
+        Exception: #{exception.class.name}
+        Message: #{exception.message}
+        Location: #{suggestion.location}
+        Root cause: #{suggestion.root_cause}
+        Suggested fixes: #{suggestion.fixes.join("; ")}
+        AI notes: #{suggestion.ai_notes}
+        Current code_patch JSON: #{patch_json}
+        Current patch preview: #{suggestion.code_fix || "none yet"}
+
+        Numbered source:
+        #{source_block}
+      PROMPT
+    end
+
+    def self.extract_json(response)
+      AiSupport.extract_json(response)
+    end
+
+    def self.build_client
+      AiSupport.build_client(Bugsage.configuration)
+    end
+
+    def self.normalize_history(history)
+      Array(history).filter_map do |entry|
+        role = entry["role"].to_s
+        content = entry["content"].to_s.strip
+        next if content.empty?
+        next unless %w[user assistant].include?(role)
+
+        { "role" => role, "content" => content }
+      end
+    end
+
+    def self.render_widget(suffix:, bug_index: nil)
+      index_attr = bug_index.nil? ? "" : %( data-bug-index="#{bug_index}")
+
+      <<~HTML
+        <div class="ai-loading-overlay hidden" id="bugsage-ai-loading#{suffix}" aria-hidden="true">
+          <div class="ai-loading-card">
+            <div class="ai-spinner" aria-hidden="true"></div>
+            <p class="ai-loading-title">#{CodeContext.escape_html(Bugsage.t("ui.ai_chat.working_title"))}</p>
+            <p class="ai-loading-step" id="bugsage-ai-loading-step#{suffix}">#{CodeContext.escape_html(Bugsage.t("ui.ai_chat.reading_source"))}</p>
+            <div class="ai-loading-bar"><span class="ai-loading-bar-fill"></span></div>
+          </div>
+        </div>
+
+        <div class="ai-chat-panel hidden" id="bugsage-ai-chat#{suffix}"#{index_attr}>
+          <div class="ai-chat-header">
+            <span>#{CodeContext.escape_html(Bugsage.t("ui.ai_chat.chat_header"))}</span>
+            <button type="button" class="ai-chat-close" aria-label="#{CodeContext.escape_html(Bugsage.t("ui.ai_chat.close_chat_aria"))}">&times;</button>
+          </div>
+          <div class="ai-chat-messages" id="bugsage-ai-chat-messages#{suffix}" aria-live="polite"></div>
+          <form class="ai-chat-form bugsage-ai-chat-form" data-output-target="#bugsage-ai-chat-messages#{suffix}">
+            <input
+              class="ai-chat-input"
+              type="text"
+              name="message"
+              autocomplete="off"
+              placeholder="#{CodeContext.escape_html(Bugsage.t("ui.ai_chat.input_placeholder"))}"
+            />
+            <button type="submit" class="ai-chat-send">#{CodeContext.escape_html(Bugsage.t("ui.ai_chat.send"))}</button>
+          </form>
+        </div>
+      HTML
+    end
+
+    def self.styles
+      <<~CSS
+        .ai-panel.is-loading {
+          overflow: hidden;
+        }
+        .ai-panel-header-actions {
+          display: inline-flex;
+          align-items: center;
+          gap: 8px;
+        }
+        .ai-chat-toggle {
+          background: rgba(137, 180, 250, 0.15);
+          color: #89b4fa;
+          border: 1px solid rgba(137, 180, 250, 0.35);
+          border-radius: 999px;
+          width: 36px;
+          height: 36px;
+          font-size: 16px;
+          cursor: pointer;
+        }
+        .ai-chat-toggle:hover {
+          background: rgba(137, 180, 250, 0.25);
+        }
+        .ai-loading-overlay {
+          position: absolute;
+          inset: 0;
+          background: rgba(30, 30, 46, 0.82);
+          border-radius: 8px;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          z-index: 2;
+        }
+        .ai-loading-overlay.hidden {
+          display: none;
+        }
+        .ai-loading-card {
+          text-align: center;
+          padding: 20px;
+          width: min(100%, 280px);
+        }
+        .ai-spinner {
+          width: 42px;
+          height: 42px;
+          border: 3px solid rgba(137, 180, 250, 0.2);
+          border-top-color: #89b4fa;
+          border-radius: 50%;
+          margin: 0 auto 14px;
+          animation: bugsage-spin 0.9s linear infinite;
+        }
+        .ai-loading-title {
+          color: #cdd6f4;
+          font-size: 14px;
+          font-weight: bold;
+          margin: 0 0 6px 0;
+        }
+        .ai-loading-step {
+          color: #f9e2af;
+          font-size: 12px;
+          margin: 0 0 12px 0;
+          min-height: 16px;
+        }
+        .ai-loading-bar {
+          height: 4px;
+          background: rgba(137, 180, 250, 0.15);
+          border-radius: 999px;
+          overflow: hidden;
+        }
+        .ai-loading-bar-fill {
+          display: block;
+          height: 100%;
+          width: 35%;
+          background: linear-gradient(90deg, #89b4fa, #a6e3a1);
+          border-radius: 999px;
+          animation: bugsage-progress 1.4s ease-in-out infinite;
+        }
+        @keyframes bugsage-spin {
+          to { transform: rotate(360deg); }
+        }
+        @keyframes bugsage-progress {
+          0% { transform: translateX(-120%); }
+          100% { transform: translateX(320%); }
+        }
+        .ai-chat-panel {
+          margin-top: 14px;
+          background: #1e1e2e;
+          border: 1px solid #45475a;
+          border-radius: 8px;
+          overflow: hidden;
+        }
+        .ai-chat-panel.hidden {
+          display: none;
+        }
+        .ai-chat-header {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          padding: 10px 12px;
+          background: #313244;
+          color: #cdd6f4;
+          font-size: 13px;
+          font-weight: bold;
+        }
+        .ai-chat-close {
+          background: transparent;
+          border: 0;
+          color: #a6adc8;
+          font-size: 20px;
+          cursor: pointer;
+          line-height: 1;
+        }
+        .ai-chat-messages {
+          max-height: 220px;
+          overflow-y: auto;
+          padding: 12px;
+          display: flex;
+          flex-direction: column;
+          gap: 10px;
+        }
+        .ai-chat-bubble {
+          max-width: 92%;
+          padding: 10px 12px;
+          border-radius: 10px;
+          font-size: 13px;
+          line-height: 1.45;
+          white-space: pre-wrap;
+        }
+        .ai-chat-bubble.user {
+          align-self: flex-end;
+          background: rgba(137, 180, 250, 0.18);
+          color: #cdd6f4;
+        }
+        .ai-chat-bubble.assistant {
+          align-self: flex-start;
+          background: rgba(166, 227, 161, 0.12);
+          color: #cdd6f4;
+        }
+        .ai-chat-bubble.loading {
+          align-self: flex-start;
+          color: #f9e2af;
+          font-style: italic;
+        }
+        .ai-chat-form {
+          display: flex;
+          gap: 8px;
+          padding: 12px;
+          border-top: 1px solid #45475a;
+        }
+        .ai-chat-input {
+          flex: 1;
+          background: #313244;
+          color: #cdd6f4;
+          border: 1px solid #45475a;
+          border-radius: 6px;
+          padding: 10px 12px;
+          font-family: inherit;
+          font-size: 13px;
+        }
+        .ai-chat-send {
+          background: #89b4fa;
+          color: #1e1e2e;
+          border: 0;
+          border-radius: 6px;
+          padding: 10px 14px;
+          font-family: inherit;
+          font-size: 13px;
+          font-weight: bold;
+          cursor: pointer;
+        }
+        .ai-chat-send:disabled {
+          opacity: 0.5;
+          cursor: not-allowed;
+        }
+      CSS
+    end
+
+    def self.log_failure(error)
+      AiSupport.log_failure("AI chat failed", error)
+    end
+  end
+end