rails_pulse 0.4.2 → 0.5.0.pre.2

data/lib/rails_pulse/cli/client.rb

@@ -0,0 +1,64 @@
+require "net/http"
+require "openssl"
+require "uri"
+require "json"
+require_relative "config"
+
+module RailsPulse
+  module CLI
+    # HTTP client for the read-only JSON API under <mount>/api/v1.
+    class Client
+      class ApiError < StandardError; end
+
+      def initialize(config = nil)
+        @config = config || Config.load
+      end
+
+      def get(path, params = {})
+        uri = URI("#{@config.url}#{@config.mount_path}/api/v1#{path}")
+        uri.query = URI.encode_www_form(params) unless params.empty?
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          req = Net::HTTP::Get.new(uri)
+          req["X-Rails-Pulse-Token"] = @config.token
+          response = http.request(req)
+          raise_for(response) unless response.is_a?(Net::HTTPSuccess)
+          parse(response, uri)
+        end
+      rescue URI::InvalidURIError => e
+        raise ApiError, "the configured URL and mount path do not form a valid URL (#{e.message})"
+      rescue OpenSSL::SSL::SSLError => e
+        raise ApiError, "TLS failed talking to #{uri.host}:#{uri.port} (#{e.message})"
+      rescue SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout => e
+        raise ApiError, "could not connect to #{uri.host}:#{uri.port} (#{e.message})"
+      end
+
+      private
+
+      # A 200 that is not JSON is almost always the wrong URL or mount path
+      # answered by the host app itself: a login page or a catch-all route.
+      def parse(response, uri)
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        type = response["Content-Type"].to_s.split(";").first
+        raise ApiError, "#{uri} answered with #{type.to_s.empty? ? 'a non-JSON body' : type} rather than JSON. " \
+                        "Check the URL and mount path ('rails-pulse configure' or RAILS_PULSE_MOUNT_PATH)"
+      end
+
+      def raise_for(response)
+        body = begin
+          JSON.parse(response.body.to_s)
+        rescue JSON::ParserError
+          {}
+        end
+        body = {} unless body.is_a?(Hash)
+
+        # The API explains a 400 or 401 in the body ("Invalid sort. Valid
+        # values: ..."); relay it rather than only the status line.
+        message = "#{response.code} #{response.message}".strip
+        message = "#{message}: #{body["error"]}" if body["error"].is_a?(String) && !body["error"].empty?
+        raise ApiError, message
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/config.rb

@@ -0,0 +1,87 @@
+require "yaml"
+
+module RailsPulse
+  module CLI
+    # Where the CLI and MCP server find the app to talk to. Environment
+    # variables win; otherwise ~/.rails-pulse (or RAILS_PULSE_CONFIG), written
+    # by `rails-pulse configure`.
+    class Config
+      class ConfigError < StandardError; end
+
+      DEFAULT_PATH = "~/.rails-pulse".freeze
+      DEFAULT_MOUNT_PATH = "/rails_pulse".freeze
+      URL_SCHEMES = %r{\Ahttps?://\S+\z}i
+
+      # The file holds the API token, so nobody else on the machine may read it.
+      FILE_MODE = 0o600
+
+      attr_reader :url, :token, :mount_path
+
+      def initialize(url:, token:, mount_path: DEFAULT_MOUNT_PATH)
+        @url        = url.to_s.chomp("/")
+        @token      = token.to_s
+        # A root mount is an empty prefix, not "/", or every path gains "//".
+        trimmed     = mount_path.to_s.delete_prefix("/").chomp("/")
+        @mount_path = trimmed.empty? ? "" : "/#{trimmed}"
+
+        raise ConfigError, "RAILS_PULSE_URL must start with http:// or https:// (got #{@url.inspect})" unless @url.match?(URL_SCHEMES)
+        # The API path is appended to the URL, so anything after the host
+        # belongs in the mount path instead.
+        if @url.match?(/[?#]/)
+          raise ConfigError, "RAILS_PULSE_URL must not contain a query string or fragment (got #{@url.inspect})"
+        end
+      end
+
+      def self.path
+        File.expand_path(ENV.fetch("RAILS_PULSE_CONFIG", DEFAULT_PATH))
+      end
+
+      def self.load
+        url        = ENV["RAILS_PULSE_URL"]
+        token      = ENV["RAILS_PULSE_TOKEN"]
+        mount_path = ENV["RAILS_PULSE_MOUNT_PATH"]
+
+        # Complete credentials in the environment never touch the file, so a
+        # broken ~/.rails-pulse cannot block a setup that does not use it.
+        if url.nil? || token.nil?
+          data       = read_file
+          url        ||= data["url"]
+          token      ||= data["token"]
+          mount_path ||= data["mount_path"]
+        end
+
+        url = url.to_s.chomp("/")
+
+        raise ConfigError, "RAILS_PULSE_URL is not set. Run 'rails-pulse configure'" if url.empty?
+        raise ConfigError, "RAILS_PULSE_TOKEN is not set. Run 'rails-pulse configure'" if token.to_s.empty?
+
+        new(url: url, token: token, mount_path: mount_path || DEFAULT_MOUNT_PATH)
+      end
+
+      def self.write!(url:, token:, mount_path: nil)
+        data = { "url" => url.to_s.chomp("/"), "token" => token.to_s }
+        data["mount_path"] = mount_path if mount_path && mount_path != DEFAULT_MOUNT_PATH
+        # perm: applies only when the file is created, so an existing file is
+        # narrowed before the token is written into it.
+        File.chmod(FILE_MODE, path) if File.exist?(path)
+        File.write(path, YAML.dump(data), perm: FILE_MODE)
+        File.chmod(FILE_MODE, path)
+      end
+
+      # The parsed config file, or an empty hash when there is none yet.
+      def self.read_file
+        data = YAML.safe_load_file(path)
+        raise ConfigError, "#{path} should be a YAML mapping with url and token keys" unless data.nil? || data.is_a?(Hash)
+
+        data || {}
+      rescue Errno::ENOENT
+        {}
+      rescue Errno::EACCES, Errno::EISDIR => e
+        raise ConfigError, "#{path} cannot be read (#{e.message}). Fix its permissions or run 'rails-pulse configure'"
+      rescue Psych::SyntaxError => e
+        raise ConfigError, "#{path} is not valid YAML (#{e.message}). Fix it or run 'rails-pulse configure'"
+      end
+      private_class_method :read_file
+    end
+  end
+end

data/lib/rails_pulse/cli/configure.rb

@@ -0,0 +1,75 @@
+require_relative "base_command"
+require_relative "config"
+require_relative "client"
+
+module RailsPulse
+  module CLI
+    class Configure < BaseCommand
+      default_task :setup
+
+      desc "setup", "Prompt for URL and API token, test the connection, and write ~/.rails-pulse"
+      long_desc <<~DESC
+        Interactively configure credentials for the Rails Pulse JSON API.
+
+        Prompts for:
+          - Rails Pulse URL  (e.g. http://localhost:3000)
+          - API token        (matches config.api_token in the app's Rails Pulse initializer)
+          - Mount path       (where the engine is mounted; default /rails_pulse)
+
+        Existing values are shown as defaults — press Enter to keep them.
+        The token is not echoed as you type it.
+
+        A test request is made before saving. If it fails, no file is written.
+        Credentials are saved to ~/.rails-pulse (never to the project directory),
+        readable only by you.
+
+        You can also skip this command and set environment variables instead:
+          RAILS_PULSE_URL, RAILS_PULSE_TOKEN, RAILS_PULSE_MOUNT_PATH (optional)
+      DESC
+      def setup
+        current = begin
+          Config.load
+        rescue Config::ConfigError
+          nil
+        end
+
+        url = ask_with_default("Rails Pulse URL", current&.url)
+        token = ask_with_default("API token", current&.token, echo: false, mask: true)
+        mount_path = ask_with_default("Mount path", current&.mount_path || Config::DEFAULT_MOUNT_PATH)
+
+        say "Testing connection..."
+        begin
+          test_config = Config.new(url: url, token: token, mount_path: mount_path)
+          Client.new(test_config).get("/routes", { limit: 1 })
+        rescue Config::ConfigError, Client::ApiError => e
+          say "Connection failed: #{e.message}", :red
+          exit 1
+        end
+
+        Config.write!(url: url, token: token, mount_path: test_config.mount_path)
+        say "Configuration saved to #{Config.path}", :green
+      end
+
+      private
+
+      # Prompts with the current value as the default; an empty answer keeps
+      # it. A masked default shows only that a value exists, never the token.
+      def ask_with_default(label, default, echo: true, mask: false)
+        prompt = if default.to_s.empty?
+          "#{label}:"
+        else
+          "#{label} [#{mask ? 'keep current' : default}]:"
+        end
+        # Hiding input needs a terminal; piped input has nothing to hide from.
+        hide = !echo && terminal?
+        answer = ask(prompt, echo: !hide)
+        say "" if hide
+        answer.to_s.empty? ? default.to_s : answer
+      end
+
+      def terminal?
+        $stdin.tty?
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/coverage.rb

@@ -0,0 +1,91 @@
+require_relative "base_command"
+require_relative "formatter"
+
+module RailsPulse
+  module CLI
+    class Coverage < BaseCommand
+      desc "show", "Report what has been recorded, how recently, and any gaps"
+      long_desc <<~DESC
+        Answers whether the data is there, rather than a question about the data: which
+        application and environment answered, the span of requests, job runs and exceptions
+        held, how far summaries have been generated, what retention keeps, and whether the
+        background writer has dropped anything.
+
+        Read this before concluding that nothing went wrong. An empty error list means
+        "nothing recorded", which is only the same as "nothing happened" when collection was
+        healthy over the window in question.
+
+        Use --json for the full structure.
+      DESC
+      option :json, type: :boolean, default: false, desc: "Output raw JSON"
+      def show
+        with_error_handling do
+          data = client.get("/coverage", {})
+          capabilities = client.get("/capabilities", {})
+          next say(JSON.pretty_generate(data.merge("capabilities" => capabilities))) if options[:json]
+
+          print_installation(capabilities)
+          print_telemetry(data["telemetry"] || {})
+          print_summaries(data["summaries"] || {})
+          print_retention(data["retention"] || {})
+          print_collection(data["collection"] || {})
+        end
+      end
+
+      private
+
+      def print_installation(capabilities)
+        say "Installation"
+        say "  application  #{capabilities['application'] || '—'} (#{capabilities['environment']})"
+        say "  version      #{capabilities['rails_pulse_version']}"
+        say ""
+      end
+
+      def print_telemetry(telemetry)
+        say "Telemetry"
+        telemetry.each do |kind, info|
+          if info["tracked"] == false
+            say "  #{kind.ljust(12)} not tracked — #{info['reason']}"
+          elsif info["newest"]
+            say "  #{kind.ljust(12)} #{info['count']} rows, #{info['oldest']} → #{info['newest']}"
+          else
+            say "  #{kind.ljust(12)} nothing recorded"
+          end
+        end
+      end
+
+      def print_summaries(summaries)
+        say ""
+        say "Summaries"
+        say "  hourly       #{summaries['hourly_from'] || '—'} → #{summaries['hourly_through'] || '—'}#{summaries['stale'] ? ' (stale)' : ''}"
+        say "  #{summaries['note']}" if summaries["note"]
+      end
+
+      def print_retention(retention)
+        say ""
+        say "Retention"
+        say "  raw records  #{days(retention['raw_records'])}"
+        say "  hourly       #{days(retention['hourly_summaries'])}"
+        say "  events       #{days(retention['events'])}"
+      end
+
+      def print_collection(collection)
+        say ""
+        say "Collection"
+        if collection["known"] == false
+          say "  unknown — #{collection['reason']}"
+          return
+        end
+
+        say "  writers      #{collection['live_writers']} live, queue #{collection['queue_depth']}/#{collection['queue_size']}"
+        say "  dropped      #{collection['dropped_last_hour']} in the last hour"
+        say "  last beat    #{collection['last_heartbeat_at'] || 'never'}"
+        say "  #{collection['note']}" if collection["note"]
+      end
+
+      def days(value)
+        value ? "#{value['days']} days" : "—"
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/deployments.rb

@@ -0,0 +1,54 @@
+require_relative "base_command"
+require_relative "formatter"
+
+module RailsPulse
+  module CLI
+    class Deployments < BaseCommand
+      COLUMNS = [
+        [ "Revision", 14, :short_revision ],
+        [ "Started",  25, :started_at ],
+        [ "Finished", 25, :finished_at ],
+        [ "Compared", 17, :compared ]
+      ].freeze
+
+      desc "list", "List recorded deployments"
+      long_desc <<~DESC
+        Returns deployments ordered by most recent first. A deployment still in progress has
+        no finish time.
+
+        Each deployment is compared across the hours it ran in: the hour before it started
+        against the hour after it finished. degraded when average or p95 response time is
+        more than 1.5x and at least 50ms worse afterwards, or the error rate more than 1.25x
+        and at least a percentage point worse; insufficient_data when either hour had fewer
+        than 10 requests; pending until the hour after has been summarized, or unavailable
+        when it never will be because SummaryJob is not running.
+
+        Filter by time window (ISO 8601):
+          --since 2026-06-01T00:00:00Z
+          --until 2026-06-01T23:59:59Z
+
+        Find a deployment by its full revision or the start of one:
+          --revision a1b2c3d
+
+        Use --json to get the full revision, duration, metadata and per-metric comparison.
+      DESC
+      option :limit,  type: :numeric, default: 25,    desc: "Max records to return (1–500)"
+      option :offset, type: :numeric, default: 0,     desc: "Number of records to skip (for pagination)"
+      option :since,  type: :string,                  desc: "Return deployments started at or after this time (ISO 8601)"
+      option :until,  type: :string,                  desc: "Return deployments started at or before this time (ISO 8601)"
+      option :revision, type: :string,                desc: "Full revision or the start of one"
+      option :json,   type: :boolean, default: false, desc: "Output raw JSON including meta envelope"
+      def list
+        with_error_handling do
+          params = { limit: options[:limit], offset: options[:offset] }
+          params[:since] = options[:since] if options[:since]
+          params[:until] = options[:until] if options[:until]
+          params[:revision] = options[:revision] if options[:revision]
+          result = client.get("/deployments", params)
+          (result["data"] || []).each { |row| row["compared"] = row.dig("comparison", "outcome") } unless options[:json]
+          Formatter.render(result, json: options[:json], columns: COLUMNS)
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/exceptions.rb

@@ -0,0 +1,116 @@
+require_relative "base_command"
+require_relative "formatter"
+require "json"
+
+module RailsPulse
+  module CLI
+    class Exceptions < BaseCommand
+      COLUMNS = [
+        [ "ID",        6, :id ],
+        [ "Class",    36, :exception_class ],
+        [ "Location", 40, :location ],
+        [ "Status",    9, :status ],
+        [ "Count",     6, :occurrence_count ],
+        [ "Last seen", 25, :last_seen_at ]
+      ].freeze
+
+      desc "list", "List exception groups"
+      long_desc <<~DESC
+        Returns exception groups — one row per exception class and location — ordered by most
+        recently seen first. Each row carries the group's lifecycle status (open, resolved,
+        ignored), how many times it has occurred, and when it was first and last seen.
+
+        Filter by status:
+          --status open
+
+        Search the class name or location:
+          --search RecordNotFound
+
+        Look up one group by its fingerprint, as listed with --json or by Rails Pulse Cloud:
+          --fingerprint 9b2c4e7a1f3d5c8b
+
+        Filter by when the group was last seen (ISO 8601):
+          --since 2026-06-01T00:00:00Z
+          --until 2026-06-01T23:59:59Z
+
+        Sort by last_seen_at (default), first_seen_at, or occurrence_count:
+          --sort occurrence_count
+
+        Use --json to get the latest message, fingerprint, and the full response envelope.
+      DESC
+      option :limit,  type: :numeric, default: 25,    desc: "Max records to return (1–500)"
+      option :offset, type: :numeric, default: 0,     desc: "Number of records to skip (for pagination)"
+      option :since,  type: :string,                  desc: "Return groups last seen at or after this time (ISO 8601)"
+      option :until,  type: :string,                  desc: "Return groups last seen at or before this time (ISO 8601)"
+      option :status, type: :string,                  desc: "Filter by status (open, resolved, ignored)"
+      option :search, type: :string,                  desc: "Substring match on exception class or location"
+      option :fingerprint, type: :string,             desc: "Exact fingerprint of one group"
+      option :sort,   type: :string,                  desc: "Sort by last_seen_at, first_seen_at, or occurrence_count"
+      option :json,   type: :boolean, default: false, desc: "Output raw JSON including meta envelope"
+      def list
+        with_error_handling do
+          params = { limit: options[:limit], offset: options[:offset] }
+          params[:since]  = options[:since]  if options[:since]
+          params[:until]  = options[:until]  if options[:until]
+          params[:status] = options[:status] if options[:status]
+          params[:search] = options[:search] if options[:search]
+          params[:fingerprint] = options[:fingerprint] if options[:fingerprint]
+          params[:sort]   = options[:sort]   if options[:sort]
+          result = client.get("/exceptions", params)
+          Formatter.render(result, json: options[:json], columns: COLUMNS)
+        end
+      end
+
+      desc "show ID", "Show one exception group with its recent occurrences and backtraces"
+      long_desc <<~DESC
+        Prints the group's class, location, status and counts, then each of its most recent
+        occurrences with request, environment, deploy SHA, filtered params, and the backtrace.
+
+          rails-pulse exceptions show 42
+          rails-pulse exceptions show 42 --occurrences 10 --json
+      DESC
+      option :occurrences, type: :numeric, default: 3,     desc: "Most recent occurrences to include (1–20)"
+      option :json,        type: :boolean, default: false, desc: "Output raw JSON"
+      def show(id)
+        with_error_handling do
+          result = client.get("/exceptions/#{id.to_i}", { occurrences: options[:occurrences] })
+          if options[:json]
+            puts JSON.pretty_generate(result)
+          else
+            render_group(result["data"] || {})
+          end
+        end
+      end
+
+      no_commands do
+        def render_group(group)
+          say ""
+          say "#{group["exception_class"]}  ##{group["id"]}", :bold
+          say "═" * 60
+          say "  Location:   #{group["location"] || "—"}"
+          say "  Status:     #{group["status"]}"
+          say "  Count:      #{group["occurrence_count"]}"
+          say "  First seen: #{group["first_seen_at"]}"
+          say "  Last seen:  #{group["last_seen_at"]}"
+          say "  Message:    #{group["message"]}" if group["message"]
+
+          Array(group["occurrences"]).each_with_index do |occurrence, index|
+            say ""
+            say "Occurrence #{index + 1} — #{occurrence["occurred_at"]}", :bold
+            say "  Request:  #{occurrence["request_method"]} #{occurrence["request_url"]}" if occurrence["request_url"]
+            say "  Env:      #{occurrence["environment"]}" if occurrence["environment"]
+            say "  Deploy:   #{occurrence["deploy_sha"]}" if occurrence["deploy_sha"]
+            say "  Params:   #{occurrence["request_params"].to_json}" if occurrence["request_params"]
+            say "  Message:  #{occurrence["message"]}" if occurrence["message"] && occurrence["message"] != group["message"]
+            Array(occurrence["backtrace"]).each do |frame|
+              location = frame.is_a?(Hash) ? "#{frame["file"]}:#{frame["line"]}#{frame["method"] ? " in #{frame["method"]}" : ""}" : frame.to_s
+              app = location.start_with?("app/", "lib/", "config/")
+              say "    #{app ? "▸" : " "} #{location}", app ? :green : nil
+            end
+          end
+          say ""
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/formatter.rb

@@ -0,0 +1,31 @@
+require "json"
+
+module RailsPulse
+  module CLI
+    class Formatter
+      def self.render(response, json: false, columns: [])
+        if json
+          puts JSON.pretty_generate(response)
+        else
+          render_table(response["data"], columns)
+        end
+      end
+
+      def self.render_table(rows, columns)
+        return puts "(no results)" if rows.empty?
+
+        header = columns.map { |header, width, _key| header.upcase.ljust(width) }.join("  ")
+        puts header
+        puts "-" * header.length
+
+        rows.each do |row|
+          line = columns.map do |_header, width, key|
+            val = row[key.to_s].to_s
+            val.length > width ? "#{val[0, width - 1]}…" : val.ljust(width)
+          end.join("  ")
+          puts line
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/insights.rb

@@ -0,0 +1,70 @@
+require_relative "base_command"
+require_relative "formatter"
+
+module RailsPulse
+  module CLI
+    class Insights < BaseCommand
+      PERIODS = %w[hour day week month].freeze
+
+      desc "show", "What needs attention over one period, and whether the thresholds fit it"
+      long_desc <<~DESC
+        Reads one summary period (an hour, day, week or month) and lists the routes, queries
+        and jobs past their slow or critical thresholds, critical first, ten at most. Then
+        checks route_thresholds and query_thresholds against the period's slowest routes and
+        most expensive queries, and suggests an initializer line when a slow threshold is
+        exceeded by most of them or a critical threshold is never approached.
+
+        Defaults to the last complete week. --at picks the period containing that time:
+          --period day --at 2026-06-10T00:00:00Z
+
+        Use --json for the full structure, including record ids and current thresholds.
+      DESC
+      option :period, type: :string, default: "week", enum: PERIODS, desc: "Summary period to read"
+      option :at,     type: :string,                                   desc: "A time inside the period (ISO 8601); default the last complete one"
+      option :json,   type: :boolean, default: false,                  desc: "Output raw JSON"
+      def show
+        with_error_handling do
+          params = { period: options[:period] }
+          params[:at] = options[:at] if options[:at]
+          data = client.get("/insights", params)
+          next say(JSON.pretty_generate(data)) if options[:json]
+
+          print_period(data["period"] || {})
+          print_attention(data["needs_attention"] || {})
+          print_recommendations(data["threshold_recommendations"] || [])
+        end
+      end
+
+      private
+
+      def print_period(period)
+        say "#{period['type'].to_s.capitalize} from #{period['start']} to #{period['end']}"
+        say "  not fully summarized yet — what follows may be incomplete" unless period["summarized"]
+        say ""
+      end
+
+      def print_attention(attention)
+        say "Needs attention"
+        items = Array(attention["critical"]) + Array(attention["warning"])
+        return say("  nothing past its thresholds") if items.empty?
+
+        items.each do |item|
+          say "  #{item['severity'].to_s.upcase.ljust(8)} #{item['type'].to_s.ljust(5)} #{item['name']}"
+          say "           #{item['reason']}"
+        end
+      end
+
+      def print_recommendations(recommendations)
+        say ""
+        say "Threshold recommendations"
+        return say("  none — the thresholds fit this period") if recommendations.empty?
+
+        recommendations.each do |rec|
+          say "  #{rec['title']}"
+          say "    #{rec['detail']}"
+          say "    #{rec['config_snippet']}"
+        end
+      end
+    end
+  end
+end