concise_errors 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 746b9cdaa164daed16b8bc70adba8cb822ef52c9039a441ab1fc29d92c53e48f
+  data.tar.gz: 6af78b52ef0ce3cae853b72a379e9c744b55c06d6324acfd66d776d7870dc6c1
+SHA512:
+  metadata.gz: 4695c72ba6c43566bc957f975fb1c190f1bcbd66572d847554f8ea725fec6686be2990e8862c9b040f7367f3a169a1699a501b083965885c173ac69574410471
+  data.tar.gz: 4097761cb0f2a54d2d2f3c40eab9870c842c00f7a4efbbb82c4d31baa5316077e8160656ce891e96d76f9cd4134343a9cab61b33d69fb3f40320b049897b70be

data/.rubocop.yml

@@ -0,0 +1,10 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-10-22
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,21 @@
+# Code of Conduct
+
+This guideline exists to support a safe, respectful, and productive place for anyone contributing to the ConciseErrors project.
+
+## Scope
+
+This Code of Conduct applies to all collaborative spaces, including mailing lists, issues, patches/pull requests, commit comments, chats, and events.
+
+## Expected Behavior
+
+- Be tolerant of opposing views.
+- Assume good intentions when interpreting others’ words and actions.
+- Keep language and actions free of personal attacks or disparaging remarks.
+
+## Unacceptable Behavior
+
+- Harassment, or behavior that could reasonably be considered harassment.
+
+## Reporting
+
+Report concerns to the maintainers at obiefernandez@gmail.com. Reports will be reviewed promptly and fairly, and the privacy of reporters will be respected.

data/README.md

