rubylens 0.1.0 → 0.2.0

data/lib/rubylens/clip/chrome_page.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "base64"
+require "fileutils"
+require "json"
+require "net/http"
+require "tmpdir"
+require "uri"
+require_relative "../errors"
+require_relative "deadline_io"
+require_relative "web_socket_channel"
+
+module RubyLens
+  module Clip
+    # Runs a headless Chrome/Chromium with an ephemeral DevTools port and a
+    # throwaway profile, attaches to the page that loads the showcase HTML,
+    # and exposes the two operations clip rendering needs: evaluate and
+    # screenshot. The port comes from the profile's DevToolsActivePort file,
+    # so parallel clips never race for a fixed port.
+    class ChromePage
+      HEADLESS_FLAGS = %w[
+        --headless=new
+        --remote-debugging-port=0
+        --no-first-run
+        --no-default-browser-check
+        --disable-background-networking
+        --disable-component-update
+        --disable-sync
+        --mute-audio
+        --hide-scrollbars
+        --force-device-scale-factor=1
+        --force-color-profile=srgb
+        --enable-unsafe-swiftshader
+      ].freeze
+      LAUNCH_TIMEOUT_SECONDS = 30
+
+      def self.open(executable:, url:, width:, height:)
+        page = new(executable:, url:, width:, height:)
+        begin
+          yield page
+        ensure
+          page.close
+        end
+      end
+
+      def initialize(executable:, url:, width:, height:)
+        @profile = Dir.mktmpdir("rubylens-clip-")
+        @next_id = 0
+        @responses = {}
+        flags = HEADLESS_FLAGS.dup
+        # Chrome refuses its sandbox as root (typical for containers and CI).
+        flags << "--no-sandbox" if Process.euid.zero?
+        flags << "--window-size=#{width},#{height}"
+        flags << "--user-data-dir=#{@profile}"
+        @pid = Process.spawn(executable, *flags, url, %i[out err] => File::NULL)
+        port = wait_for_devtools_port
+        @channel = WebSocketChannel.new("127.0.0.1", port, page_target_path(port))
+        # The headless window includes non-viewport space; pin the viewport so
+        # captures are exactly the stage size.
+        command("Emulation.setDeviceMetricsOverride", {
+          "width" => width, "height" => height, "deviceScaleFactor" => 1, "mobile" => false
+        }, timeout: 30)
+      rescue Errno::ENOENT => error
+        abort_start
+        raise Error, "could not launch Chrome at #{executable}: #{error.message}"
+      rescue SystemCallError => error
+        # A startup race (Chrome exiting or closing its port mid-attach) must
+        # surface as a normal rubylens error, not a raw Errno stack trace.
+        abort_start
+        raise Error, "could not attach to Chrome's DevTools endpoint: #{error.message}"
+      rescue StandardError
+        abort_start
+        raise
+      end
+
+      def evaluate(expression, await: false, timeout: 30)
+        result = command("Runtime.evaluate", {
+          "expression" => expression,
+          "returnByValue" => true,
+          "awaitPromise" => await,
+        }, timeout:)
+        if (details = result["exceptionDetails"])
+          raise Error, "the showcase page raised: #{details.dig("exception", "description") || details["text"]}"
+        end
+        result.dig("result", "value")
+      end
+
+      def screenshot_png(timeout: 60)
+        data = command("Page.captureScreenshot", { "format" => "png", "optimizeForSpeed" => true }, timeout:)
+        Base64.decode64(data.fetch("data"))
+      end
+
+      def close
+        begin
+          command("Browser.close", {}, timeout: 3) if @channel
+        rescue Error
+          terminate
+        end
+        Process.wait(@pid) if @pid
+      rescue Errno::ECHILD
+        nil
+      ensure
+        @channel&.close
+        FileUtils.remove_entry(@profile) if @profile && File.directory?(@profile)
+      end
+
+      private
+
+      # A failed start never reaches ChromePage.open's ensure, so the spawned
+      # browser and throwaway profile must be cleaned up before re-raising.
+      # The unconditional kill keeps close's Process.wait from hanging on a
+      # live Chrome with no channel.
+      def abort_start
+        terminate if @pid
+        close
+      end
+
+      def terminate
+        Process.kill("KILL", @pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def command(method, params, timeout:)
+        id = (@next_id += 1)
+        @channel.send_text(JSON.generate({ "id" => id, "method" => method, "params" => params }))
+        loop do
+          if (message = @responses.delete(id))
+            if (error = message["error"])
+              raise Error, "Chrome rejected #{method}: #{error["message"]}"
+            end
+            return message.fetch("result")
+          end
+          message = JSON.parse(@channel.read_text(timeout:))
+          @responses[message["id"]] = message if message["id"]
+        end
+      end
+
+      def wait_for_devtools_port
+        port_path = File.join(@profile, "DevToolsActivePort")
+        deadline = DeadlineIO.deadline(LAUNCH_TIMEOUT_SECONDS)
+        while DeadlineIO.monotonic < deadline
+          if File.exist?(port_path)
+            # to_i reads the leading port line and tolerates a mid-write file.
+            port = File.read(port_path).to_i
+            return port if port.positive?
+          end
+          if Process.waitpid(@pid, Process::WNOHANG)
+            @pid = nil
+            raise Error, "Chrome exited while starting up; it may not support headless rendering here"
+          end
+          sleep 0.05
+        end
+        raise Error, "Chrome did not publish a DevTools port within #{LAUNCH_TIMEOUT_SECONDS} seconds"
+      end
+
+      def page_target_path(port)
+        deadline = DeadlineIO.deadline(LAUNCH_TIMEOUT_SECONDS)
+        while DeadlineIO.monotonic < deadline
+          begin
+            target = JSON.parse(http_get(port, "/json/list")).find { |info| info["type"] == "page" }
+            if (socket_url = target&.fetch("webSocketDebuggerUrl", nil))
+              return URI(socket_url).path
+            end
+          rescue Error, SystemCallError, JSON::ParserError, Timeout::Error, EOFError
+            # The HTTP endpoint can lag DevToolsActivePort; retry until the deadline.
+          end
+          sleep 0.05
+        end
+        raise Error, "Chrome never exposed the showcase page for capture"
+      end
+
+      # The explicit nil proxy argument keeps this loopback request off any
+      # configured HTTP proxy.
+      def http_get(port, path, timeout: 10)
+        http = Net::HTTP.new("127.0.0.1", port, nil)
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.get(path).body
+      end
+    end
+  end
+end

data/lib/rubylens/clip/deadline_io.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module RubyLens
+  module Clip
+    # Deadline-bounded, non-blocking socket reads shared by the DevTools
+    # WebSocket channel and the local DevTools HTTP client.
+    module DeadlineIO
+      module_function
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def deadline(timeout) = monotonic + timeout
+
+      def read_chunk(socket, deadline, closed_message:, timeout_message:)
+        remaining = deadline - monotonic
+        raise Error, timeout_message if remaining <= 0
+        IO.select([socket], nil, nil, remaining) or raise Error, timeout_message
+        chunk = socket.read_nonblock(1 << 20, exception: false)
+        raise Error, closed_message if chunk.nil?
+        chunk.is_a?(String) ? chunk : "".b
+      rescue SystemCallError, IOError => error
+        raise Error, "#{closed_message}: #{error.message}"
+      end
+    end
+  end
+end

data/lib/rubylens/clip/renderer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "open3"
+require "uri"
+require_relative "../errors"
+require_relative "chrome_page"
+require_relative "deadline_io"
+
+module RubyLens
+  module Clip
+    # Renders a showcase HTML file into an H.264 MP4: headless Chrome steps
+    # the showcase's deterministic clip frames, and each captured frame is
+    # streamed straight into ffmpeg so no frame images ever touch disk. One
+    # render covers exactly one camera loop, so the video loops seamlessly.
+    class Renderer
+      STAGE_WIDTH = 1920
+      STAGE_HEIGHT = 1080
+      DEFAULT_FPS = 30
+      READY_TIMEOUT_SECONDS = 120
+      MARKER_COMMENT = "RubyLens clip"
+
+      def initialize(chrome:, ffmpeg:, fps: DEFAULT_FPS, frame_limit: nil, progress: nil)
+        @chrome = chrome
+        @ffmpeg = ffmpeg
+        @fps = Integer(fps)
+        @frame_limit = frame_limit
+        @progress = progress
+      end
+
+      def render(showcase_html:, output:)
+        ChromePage.open(executable: @chrome, url: file_url(showcase_html), width: STAGE_WIDTH, height: STAGE_HEIGHT) do |page|
+          wait_until_ready(page)
+          preset = begin_clip(page)
+          frames = frame_count(preset)
+          encode(page, frames, output)
+        end
+        output
+      end
+
+      private
+
+      def file_url(path)
+        "file://#{URI::DEFAULT_PARSER.escape(File.expand_path(path))}"
+      end
+
+      def wait_until_ready(page)
+        deadline = DeadlineIO.deadline(READY_TIMEOUT_SECONDS)
+        until page.evaluate("document.documentElement?.dataset.showcaseReady === 'true'")
+          raise Error, "the showcase page never finished loading" if DeadlineIO.monotonic > deadline
+
+          sleep 0.1
+        end
+      end
+
+      def begin_clip(page)
+        preset = page.evaluate("beginShowcaseClip()")
+        status = preset.is_a?(Hash) ? preset["status"] : nil
+        raise Error, "Chrome could not initialize WebGL2, which clip rendering requires" if status == "renderer-unavailable"
+        raise Error, "the page is not a RubyLens showcase" unless status == "ok"
+
+        preset
+      end
+
+      def frame_count(preset)
+        frames = Integer(preset.fetch("durationMs")) * @fps / 1000
+        @frame_limit ? [frames, Integer(@frame_limit)].min : frames
+      end
+
+      def ffmpeg_arguments(output)
+        [
+          @ffmpeg, "-loglevel", "error", "-y",
+          "-f", "image2pipe", "-c:v", "png", "-framerate", @fps.to_s, "-i", "-",
+          "-c:v", "libx264", "-preset", "medium", "-crf", "18", "-pix_fmt", "yuv420p",
+          "-movflags", "+faststart",
+          "-metadata", "comment=#{MARKER_COMMENT}",
+          "-f", "mp4", output
+        ]
+      end
+
+      def encode(page, frames, output)
+        stdin, stderr, waiter = Open3.popen3(*ffmpeg_arguments(output)).then { |i, o, e, t| o.close; [i, e, t] }
+        stdin.binmode
+        stderr_reader = Thread.new { stderr.read }
+        begin
+          frames.times do |index|
+            page.evaluate("renderShowcaseClipFrame(#{index}, #{@fps})", await: true)
+            stdin.write(page.screenshot_png)
+            @progress&.call(index + 1, frames)
+          end
+          stdin.close
+          raise Error, "ffmpeg failed while encoding the clip: #{failure_reason(stderr_reader.value)}" unless waiter.value.success?
+        rescue Errno::EPIPE
+          raise Error, "ffmpeg stopped accepting frames: #{failure_reason(stderr_reader.value)}"
+        ensure
+          # On a capture-side failure, closing stdin lets ffmpeg finish and
+          # exit, the waiter reaps it, and the stderr reader ends on EOF, so
+          # only the original error surfaces.
+          stdin.close unless stdin.closed?
+          waiter.value
+          stderr_reader.value
+          stderr.close unless stderr.closed?
+        end
+      rescue Errno::ENOENT => error
+        raise Error, "could not run ffmpeg at #{@ffmpeg}: #{error.message}"
+      end
+
+      def failure_reason(stderr_output)
+        lines = stderr_output.to_s.strip.lines.last(3).map(&:strip)
+        lines.empty? ? "no error output" : lines.join(" / ")
+      end
+    end
+  end
+end

data/lib/rubylens/clip/toolchain.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module RubyLens
+  module Clip
+    # Locates the two external tools clip rendering needs: a Chrome/Chromium
+    # binary and ffmpeg. Environment overrides win, then PATH, then well-known
+    # install locations. Discovery failures raise with install guidance so the
+    # command fails fast, before any indexing work.
+    module Toolchain
+      CHROME_ENV = "RUBYLENS_CHROME"
+      FFMPEG_ENV = "RUBYLENS_FFMPEG"
+      CHROME_COMMANDS = %w[google-chrome google-chrome-stable chromium chromium-browser chrome].freeze
+      CHROME_KNOWN_PATHS = [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      ].freeze
+      PLAYWRIGHT_CHROME_GLOBS = %w[
+        chromium
+        chromium-*/chrome-linux/chrome
+        chromium-*/chrome-mac/Chromium.app/Contents/MacOS/Chromium
+      ].freeze
+
+      module_function
+
+      def chrome_path
+        from_environment(CHROME_ENV) ||
+          from_path(CHROME_COMMANDS) ||
+          from_known_paths(CHROME_KNOWN_PATHS + playwright_chrome_candidates) ||
+          raise(Error, "clip rendering needs Chrome or Chromium; install Google Chrome, " \
+                       "or point #{CHROME_ENV} at a Chrome-compatible browser binary")
+      end
+
+      def ffmpeg_path
+        from_environment(FFMPEG_ENV) ||
+          from_path(%w[ffmpeg]) ||
+          raise(Error, "clip rendering needs ffmpeg; install it (for example `brew install ffmpeg` " \
+                       "or `apt install ffmpeg`), or point #{FFMPEG_ENV} at an ffmpeg binary")
+      end
+
+      def from_environment(name)
+        value = ENV.fetch(name, nil)
+        return nil if value.nil? || value.empty?
+        raise Error, "#{name} is set to #{value}, which is not an executable file" unless executable?(value)
+
+        value
+      end
+
+      def from_path(commands)
+        directories = ENV.fetch("PATH", "").split(File::PATH_SEPARATOR)
+        commands.each do |command|
+          directories.each do |directory|
+            next if directory.empty?
+
+            candidate = File.join(directory, command)
+            return candidate if executable?(candidate)
+          end
+        end
+        nil
+      end
+
+      def from_known_paths(paths)
+        paths.find { |path| executable?(path) }
+      end
+
+      def playwright_chrome_candidates
+        root = ENV.fetch("PLAYWRIGHT_BROWSERS_PATH", nil)
+        root = File.expand_path("~/.cache/ms-playwright") if root.nil? || root.empty?
+        PLAYWRIGHT_CHROME_GLOBS.flat_map { |pattern| Dir.glob(File.join(root, pattern)) }.sort
+      rescue ArgumentError
+        # File.expand_path("~") raises when HOME is unset.
+        []
+      end
+
+      def executable?(path)
+        File.file?(path) && File.executable?(path)
+      end
+    end
+  end
+end

data/lib/rubylens/clip/web_socket_channel.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest/sha1"
+require "securerandom"
+require "socket"
+require_relative "../errors"
+require_relative "deadline_io"
+
+module RubyLens
+  module Clip
+    # Minimal RFC 6455 client for Chrome's local DevTools WebSocket endpoint,
+    # so clip rendering needs no gem or Node dependencies. Client frames are
+    # masked text; ping, close, and fragmented server frames are handled;
+    # extensions are never negotiated.
+    class WebSocketChannel
+      HANDSHAKE_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+      TEXT_OPCODE = 1
+      CONTINUATION_OPCODE = 0
+      CLOSE_OPCODE = 8
+      PING_OPCODE = 9
+      PONG_OPCODE = 10
+
+      def initialize(host, port, path, timeout: 15)
+        @socket = TCPSocket.new(host, port)
+        @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+        @buffer = +"".b
+        handshake(host, port, path, timeout)
+      end
+
+      def send_text(payload)
+        bytes = payload.b
+        length = bytes.bytesize
+        header = if length < 126 then [0x80 | TEXT_OPCODE, 0x80 | length].pack("CC")
+                 elsif length < 65_536 then [0x80 | TEXT_OPCODE, 0x80 | 126, length].pack("CCn")
+                 else [0x80 | TEXT_OPCODE, 0x80 | 127, length].pack("CCQ>")
+                 end
+        mask = SecureRandom.bytes(4)
+        @socket.write(header + mask + apply_mask(bytes, mask))
+      rescue SystemCallError, IOError => error
+        raise Error, "lost the Chrome DevTools connection: #{error.message}"
+      end
+
+      def read_text(timeout: 30)
+        deadline = DeadlineIO.deadline(timeout)
+        message = +"".b
+        loop do
+          finished, opcode, payload = read_frame(deadline)
+          case opcode
+          when TEXT_OPCODE, CONTINUATION_OPCODE then message << payload
+          when CLOSE_OPCODE then raise Error, "Chrome closed the DevTools connection"
+          when PING_OPCODE then send_control(PONG_OPCODE, payload)
+          end
+          return message.force_encoding(Encoding::UTF_8) if finished && opcode <= TEXT_OPCODE && !message.empty?
+        end
+      end
+
+      def close
+        @socket.close unless @socket.closed?
+      rescue IOError
+        nil
+      end
+
+      private
+
+      def handshake(host, port, path, timeout)
+        deadline = DeadlineIO.deadline(timeout)
+        key = SecureRandom.base64(16)
+        @socket.write("GET #{path} HTTP/1.1\r\nHost: #{host}:#{port}\r\n" \
+                      "Upgrade: websocket\r\nConnection: Upgrade\r\n" \
+                      "Sec-WebSocket-Key: #{key}\r\nSec-WebSocket-Version: 13\r\n\r\n")
+        response = +"".b
+        response << read_chunk(deadline) until response.include?("\r\n\r\n")
+        head, _, rest = response.partition("\r\n\r\n")
+        raise Error, "Chrome refused the DevTools WebSocket: #{head.lines.first&.strip}" unless head.start_with?("HTTP/1.1 101")
+
+        expected = Base64.strict_encode64(Digest::SHA1.digest(key + HANDSHAKE_GUID))
+        unless head.match?(/^sec-websocket-accept:\s*#{Regexp.escape(expected)}\s*$/i)
+          raise Error, "Chrome DevTools WebSocket handshake failed verification"
+        end
+
+        @buffer << rest
+      end
+
+      def apply_mask(bytes, mask)
+        masked = bytes.dup
+        masked.bytesize.times { |index| masked.setbyte(index, masked.getbyte(index) ^ mask.getbyte(index % 4)) }
+        masked
+      end
+
+      def send_control(opcode, payload)
+        mask = SecureRandom.bytes(4)
+        @socket.write([0x80 | opcode, 0x80 | payload.bytesize].pack("CC") + mask + apply_mask(payload, mask))
+      end
+
+      def read_frame(deadline)
+        first, second = read_exact(2, deadline).unpack("CC")
+        length = second & 0x7F
+        length = read_exact(2, deadline).unpack1("n") if length == 126
+        length = read_exact(8, deadline).unpack1("Q>") if length == 127
+        [first.anybits?(0x80), first & 0x0F, read_exact(length, deadline)]
+      end
+
+      def read_exact(length, deadline)
+        @buffer << read_chunk(deadline) while @buffer.bytesize < length
+        @buffer.slice!(0, length)
+      end
+
+      def read_chunk(deadline)
+        DeadlineIO.read_chunk(@socket, deadline,
+                              closed_message: "Chrome closed the DevTools connection",
+                              timeout_message: "timed out waiting for Chrome")
+      end
+    end
+  end
+end

data/lib/rubylens/clip_generator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "artifact_marker"
+require_relative "atomic_output"
+require_relative "default_output"
+require_relative "showcase_generator"
+require_relative "clip/renderer"
+require_relative "clip/toolchain"
+
+module RubyLens
+  ClipResult = Data.define(:output_path, :showcase_path, :counts, :warnings) do
+    def to_payload = { output: output_path, showcase: showcase_path, counts: counts, warnings: warnings }
+  end
+
+  # Generates a shareable MP4 of a project's showcase. The showcase HTML is
+  # written first (it is the render input and stays useful on its own), then
+  # headless Chrome and ffmpeg turn it into one seamless 1080p camera loop.
+  # The toolchain is checked before any indexing so a missing browser or
+  # ffmpeg fails in under a second with install guidance.
+  class ClipGenerator
+    DEFAULT_CLIP_NAME = "rubylens-clip.mp4"
+    # faststart parks the metadata (and so the marker) right behind ftyp, so
+    # every clip RubyLens writes matches within this head window.
+    MARKER_SCAN_HEAD_BYTES = 512 * 1024
+
+    def initialize(path: Dir.pwd, output: nil, lockfile: nil, details: false, progress: nil, renderer: nil)
+      @path = path
+      @output = output
+      @lockfile = lockfile
+      @details = details
+      @progress = progress
+      @renderer = renderer
+    end
+
+    def call
+      renderer = @renderer || build_renderer
+      root = File.realpath(@path)
+      output, showcase_output = resolve_outputs(root)
+      showcase_result = ShowcaseGenerator.new(
+        path: @path, output: showcase_output, lockfile: @lockfile, details: @details,
+      ).call
+      render_atomically(renderer, showcase_result.output_path, output)
+
+      ClipResult.new(
+        output_path: output,
+        showcase_path: showcase_result.output_path,
+        counts: showcase_result.counts,
+        warnings: showcase_result.warnings,
+      )
+    rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP => error
+      raise Error, error.message
+    end
+
+    private
+
+    def build_renderer
+      Clip::Renderer.new(
+        chrome: Clip::Toolchain.chrome_path,
+        ffmpeg: Clip::Toolchain.ffmpeg_path,
+        progress: @progress,
+      )
+    end
+
+    # With no --output, both artifacts use their default names, Git-excluded
+    # locally, and an existing default clip is only replaced if it is ours.
+    # With --output FILE.mp4, the MP4 is written exactly where requested, like
+    # other custom output paths; the derived FILE.html companion was never
+    # named by the user, so an unrelated existing file there is refused.
+    def resolve_outputs(root)
+      if @output.nil?
+        default = DefaultOutput.resolve(root: root, name: DEFAULT_CLIP_NAME, description: "clip") do |existing|
+          ArtifactMarker.present?(existing, Clip::Renderer::MARKER_COMMENT, head_bytes: MARKER_SCAN_HEAD_BYTES)
+        end
+        return [default, nil]
+      end
+
+      # Expanded once here so the guard, the writer, and the reported result
+      # all refer to the same real paths.
+      output = File.expand_path(@output)
+      companion = showcase_companion_path(output)
+      if File.exist?(companion) && !ArtifactMarker.present?(companion, ShowcaseWriter::MARKER)
+        raise Error, "clip companion path #{companion} already exists and is not a RubyLens showcase"
+      end
+
+      [output, companion]
+    end
+
+    def showcase_companion_path(output)
+      base = output.sub(/\.mp4\z/i, "")
+      base = output if base.empty?
+      "#{base}.html"
+    end
+
+    def render_atomically(renderer, showcase_html, output)
+      AtomicOutput.replace(output) do |temporary|
+        renderer.render(showcase_html: showcase_html, output: temporary)
+      rescue Error => error
+        raise Error, "#{error.message} (the showcase HTML was still written to #{showcase_html})"
+      end
+    end
+  end
+end

data/lib/rubylens/default_output.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "git_repository"
+
+module RubyLens
+  # Safety policy shared by every generator's default output path: an existing
+  # file is only replaced when the given check recognizes it as our own kind of
+  # artifact, and the path plus its temporary-file pattern are added to the
+  # repository's local Git excludes.
+  module DefaultOutput
+    module_function
+
+    def resolve(root:, name:, description:)
+      output = File.join(root, name)
+      if File.exist?(output) && !yield(output)
+        raise Error, "default #{description} path already exists and is not a RubyLens #{description}"
+      end
+
+      GitRepository.new(root).exclude_local(output, description: description)
+      output
+    end
+  end
+end

data/lib/rubylens/generator.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
+require_relative "artifact_marker"
+require_relative "default_output"
+
 module RubyLens
-  Result = Data.define(:output_path, :counts, :warnings)
+  Result = Data.define(:output_path, :counts, :warnings) do
+    def to_payload = { output: output_path, counts: counts, warnings: warnings }
+  end
 
   class GenerationPipeline
     def initialize(root:, lockfile: nil)
@@ -32,17 +37,11 @@ module RubyLens
 
     def call
       root = File.realpath(@path)
-      report_writer = ReportWriter.new
-      output = @output
-      if output.nil?
-        output = File.join(root, DEFAULT_REPORT_NAME)
-        if File.exist?(output) && !report_writer.rubylens_report?(output)
-          raise Error, "default report path already exists and is not a RubyLens report"
-        end
-        GitRepository.new(root).exclude_local(output)
+      output = @output || DefaultOutput.resolve(root: root, name: DEFAULT_REPORT_NAME, description: "report") do |existing|
+        ArtifactMarker.present?(existing, ReportWriter::MARKER)
       end
       model, warnings = GenerationPipeline.new(root:, lockfile: @lockfile).call
-      output_path = report_writer.write(model, output: output)
+      output_path = ReportWriter.new.write(model, output: output)
 
       RubyLens::Result.new(output_path: output_path, counts: model.fetch("totals").freeze, warnings:)
     rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP => error