rails_pulse 0.4.2 → 0.5.0.pre.1

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,40 @@
+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 ]
+      ].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.
+
+        Filter by time window (ISO 8601):
+          --since 2026-06-01T00:00:00Z
+          --until 2026-06-01T23:59:59Z
+
+        Use --json to get the full revision, duration and deployment metadata.
+      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 :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]
+          result = client.get("/deployments", params)
+          Formatter.render(result, json: options[:json], columns: COLUMNS)
+        end
+      end
+    end
+  end
+end

data/lib/rails_pulse/cli/exceptions.rb

@@ -0,0 +1,111 @@
+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
+
+        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 :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[: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/install.rb

@@ -0,0 +1,145 @@
+require "fileutils"
+require_relative "base_command"
+
+module RailsPulse
+  module CLI
+    class Install < BaseCommand
+      AGENT_FILES_DIR = File.expand_path("agent_files", __dir__)
+
+      # Claude Code loads skills from ~/.claude/skills/<name>/SKILL.md; the
+      # file carries its own name and description in YAML front matter.
+      CLAUDE_SKILL_PATH = "~/.claude/skills/rails-pulse/SKILL.md".freeze
+
+      AGENTS_FILE = "agents.md".freeze
+
+      # Delimit the section so a re-run can replace exactly what a previous
+      # run wrote, leaving everything a project put around it untouched.
+      SECTION_START = "<!-- rails-pulse:start -->".freeze
+      SECTION_END = "<!-- rails-pulse:end -->".freeze
+      # Tolerates CRLF line endings and trailing spaces after a marker, which
+      # an editor or git's autocrlf can introduce between runs.
+      SECTION_PATTERN = /^#{Regexp.escape(SECTION_START)}[ \t]*\r?\n.*?^#{Regexp.escape(SECTION_END)}[ \t]*(?:\r?\n)?/m
+
+      INTEGRATIONS = {
+        "claude" => {
+          description: "Claude Code skill → #{CLAUDE_SKILL_PATH}",
+          source: "claude_skill.md"
+        },
+        "agents" => {
+          description: "Generic agent descriptor → ./#{AGENTS_FILE}",
+          source: "agents.md"
+        }
+      }.freeze
+
+      default_task :perform
+
+      desc "perform [INTEGRATION]", "Install an AI agent integration file"
+      long_desc <<~DESC
+        Copy a pre-built integration file to the correct location for the given agent framework.
+
+        Available integrations:
+          claude   Installs a Claude Code skill to #{CLAUDE_SKILL_PATH}.
+                   Claude Code then knows when and how to use the Rails Pulse MCP tools and CLI.
+                   An earlier copy of the skill is replaced.
+          agents   Installs a generic agent descriptor to ./#{AGENTS_FILE} in the current directory.
+                   Compatible with other AI agent frameworks, including Codex. When an agents.md
+                   or AGENTS.md already exists it is never overwritten: pass --append to add a
+                   delimited Rails Pulse section to the end of it, which a later --append
+                   replaces in place rather than duplicating.
+
+        Run --list to see all available integrations.
+      DESC
+      option :list, type: :boolean, desc: "List all available integrations and their destinations"
+      option :append, type: :boolean, default: false,
+                      desc: "For 'agents': add a delimited Rails Pulse section to an existing AGENTS.md"
+      def perform(integration = nil)
+        if options[:list]
+          say "Available integrations:"
+          INTEGRATIONS.each { |name, meta| say "  #{name.ljust(10)} #{meta[:description]}" }
+          return
+        end
+
+        case integration
+        when "claude"
+          install_claude
+        when "agents"
+          install_agents
+        else
+          say "Usage: rails-pulse install [claude|agents]", :yellow
+          say "       rails-pulse install --list"
+        end
+      end
+
+      private
+
+      def install_claude
+        dest = File.expand_path(CLAUDE_SKILL_PATH)
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(File.join(AGENT_FILES_DIR, "claude_skill.md"), dest)
+        say "Installed Claude Code skill to #{dest}", :green
+      end
+
+      # A project's own AGENTS.md is compared case-insensitively: on a
+      # case-insensitive filesystem (macOS by default) writing agents.md
+      # would silently replace it.
+      def install_agents
+        source = File.join(AGENT_FILES_DIR, "agents.md")
+        existing = Dir.children(Dir.pwd).find { |name| name.casecmp?(AGENTS_FILE) }
+
+        return append_to_agents(File.join(Dir.pwd, existing), source) if existing && options[:append]
+
+        if existing
+          say "#{File.join(Dir.pwd, existing)} already exists; not overwriting it.", :yellow
+          say "Run `rails-pulse install agents --append` to add a Rails Pulse section to it instead."
+          exit 1
+        end
+
+        # Written as a delimited section from the start, so a later --append
+        # recognises it and replaces it rather than adding a second copy.
+        dest = File.join(Dir.pwd, AGENTS_FILE)
+        File.write(dest, section(source, "\n"))
+        say "Installed agent descriptor to #{dest}", :green
+      end
+
+      # The project's own instructions are never rewritten: the Rails Pulse
+      # section is delimited, so a re-run replaces it where it sits and
+      # everything around it is left exactly as the project wrote it.
+      def append_to_agents(dest, source)
+        existing = File.read(dest)
+        newline = existing.include?("\r\n") ? "\r\n" : "\n"
+        section = section(source, newline)
+
+        if existing.match?(SECTION_PATTERN)
+          File.write(dest, existing.sub(SECTION_PATTERN) { section })
+          say "Updated the Rails Pulse section in #{dest}", :green
+        elsif existing.lstrip.start_with?(descriptor_title(source))
+          # A copy written before the section markers existed. Its end cannot
+          # be told from anything the project added after it, so it is left
+          # for a person to replace rather than guessed at or duplicated.
+          say "#{dest} starts with a Rails Pulse descriptor that has no section markers; not appending a second copy.", :yellow
+          say "Delete the Rails Pulse part of it (or the file, if nothing else is in it) and run this again."
+          exit 1
+        else
+          separator = if existing.empty? || existing.end_with?("#{newline}#{newline}")
+            ""
+          elsif existing.end_with?(newline)
+            newline
+          else
+            newline * 2
+          end
+          File.write(dest, "#{existing}#{separator}#{section}")
+          say "Appended a Rails Pulse section to #{dest}", :green
+        end
+      end
+
+      def section(source, newline)
+        body = File.read(source).strip.gsub(/\r?\n/, newline)
+        "#{SECTION_START}#{newline}#{body}#{newline}#{SECTION_END}#{newline}"
+      end
+
+      def descriptor_title(source)
+        File.foreach(source).first.to_s.strip
+      end
+    end
+  end
+end