@@ -0,0 +1,76 @@
+# ConciseErrors
+
+ConciseErrors swaps Rails’ `ActionDispatch::DebugExceptions` middleware with a compact error page that focuses on the class, message, and a truncated backtrace. It was designed to give human developers and AI assistants the minimum viable context needed to diagnose a failure without the noise of the default HTML-heavy debugger.
+
+## Features
+
+- Tiny plain-text payloads by default (no inline assets, no copious markup).
+- Optional single-file HTML view optimised for dark/light mode without external CSS.
+- Configurable backtrace depth with an omission indicator.
+- Automatic fallback to `text/plain` when the request is `xhr?` or clients negotiate non-HTML `Accept` headers.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "concise_errors"
+```
+
+Run `bundle install` and restart your Rails server. ConciseErrors automatically swaps the middleware when the gem loads.
+
+## Configuration
+
+ConciseErrors ships with opinionated defaults — HTML output, no CSS, and Web Console middleware is automaticallyremoved in development — so simply installing the gem is enough. Override anything you need from `config/application.rb` or an environment-specific config:
+
+```ruby
+# config/environments/development.rb
+Rails.application.configure do
+  config.concise_errors.tap do |cfg|
+    cfg.stack_trace_lines = 5   # default: 10
+    cfg.format = :html          # available: :text (default) or :html
+    cfg.enabled = true          # flip to false to restore the stock debug page
+    cfg.application_root = Rails.root.to_s # optional: trim this prefix from traces
+    cfg.logger = Rails.logger              # optional: reuse your preferred logger
+  end
+end
+```
+
+You can also steer the default format via `ENV["CONCISE_ERRORS_FORMAT"]` (`text` or `html`).
+
+ConciseErrors only affects the debug middleware (the screen you see when `config.consider_all_requests_local` is true). Production 500 pages continue to use whatever `ActionDispatch::ShowExceptions` is configured to serve.
+
+## Sample Output
+
+Plain text format (default):
+
+```
+RuntimeError: bang
+HTTP 500 (Internal Server Error)
+
+app/controllers/widgets_controller.rb:12:in `show'
+app/controllers/widgets_controller.rb:12:in `show'
+...
+```
+
+HTML format renders the same content inside a single `<pre>` block with minimal inline styling suitable for AI agents that prefer HTML responses.
+
+## Development
+
+After checking out the repo run:
+
+```bash
+bin/setup
+bundle exec rake test
+```
+
+`bin/console` opens an IRB session with the gem loaded. To try the middleware in a real app, add a `path:` entry to a Rails application's Gemfile pointing at your local clone.
+
+Before cutting a release:
+
+1. Update `ConciseErrors::VERSION` and `CHANGELOG.md`.
+2. Run `bundle exec rake release` to tag, build, and push the gem.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/obie/concise_errors. All contributions are expected to follow the [code of conduct](https://github.com/obie/concise_errors/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: %i[test rubocop]

data/lib/concise_errors/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ConciseErrors
+  # Stores global configuration for the middleware.
+  class Configuration
+    DEFAULT_STACK_LINES = 10
+    DEFAULT_FORMAT = :text
+
+    attr_accessor :stack_trace_lines, :enabled, :logger, :application_root, :cleaner
+
+    def initialize
+      reset!
+    end
+
+    def format
+      (@format || DEFAULT_FORMAT).to_sym
+    end
+
+    def enabled?
+      enabled != false
+    end
+
+    def format=(value)
+      @format = value&.to_sym
+    end
+
+    def reset!
+      @format = :text
+      @stack_trace_lines = DEFAULT_STACK_LINES
+      @enabled = true
+      @logger = nil
+      @application_root = nil
+      @cleaner = nil
+    end
+  end
+end

data/lib/concise_errors/debug_exceptions.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "action_dispatch/http/content_security_policy"
+require "action_dispatch/http/mime_type"
+require "action_dispatch/http/parameters"
+require "action_dispatch/http/request"
+require "action_dispatch/middleware/debug_exceptions"
+
+module ConciseErrors
+  # Replacement middleware that keeps the existing API while producing concise output.
+  class DebugExceptions < ::ActionDispatch::DebugExceptions
+    def call(env)
+      env["action_dispatch.backtrace_cleaner"] ||= ConciseErrors.configuration.cleaner
+      super
+    end
+
+    private
+
+    def render_for_browser_request(request, wrapper)
+      formatter = Formatter.new(wrapper, request, ConciseErrors.configuration)
+      render(wrapper.status_code, formatter.body, formatter.content_type)
+    end
+
+    def logger(request)
+      ConciseErrors.logger || super
+    end
+  end
+end

data/lib/concise_errors/formatter.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "erb"
+require "rack/utils"
+
+module ConciseErrors
+  # Builds the compact error payload for browser responses.
+  class Formatter
+    OMITTED_SUFFIX = "... %<count>d more lines omitted"
+
+    def initialize(wrapper, request, configuration)
+      @wrapper = wrapper
+      @request = request
+      @configuration = configuration
+    end
+
+    def body
+      response_format == :html ? html_payload : text_payload
+    end
+
+    def content_type
+      response_format == :html ? "text/html" : "text/plain"
+    end
+
+    private
+
+    attr_reader :wrapper, :request, :configuration
+
+    def response_format
+      return :text if prefers_plain_text?
+
+      configuration.format
+    end
+
+    def text_payload
+      [heading_line, status_line, "", *truncated_trace].compact.join("\n")
+    end
+
+    def html_payload
+      <<~HTML
+        <!DOCTYPE html>
+        <html lang="en">
+          <head>
+            <meta charset="utf-8" />
+            <title>#{html_escape(heading_line)}</title>
+          </head>
+          <body>
+            <h1>#{html_escape(heading_line)}</h1>
+            <p>#{html_escape(status_line)}</p>
+            <pre>#{html_escape(truncated_trace.join("\n"))}</pre>
+          </body>
+        </html>
+      HTML
+    end
+
+    def heading_line
+      "#{wrapper.exception_class_name}: #{wrapper.message}".strip
+    end
+
+    def status_line
+      status = wrapper.status_code
+      message = Rack::Utils::HTTP_STATUS_CODES[status] || "Internal Server Error"
+      "HTTP #{status} (#{message})"
+    end
+
+    def truncated_trace
+      full_trace = Array(wrapper.exception_trace).map { |line| sanitize_trace(line) }
+      limit = configuration.stack_trace_lines
+
+      return full_trace if limit.nil? || limit <= 0 || full_trace.size <= limit
+
+      full_trace.first(limit) + [Kernel.format(OMITTED_SUFFIX, count: full_trace.size - limit)]
+    end
+
+    def html_escape(string)
+      ERB::Util.html_escape(string)
+    end
+
+    def prefers_plain_text?
+      return true if request.xhr?
+
+      accept = request.get_header("HTTP_ACCEPT").to_s
+      return false if accept.empty?
+
+      !accept.downcase.include?("html")
+    end
+
+    def sanitize_trace(line)
+      root = configuration.application_root.to_s
+      return line if root.empty?
+
+      line.sub(%r{\A#{Regexp.escape(root)}/?}, "./")
+    end
+  end
+end

data/lib/concise_errors/railtie.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module ConciseErrors
+  # Integrates the middleware with a host Rails application.
+  class Railtie < Rails::Railtie
+    config.concise_errors = ConciseErrors.configuration
+
+    initializer "concise_errors.configure_defaults" do |app|
+      ConciseErrors.configure do |config|
+        apply_framework_defaults(config, app)
+      end
+    end
+
+    initializer "concise_errors.swap_middleware" do |app|
+      next unless ConciseErrors.configuration.enabled?
+
+      stack = app.config.middleware
+      disable_web_console(stack)
+
+      begin
+        stack.swap ::ActionDispatch::DebugExceptions, ConciseErrors::DebugExceptions
+      rescue RuntimeError
+        stack.delete ::ActionDispatch::DebugExceptions
+        stack.use ConciseErrors::DebugExceptions
+      end
+    end
+
+    private
+
+    def apply_framework_defaults(config, app)
+      config.logger ||= detect_logger
+      config.application_root ||= detect_root(app)
+      config.format = detect_format if config.format == Configuration::DEFAULT_FORMAT
+      config.stack_trace_lines ||= Configuration::DEFAULT_STACK_LINES
+      config.cleaner ||= detect_cleaner
+    end
+
+    def detect_logger
+      return Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+
+      require "logger"
+      Logger.new($stdout)
+    end
+
+    def detect_root(app)
+      return Rails.root.to_s if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+      return unless app.respond_to?(:root) && app.root
+
+      app.root.to_s
+    end
+
+    def detect_cleaner
+      Rails.backtrace_cleaner if defined?(Rails) && Rails.respond_to?(:backtrace_cleaner)
+    end
+
+    def detect_format
+      configured = ENV.fetch("CONCISE_ERRORS_FORMAT", nil)&.strip
+      return configured.downcase.to_sym if configured && %w[text html].include?(configured.downcase)
+
+      :html
+    end
+
+    def disable_web_console(stack)
+      return unless defined?(WebConsole::Middleware)
+
+      stack.delete(WebConsole::Middleware)
+    end
+  end
+end

data/lib/concise_errors/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ConciseErrors
+  VERSION = "0.1.0"
+end

data/lib/concise_errors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/module/attribute_accessors"
+
+require_relative "concise_errors/version"
+require_relative "concise_errors/configuration"
+require_relative "concise_errors/formatter"
+require_relative "concise_errors/debug_exceptions"
+
+# ConciseErrors exposes configuration helpers and loads the custom error middleware.
+module ConciseErrors
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def logger
+      configuration.logger
+    end
+
+    def logger=(logger)
+      configuration.logger = logger
+    end
+
+    def application_root
+      configuration.application_root
+    end
+
+    def application_root=(path)
+      configuration.application_root = path
+    end
+
+    def cleaner
+      configuration.cleaner
+    end
+
+    def cleaner=(cleaner)
+      configuration.cleaner = cleaner
+    end
+  end
+end
+
+require_relative "concise_errors/railtie" if defined?(Rails::Railtie)

data/sig/concise_errors.rbs

@@ -0,0 +1,35 @@
+module ConciseErrors
+  VERSION: String
+
+  class Configuration
+    DEFAULT_FORMAT: Symbol
+    @format: Symbol
+    @stack_trace_lines: Integer?
+    @enabled: bool
+    @logger: untyped
+    @application_root: String?
+    @cleaner: untyped
+
+    attr_accessor stack_trace_lines: Integer?
+    attr_accessor enabled: bool
+    attr_accessor logger: untyped
+    attr_accessor application_root: String?
+    attr_accessor cleaner: untyped
+
+    def initialize: () -> void
+    def format: () -> Symbol
+    def format=:(Symbol | String | nil) -> void
+    def enabled?: () -> bool
+    def reset!: () -> void
+  end
+
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.reset_configuration!: () -> void
+  def self.logger: () -> untyped
+  def self.logger=:(untyped) -> void
+  def self.application_root: () -> String?
+  def self.application_root=:(String?) -> void
+  def self.cleaner: () -> untyped
+  def self.cleaner=:(untyped) -> void
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: concise_errors
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Obie Fernandez
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: 'ConciseErrors replaces ActionDispatch::DebugExceptions with a compact
+  error page that highlights the exception and a truncated backtrace, making Rails
+  crashes easier for humans and AI helpers alike.
+
+  '
+email:
+- obiefernandez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- README.md
+- Rakefile
+- lib/concise_errors.rb
+- lib/concise_errors/configuration.rb
+- lib/concise_errors/debug_exceptions.rb
+- lib/concise_errors/formatter.rb
+- lib/concise_errors/railtie.rb
+- lib/concise_errors/version.rb
+- sig/concise_errors.rbs
+homepage: https://github.com/obie/concise_errors
+licenses: []
+metadata:
+  homepage_uri: https://github.com/obie/concise_errors
+  source_code_uri: https://github.com/obie/concise_errors
+  changelog_uri: https://github.com/obie/concise_errors/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Minimal Rails error pages tuned for AI agents and compact debugging.
+test_files: []