bugsage 0.2.0

data/docs/GettingStarted.md

@@ -0,0 +1,146 @@
+# Getting Started
+
+This guide walks you through installing BugSage in a Rails app and verifying that exception capture, the error page, and the session dashboard work.
+
+For configuration details, see [Configuration.md](Configuration.md). For AI setup, see [AI.md](AI.md). If something does not work, see [Troubleshooting.md](Troubleshooting.md).
+
+## Requirements
+
+- Ruby `>= 3.2`
+- A Rails application
+
+## Install the gem
+
+### From RubyGems
+
+```ruby
+# Gemfile
+gem "bugsage"
+```
+
+### From GitHub
+
+```ruby
+# Gemfile
+gem "bugsage", github: "MONARCHKOLI/bugsage", branch: "master"
+```
+
+### From a local path (gem development)
+
+```ruby
+# Gemfile
+gem "bugsage", path: "../bugsage"
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+## Start Rails
+
+```bash
+bin/rails server
+```
+
+BugSage wires itself through `Bugsage::Railtie`. You do **not** need to:
+
+- edit `config/routes.rb`
+- insert middleware manually
+- change `config/application.rb` for basic use
+
+## Verify exception capture
+
+1. Trigger an exception in development (for example, call a method on `nil` in a controller action).
+2. Confirm you see the **BugSage error page** instead of the default Rails debugger page.
+3. Confirm the page shows:
+   - exception class and message
+   - highlighted source near the failure
+   - suggested fixes and a confidence score
+   - Rails request context
+
+## Open the session dashboard
+
+Visit:
+
+```text
+http://localhost:3000/bugsage
+```
+
+You should see the error you just triggered listed in the session store.
+
+The dashboard is enabled by default in **development** only.
+
+## Optional: generate an initializer
+
+Only needed when you want documented overrides in your app:
+
+```bash
+bundle exec rails generate bugsage:install
+```
+
+Or:
+
+```bash
+bundle exec bugsage install
+```
+
+Guide only (no files written):
+
+```bash
+bundle exec bugsage install --guide-only
+```
+
+## Optional: enable AI
+
+Export a key in the **same terminal** that starts Rails:
+
+```bash
+export OPENAI_API_KEY=sk-your-openai-key-here
+# or
+export CURSOR_API_KEY=crsr_your-cursor-key-here
+
+bin/rails server
+```
+
+Then on the error page or dashboard:
+
+1. Toggle **Enable AI** if needed.
+2. Click **Quick Fix Suggestion**.
+3. Optionally use **Chat** to refine the fix.
+4. Use **Apply AI to Codebase** on the dashboard when you are ready.
+
+Full details: [AI.md](AI.md).
+
+## Optional: HTTP API error capture
+
+BugSage can record HTTP status ≥ 400 responses (for example `render json: ..., status: :bad_request`) in the dashboard **without** changing the response body returned to Postman or other clients.
+
+After calling a failing API endpoint, open `/bugsage` to see the captured HTTP error entry.
+
+To disable:
+
+```ruby
+config.bugsage.capture_http_errors = false
+```
+
+## What gets auto-wired
+
+On boot, BugSage typically enables:
+
+| Capability | Default (development) |
+|------------|------------------------|
+| Exception capture middleware | On |
+| HTML error page | On |
+| Session dashboard (`/bugsage`) | On |
+| Inline Rails console | On |
+| HTTP error capture | On (when error capture is on) |
+| Routing error capture (`exceptions_app`) | On |
+| AI panel | On when an API key is present |
+
+## Next steps
+
+- Tune options in [Configuration.md](Configuration.md)
+- Set up providers and patches in [AI.md](AI.md)
+- Diagnose common issues in [Troubleshooting.md](Troubleshooting.md)

data/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,346 @@
+# Release Checklist
+
+Checklist for publishing a new **BugSage** version to RubyGems and GitHub. Follow every step unless a release manager explicitly skips an item with a written reason.
+
+Replace `X.Y.Z` with the version you are releasing (example: `0.3.0`).
+
+---
+
+## 0. Preconditions
+
+- [ ] You have maintainer access to [github.com/MONARCHKOLI/bugsage](https://github.com/MONARCHKOLI/bugsage)
+- [ ] You have a RubyGems.org account with push rights for `bugsage`
+- [ ] MFA is enabled on RubyGems (gemspec sets `rubygems_mfa_required`)
+- [ ] Working tree is clean on an up-to-date `master` (or a release branch based on it)
+- [ ] CI is green on the commit you intend to release (`.github/workflows/ci.yml`)
+- [ ] No open blockers for this version (security issues, broken install path)
+
+```bash
+git checkout master
+git pull origin master
+git status
+```
+
+---
+
+## 1. Tests
+
+- [ ] Run the full default suite locally:
+
+```bash
+bundle install
+bundle exec rake          # RSpec + RuboCop
+# or separately:
+bundle exec rspec
+```
+
+- [ ] Confirm CI matrix passed for Ruby **3.2**, **3.3**, and **3.4**
+- [ ] Confirm **bundle-audit** job passed (no known vulnerable deps)
+- [ ] If you touched HTTP capture, AI, or middleware: run focused examples and a manual smoke test
+
+Failure here stops the release.
+
+---
+
+## 2. RuboCop
+
+- [ ] Lint is clean with project config:
+
+```bash
+bundle exec rubocop --config .rubocop.yml --force-exclusion
+```
+
+- [ ] Do **not** disable cops or widen excludes solely to ship a release
+- [ ] CI **RuboCop** job is green
+
+---
+
+## 3. README review
+
+- [ ] Installation instructions still work (Gemfile, Git, path)
+- [ ] Version badge / featured version references match `X.Y.Z` if hardcoded
+- [ ] Configuration table matches `Bugsage::Configuration` defaults
+- [ ] New user-facing behavior is documented (or linked under `docs/`)
+- [ ] Links to CONTRIBUTING, SECURITY, ARCHITECTURE, ROADMAP, and docs are valid
+- [ ] No secrets, private tokens, or broken example commands
+
+Also skim:
+
+- [ ] `docs/GettingStarted.md`
+- [ ] `docs/Configuration.md` / `docs/AI.md` / `docs/Troubleshooting.md` (if the release touches those areas)
+- [ ] `ARCHITECTURE.md` / `ROADMAP.md` status tables if milestones moved
+
+---
+
+## 4. Version bump
+
+Single source of truth:
+
+```ruby
+# lib/bugsage/version.rb
+module Bugsage
+  VERSION = "X.Y.Z"
+end
+```
+
+- [ ] Bump `Bugsage::VERSION` in `lib/bugsage/version.rb`
+- [ ] Confirm `bugsage.gemspec` reads `Bugsage::VERSION` (do not hardcode a second version)
+- [ ] Choose SemVer intentionally:
+  - **MAJOR** — breaking public API / default behavior
+  - **MINOR** — new features, backwards compatible
+  - **PATCH** — bug fixes / docs-only release packaging
+- [ ] Update gemspec metadata URIs if needed (especially `changelog_uri` branch name)
+
+```bash
+ruby -e 'require_relative "lib/bugsage/version"; puts Bugsage::VERSION'
+```
+
+---
+
+## 5. CHANGELOG
+
+Follow Keep a Changelog style in `CHANGELOG.md`:
+
+- [ ] Move items from `## [Unreleased]` into `## [X.Y.Z] - YYYY-MM-DD`
+- [ ] Group under `Added` / `Changed` / `Fixed` / `Deprecated` / `Removed` / `Security` as needed
+- [ ] Leave an empty `## [Unreleased]` section at the top for the next cycle
+- [ ] Write user-facing notes (why it matters), not only file lists
+- [ ] Call out **breaking changes** explicitly
+
+Example shape:
+
+```markdown
+## [Unreleased]
+
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- ...
+
+### Fixed
+- ...
+```
+
+---
+
+## 6. Build gem
+
+- [ ] Build from a clean tree matching what will be tagged:
+
+```bash
+rm -rf pkg/
+bundle exec rake build
+ls -la pkg/bugsage-X.Y.Z.gem
+```
+
+- [ ] Validate gemspec / package (same checks CI runs):
+
+```bash
+ruby -e 'spec = Gem::Specification.load("bugsage.gemspec"); spec.validate; puts spec.full_name'
+gem unpack pkg/bugsage-X.Y.Z.gem --target /tmp/bugsage-unpack
+test -f /tmp/bugsage-unpack/bugsage-X.Y.Z/lib/bugsage.rb
+test -f /tmp/bugsage-unpack/bugsage-X.Y.Z/exe/bugsage
+```
+
+- [ ] Confirm packaged files include locales, generators, and LICENSE; exclude `spec/`, `.github/`, etc.
+
+---
+
+## 7. Install locally
+
+- [ ] Install the built `.gem` into a clean gem home or local path:
+
+```bash
+gem install pkg/bugsage-X.Y.Z.gem
+bugsage version
+# expect: BugSage vX.Y.Z
+```
+
+Or without polluting the default gemset:
+
+```bash
+gem install pkg/bugsage-X.Y.Z.gem --install-dir /tmp/bugsage-gemhome
+GEM_HOME=/tmp/bugsage-gemhome GEM_PATH=/tmp/bugsage-gemhome \
+  /tmp/bugsage-gemhome/bin/bugsage version
+```
+
+- [ ] `require "bugsage"` loads without Rails
+- [ ] Uninstall the local test install when finished (optional cleanup)
+
+---
+
+## 8. Test on a fresh Rails application
+
+Do **not** rely only on the development dummy app path.
+
+- [ ] Generate a new Rails app (versions you claim to support):
+
+```bash
+rails new /tmp/bugsage_release_app --skip-javascript
+cd /tmp/bugsage_release_app
+```
+
+- [ ] Add the **built gem** (not the git worktree) via path to the `.gem` contents or:
+
+```ruby
+# Gemfile
+gem "bugsage", path: "/tmp/bugsage-unpack/bugsage-X.Y.Z"
+# after: gem unpack pkg/bugsage-X.Y.Z.gem --target /tmp/bugsage-unpack
+```
+
+Prefer testing the unpacked package so you catch packaging mistakes.
+
+- [ ] `bundle install` and `bin/rails server`
+- [ ] Trigger an exception → BugSage error page appears in development
+- [ ] Visit `http://localhost:3000/bugsage` → dashboard loads
+- [ ] If this release touches them, verify:
+  - [ ] HTTP 4xx capture (API `status: :bad_request`) without breaking the JSON body
+  - [ ] AI panel appears only with a key; Quick Fix does not run automatically
+  - [ ] `bundle exec rails generate bugsage:install` / `bundle exec bugsage install --guide-only`
+
+Stop the release if zero-config install fails.
+
+---
+
+## 9. Commit, tag, and push
+
+- [ ] Commit release metadata only (version, changelog, docs bumps):
+
+```bash
+git add lib/bugsage/version.rb CHANGELOG.md README.md docs/
+git commit -m "$(cat <<'EOF'
+Release vX.Y.Z
+
+EOF
+)"
+```
+
+- [ ] Create an annotated tag:
+
+```bash
+git tag -a vX.Y.Z -m "BugSage vX.Y.Z"
+```
+
+- [ ] Push commit and tag:
+
+```bash
+git push origin master
+git push origin vX.Y.Z
+```
+
+- [ ] Confirm CI is green on the tagged commit / `master`
+
+---
+
+## 10. GitHub Release
+
+Do **not** publish a bare tag with an empty body. Write human-readable release notes
+(see `docs/releases/` — e.g. [`v0.2.0.md`](releases/v0.2.0.md)).
+
+- [ ] Draft notes under `docs/releases/vX.Y.Z.md` with at least:
+
+```markdown
+## What's New
+
+- …
+```
+
+Include product highlights (features users feel), not only file-level changelog bullets.
+Link to `CHANGELOG.md` for the full detail list.
+
+- [ ] Open [Releases → Draft a new release](https://github.com/MONARCHKOLI/bugsage/releases/new)
+  or create from the CLI:
+
+```bash
+gh release create vX.Y.Z \
+  --title "BugSage vX.Y.Z" \
+  --notes-file docs/releases/vX.Y.Z.md
+```
+
+- [ ] Choose / confirm tag `vX.Y.Z`
+- [ ] Title: `BugSage vX.Y.Z` (not only the raw tag)
+- [ ] Body: paste or `--notes-file` the release notes (What's New + install + changelog link)
+- [ ] Attach `pkg/bugsage-X.Y.Z.gem` only if you build it for distribution (keep `*.gem` / `pkg/` out of Git)
+- [ ] Mark as pre-release only if intentionally unstable
+- [ ] Publish the GitHub Release
+- [ ] Confirm the release page renders: `https://github.com/MONARCHKOLI/bugsage/releases/tag/vX.Y.Z`
+
+---
+
+## 11. RubyGems publish
+
+Final gate — only after GitHub tag/release (or immediately after tag if you publish then announce).
+
+- [ ] Re-confirm you are publishing the exact built gem for `X.Y.Z`:
+
+```bash
+gem env home
+gem build bugsage.gemspec   # or use existing pkg/bugsage-X.Y.Z.gem
+gem push pkg/bugsage-X.Y.Z.gem
+```
+
+- [ ] Complete MFA / OTP when prompted
+- [ ] Verify the gem page: [https://rubygems.org/gems/bugsage](https://rubygems.org/gems/bugsage)
+- [ ] Verify install from RubyGems:
+
+```bash
+gem install bugsage -v X.Y.Z
+bugsage version
+```
+
+- [ ] `allowed_push_host` must remain `https://rubygems.org`
+
+**Never** `--force` yank unless following a security process. Prefer a new patch release for fixes.
+
+---
+
+## 12. Post-release
+
+- [ ] Smoke-install from RubyGems in another fresh Rails app (`gem "bugsage", "X.Y.Z"`)
+- [ ] Update any hardcoded version badges (README) if still pointing at the old version
+- [ ] Confirm GitHub **Social preview** uses `docs/images/BugSage_Social_Preview.png` (Settings → General → Social preview)
+- [ ] Close/milestone related GitHub issues and PRs
+- [ ] Announce briefly if you have a channel ( Discussions / social ) — optional
+- [ ] Confirm `## [Unreleased]` is ready for the next cycle
+- [ ] Rest before starting the next major feature branch ☕
+
+---
+
+## Quick command strip (healthy release)
+
+```bash
+bundle exec rake
+bundle exec bundle-audit check --update
+# bump lib/bugsage/version.rb + CHANGELOG.md + docs/releases/vX.Y.Z.md
+bundle exec rake build
+gem install pkg/bugsage-X.Y.Z.gem
+# unpack + install into a fresh rails app and smoke-test
+git tag -a vX.Y.Z -m "BugSage vX.Y.Z"
+git push origin master --follow-tags
+gh release create vX.Y.Z --title "BugSage vX.Y.Z" --notes-file docs/releases/vX.Y.Z.md
+gem push pkg/bugsage-X.Y.Z.gem
+```
+
+---
+
+## Abort criteria
+
+Do **not** publish if any of the following are true:
+
+- Specs or RuboCop fail
+- Bundle audit reports a relevant unpatched vulnerability in a runtime dependency
+- Fresh Rails app does not see the error page / dashboard with zero-config
+- Version / changelog / tag disagree
+- You cannot complete RubyGems MFA
+
+---
+
+## Related docs
+
+- [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [CHANGELOG.md](../CHANGELOG.md)
+- [Release notes — v0.2.0](releases/v0.2.0.md)
+- [SECURITY.md](../SECURITY.md)
+- [ARCHITECTURE.md](../ARCHITECTURE.md)
+- [ROADMAP.md](../ROADMAP.md)
+- RubyGems: [Make your own gem](https://guides.rubygems.org/make-your-own-gem/) · [Publishing](https://guides.rubygems.org/publishing/)

data/docs/Troubleshooting.md

@@ -0,0 +1,181 @@
+# Troubleshooting
+
+Common issues when installing or using BugSage, and how to resolve them.
+
+Related docs: [GettingStarted.md](GettingStarted.md) · [Configuration.md](Configuration.md) · [AI.md](AI.md)
+
+## Installation and loading
+
+### BugSage does nothing after `bundle install`
+
+**Checks:**
+
+1. Confirm the gem is in the bundle:
+
+   ```bash
+   bundle show bugsage
+   ```
+
+2. Confirm you restarted `bin/rails server` after adding the gem.
+3. Confirm the environment is enabled (default: `development`, `test` only).
+
+```bash
+echo $RAILS_ENV
+echo $BUGSAGE_ENABLED_ENVIRONMENTS
+```
+
+If you are in `staging` or `production`, add that environment explicitly:
+
+```bash
+export BUGSAGE_ENABLED_ENVIRONMENTS=development,test,staging
+```
+
+### Changes to the gem path are not picked up
+
+When using `gem "bugsage", path: "..."` or a GitHub branch:
+
+```bash
+bundle update bugsage
+bin/rails restart
+# or stop and start bin/rails server
+```
+
+Spring or another preloader can cache old code — stop Spring if needed: `bin/spring stop`.
+
+## Error page and dashboard
+
+### I still see the default Rails error page
+
+Possible causes:
+
+| Cause | Fix |
+|-------|-----|
+| Not in development | Use development, or set `show_error_page = true` for your env |
+| BugSage disabled for this env | Add the env to `enabled_environments` |
+| `show_error_page` forced off | Set `config.bugsage.show_error_page = true` |
+| Exception handled by the app | BugSage only sees unhandled exceptions (and configured HTTP errors) |
+
+### `/bugsage` returns 404 or an empty app page
+
+- Dashboard defaults to **development** only (`show_dashboard`).
+- Ensure middleware is loading (restart server after install).
+- Visit exactly `/bugsage` (trailing slash `/bugsage/` is also accepted).
+
+### Dashboard is empty after an API call from Postman
+
+1. Confirm `capture_errors` and `capture_http_errors` are enabled (both default to on when BugSage is enabled).
+2. Confirm the response status is **≥ 400**. Successful `200` responses are not captured as errors.
+3. Confirm you are looking at the **same Rails process** session (restarting the server clears the in-memory store).
+4. If you previously hit a BugSage middleware bug on body extraction, update to a build that iterates Rack bodies with `each` (not `map`).
+
+Disable HTTP capture intentionally:
+
+```ruby
+config.bugsage.capture_http_errors = false
+```
+
+### `NoMethodError` on `map` for `ActionDispatch::Response::RackBody`
+
+Older BugSage builds extracted response bodies with `body.map`. Rails API responses often implement `each` only.
+
+**Fix:** upgrade BugSage to a version that collects body parts with `each`, then `bundle update bugsage` and restart.
+
+## AI issues
+
+### AI panel does not appear
+
+1. Export a key in the **same terminal** that runs Rails:
+
+   ```bash
+   export OPENAI_API_KEY=sk-...
+   # or
+   export CURSOR_API_KEY=crsr_...
+   bin/rails server
+   ```
+
+2. Confirm `config.bugsage.ai_enabled` is not `false`.
+3. Confirm BugSage is enabled for the current environment.
+
+### Quick Fix fails or times out
+
+Look for:
+
+```text
+[BugSage] AI enhancement failed: ...
+```
+
+in the Rails log or server terminal.
+
+| Symptom | Likely cause | What to try |
+|---------|--------------|-------------|
+| Auth / 401 errors | Invalid or expired key | Rotate the key; confirm prefix (`sk-` vs `crsr_`) |
+| Timeouts with Cursor | Cloud Agent duration | Raise `ai_timeout` (Cursor uses at least 90s) |
+| Wrong provider | Mis-detected key | Set `config.bugsage.ai_provider = :openai` or `:cursor` |
+| Rate limits | Provider quota | Retry later or switch providers |
+
+```ruby
+config.bugsage.ai_timeout = 120
+config.bugsage.ai_provider = :cursor
+```
+
+### Chat reply does not change **Apply AI to Codebase**
+
+Chat must return a structured `code_patch` in the response. If the model only returns prose, the apply button keeps the previous Quick Fix patch.
+
+Ask explicitly, for example: “Update the code_patch to comment out line N instead of deleting it.”
+
+### Apply fix does nothing / is forbidden
+
+`/bugsage/apply-fix` is allowed in **development** and **test** only. It will not write files in production-like environments.
+
+## Inline console
+
+### Console is missing
+
+`show_inline_console` defaults to **development** only. Enable it explicitly if needed:
+
+```ruby
+config.bugsage.show_inline_console = true
+```
+
+Evaluate carefully — the console runs Ruby in the application process.
+
+## Configuration not applying
+
+1. Prefer `config/initializers/bugsage.rb` with:
+
+   ```ruby
+   Rails.application.configure do |config|
+     config.bugsage.ai_enabled = false
+   end
+   ```
+
+2. Restart the server after edits.
+3. Remember: `BUGSAGE_ENABLED_ENVIRONMENTS` can override enabled environments at boot via auto-configuration.
+
+## Logging and inspection
+
+When diagnosing capture or AI failures, check:
+
+- BugSage HTML error page
+- `http://localhost:3000/bugsage`
+- `log/development.log`
+- The terminal running `bin/rails server`
+- `[BugSage] AI enhancement failed: ...` warnings
+
+## Still stuck?
+
+1. Confirm Ruby `>= 3.2` and a supported Rails app.
+2. Run the gem’s own checks if developing locally:
+
+   ```bash
+   bundle exec rake
+   ```
+
+3. Open a GitHub issue with:
+   - BugSage version or Git commit SHA
+   - Ruby / Rails versions
+   - Steps to reproduce
+   - Relevant logs (redact secrets)
+
+For vulnerabilities, use [SECURITY.md](../SECURITY.md) instead of a public issue.