llv 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '009573ab40ee86ba88dd8daee97a3035d9a24ab0d923c774c8550313f4a999ff'
+  data.tar.gz: f569e2357a526127d941da5d4b0d5555fd6faca19a97e15a4ecf5bc4de1c73c4
+SHA512:
+  metadata.gz: c5d6f573055cd148fbeb20c1b66e8e82ce040e619a7031255b83804d871fbca26db9486b2b7edb936bb6c55bb41cef7fe87ec5334ec24c976ffa14c196d11a9f
+  data.tar.gz: d0e4c3c993f3cf2662a27b49de67c933f55624f4624ea3bcc7329ad7c8f3ab37e9a530c3408c46dc70ce3cbb23f0ffb6760e773b1fb447672e734d446ece434f

data/README.md

@@ -0,0 +1,130 @@
+# llv
+
+Rails has ~"beautiful"~ trashy noisy unreadable garbage logs that it vomits uselessly into your terminal. We can do better.
+
+Local log viewer for Rails `development.log`. Tails the file, groups lines by request (or background job), and shows them in a master/detail view — browser by default, or a TUI.
+
+This is vide-coded because solving this years-old frustration now only takes 30mins between other work. Feel free to enhance it.
+
+## Setup
+
+In your Rails app, enable tagged-logging with the request id so HTTP lines can be grouped reliably. Edit `config/environments/development.rb`:
+
+```ruby
+config.log_tags = [:request_id]
+```
+
+ActiveJob lines already carry their own tags, no change needed for those.
+
+Install `llv` globally — it's a standalone CLI, not something you bundle into your app. Once published to RubyGems:
+
+```sh
+gem install llv
+```
+
+In the meantime, from a clone of this repo:
+
+```sh
+bundle install && rake install
+```
+
+## Run
+
+Browser UI (default):
+
+```sh
+llv path/to/development.log
+# opens http://127.0.0.1:9292
+```
+
+Terminal UI:
+
+```sh
+llv --tui path/to/development.log
+```
+
+Useful flags:
+
+- `--tail` — only show lines appended after launch. By default `llv` replays the whole file first so you see existing requests too.
+- `--limit N` — keep at most N items in memory (default 500).
+- `--port`, `--host` — change the web server bind.
+- `--no-open` — don't auto-launch the browser.
+
+## TUI keys
+
+I don't use many terminal apps so please contribute enhancements to make it behave more as you'd expect.
+
+The TUI is a two-pane master/detail with one focused pane at a time. Cursor keys and the vi-style `hjkl` both work.
+
+| key                          | when focus is **LIST** (left) | when focus is **DETAIL** (right) |
+|------------------------------|-------------------------------|----------------------------------|
+| `↑` / `k`                    | previous request              | scroll one line up               |
+| `↓` / `j`                    | next request                  | scroll one line down             |
+| `→` / `l` / `enter`          | move focus to DETAIL          | —                                |
+| `←` / `h` / `esc`            | —                             | move focus back to LIST          |
+| `tab`                        | swap focus                    | swap focus                       |
+| `PgUp` / `PgDn` / space      | page through the list         | page through detail              |
+| `Ctrl-U` / `Ctrl-D`          | —                             | half-page up / down              |
+| `g` / `Home`                 | first item                    | scroll to top                    |
+| `G` / `End`                  | last item                     | scroll to bottom                 |
+| `s`                          | toggle SQL `↳` source lines   | toggle SQL `↳` source lines      |
+| `H` / `J` / `C`              | toggle http / jobs / cable    | toggle http / jobs / cable       |
+| `q` / `Ctrl-C`               | quit                          | quit                             |
+
+The header shows which pane has focus (`[LIST]` or `[DETAIL]`) and the divider thickens (`│` → `┃`) when the detail pane is active.
+
+## What you see
+
+- **Left pane** — newest-first list of items. Each item is one HTTP request (with method, path, status, duration), one ActiveJob run, or one ActionCable (`/cable`) connection.
+- **Right pane** — the log lines that belong to the selected item, with the ANSI colours Rails already emits (bold cyan for SQL labels, bold blue for the SQL itself, etc.). SQL source `↳` lines are revealed alongside their query.
+
+## Filtering noise
+
+ActionCable (`/cable`) requests are very chatty in development and are usually not what you're trying to debug. Each kind (`http`, `jobs`, `cable`) has its own independent toggle:
+
+- **Browser**: three buttons in the header — click one to toggle its requests on/off. They're independent, so "HTTP + Jobs but not Cable" is one click on the Cable button.
+- **TUI**: `H` toggles HTTP, `J` toggles Jobs, `C` toggles Cable. The header shows the current state and the total reflects items visible / items captured.
+
+## Layout
+
+```
+lib/llv/
+  ansi.rb         # SGR <-> HTML span
+  parser.rb       # line classifier, stateful for untagged-HTTP grouping
+  group_store.rb  # thread-safe ring buffer, pub/sub
+  tailer.rb       # listen-based file follower, rotation-aware
+  web.rb          # Sinatra + SSE
+  tui.rb          # bubbletea Model + lipgloss layout
+  public/         # vanilla HTML/JS/CSS
+```
+
+## Tests
+
+```sh
+bundle exec rake test
+# or:
+bundle exec ruby -Ilib -Itest test/parser_test.rb
+```
+
+## Releasing to RubyGems
+
+For maintainers. The Rakefile pulls in `bundler/gem_tasks`, which gives you `rake build` and `rake release`.
+
+One-time setup — sign in to RubyGems so credentials land in `~/.gem/credentials`:
+
+```sh
+gem signin
+```
+
+Cutting a new release:
+
+1. Bump `Llv::VERSION` in `lib/llv/version.rb` (`llv.gemspec` reads from there, so it's the single source of truth).
+2. Commit and push the version bump.
+3. `bundle exec rake release` — this builds `pkg/llv-<version>.gem`, tags `v<version>` in git, pushes the tag, then pushes the gem to rubygems.org.
+
+If you want to do it by hand instead:
+
+```sh
+bundle exec rake build           # writes pkg/llv-<version>.gem
+gem push pkg/llv-<version>.gem
+```

data/bin/llv

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/llv"
+
+Llv::CLI.start(ARGV)

data/lib/llv/ansi.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Llv
+  # Translates a small subset of ANSI SGR escape codes (the ones Rails actually
+  # emits in development.log) into either nothing (strip) or HTML spans (to_html).
+  module Ansi
+    SGR = /\e\[([0-9;]*)m/
+
+    FG = {
+      30 => "black", 31 => "red", 32 => "green", 33 => "yellow",
+      34 => "blue", 35 => "magenta", 36 => "cyan", 37 => "white",
+      90 => "bright-black", 91 => "bright-red", 92 => "bright-green",
+      93 => "bright-yellow", 94 => "bright-blue", 95 => "bright-magenta",
+      96 => "bright-cyan", 97 => "bright-white"
+    }.freeze
+
+    BG = {
+      40 => "black", 41 => "red", 42 => "green", 43 => "yellow",
+      44 => "blue", 45 => "magenta", 46 => "cyan", 47 => "white"
+    }.freeze
+
+    module_function
+
+    def strip(str)
+      str.gsub(SGR, "")
+    end
+
+    # Truncate `str` to at most `max_visible` printable characters, ignoring
+    # SGR escape codes for measurement and preserving every SGR encountered up
+    # to the cut so colours don't bleed past the truncation. Adds an ellipsis
+    # and a final reset when the string is shortened.
+    def truncate(str, max_visible)
+      return str if max_visible <= 0
+      return str if strip(str).length <= max_visible
+
+      out = +""
+      visible = 0
+      cut = false
+
+      scan(str) do |segment|
+        case segment
+        in [:sgr, codes]
+          out << "\e[#{codes.join(";")}m"
+        in [:text, text]
+          break if cut
+
+          remaining = max_visible - visible
+          if text.length <= remaining
+            out << text
+            visible += text.length
+          else
+            out << text[0, [remaining - 1, 0].max]
+            out << "…"
+            visible = max_visible
+            cut = true
+          end
+        end
+      end
+
+      out << "\e[0m" if cut
+      out
+    end
+
+    # Turn raw text containing SGR codes into HTML. Adjacent text under the same
+    # state is wrapped in one <span class="..."> per state-change boundary.
+    def to_html(str)
+      out = +""
+      state = { bold: false, italic: false, underline: false, fg: nil, bg: nil }
+      open = false
+
+      scan(str) do |segment|
+        case segment
+        in [:text, text]
+          next if text.empty?
+
+          out << open_span(state) unless open || empty_state?(state)
+          open = true unless empty_state?(state)
+          out << CGI.escape_html(text)
+        in [:sgr, codes]
+          if open
+            out << "</span>"
+            open = false
+          end
+          apply(state, codes)
+        end
+      end
+
+      out << "</span>" if open
+      out
+    end
+
+    # Yields [:text, "..."] and [:sgr, [int, ...]] segments in order.
+    def scan(str)
+      pos = 0
+      str.scan(SGR) do
+        match = Regexp.last_match
+        if match.begin(0) > pos
+          yield [:text, str[pos...match.begin(0)]]
+        end
+        codes = match[1].to_s.split(";").map { |c| c.empty? ? 0 : c.to_i }
+        codes = [0] if codes.empty?
+        yield [:sgr, codes]
+        pos = match.end(0)
+      end
+      yield [:text, str[pos..]] if pos < str.length
+    end
+
+    def apply(state, codes)
+      i = 0
+      while i < codes.length
+        code = codes[i]
+        case code
+        when 0
+          state[:bold] = false
+          state[:italic] = false
+          state[:underline] = false
+          state[:fg] = nil
+          state[:bg] = nil
+        when 1 then state[:bold] = true
+        when 3 then state[:italic] = true
+        when 4 then state[:underline] = true
+        when 22 then state[:bold] = false
+        when 23 then state[:italic] = false
+        when 24 then state[:underline] = false
+        when 30..37, 90..97
+          state[:fg] = FG[code]
+        when 39
+          state[:fg] = nil
+        when 40..47
+          state[:bg] = BG[code]
+        when 49
+          state[:bg] = nil
+        end
+        i += 1
+      end
+    end
+
+    def empty_state?(state)
+      !state[:bold] && !state[:italic] && !state[:underline] && state[:fg].nil? && state[:bg].nil?
+    end
+
+    def open_span(state)
+      classes = []
+      classes << "ansi-bold" if state[:bold]
+      classes << "ansi-italic" if state[:italic]
+      classes << "ansi-underline" if state[:underline]
+      classes << "ansi-fg-#{state[:fg]}" if state[:fg]
+      classes << "ansi-bg-#{state[:bg]}" if state[:bg]
+      %(<span class="#{classes.join(" ")}">)
+    end
+  end
+end

data/lib/llv/cli.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Llv
+  class CLI
+    DEFAULTS = {
+      port: 9292,
+      host: "127.0.0.1",
+      limit: 500,
+      # Replay the whole file by default — when you launch llv you almost
+      # always want to see what's already there. Pass --tail to opt out.
+      from_start: true,
+      tui: false,
+      open_browser: true
+    }.freeze
+
+    def self.start(argv)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+      @options = DEFAULTS.dup
+    end
+
+    def run
+      parse!
+      path = @argv.shift
+      unless path
+        warn "usage: llv [options] PATH/TO/development.log"
+        exit 1
+      end
+
+      store = GroupStore.new(limit: @options[:limit])
+      parser = Parser.new
+      tailer = Tailer.new(path, from_start: @options[:from_start])
+
+      # Tailer#each_line returns immediately after starting the listener +
+      # poll threads, so we don't need an extra wrapper thread.
+      tailer.each_line do |line|
+        event = parser.parse(line)
+        store.ingest(event)
+      end
+
+      @tailer = tailer
+      if @options[:tui]
+        require_relative "tui"
+        install_traps
+        Tui::Program.new(store: store).run
+      else
+        require_relative "web"
+        start_web(store)
+      end
+    ensure
+      @tailer&.stop
+    end
+
+    def install_traps
+      shutdown = lambda do |_signo = nil|
+        $stderr.puts "\nllv: stopping"
+        # Process.exit! is the only way out of Puma's Launcher loop once it has
+        # decided to "gracefully" stop and is blocked on its own threads.
+        Process.exit!(0)
+      end
+      Signal.trap("INT", &shutdown)
+      Signal.trap("TERM", &shutdown)
+    end
+
+    private
+
+    def parse!
+      OptionParser.new do |o|
+        o.banner = "usage: llv [options] PATH/TO/development.log"
+        o.on("--tui", "Use the terminal UI instead of the browser") { @options[:tui] = true }
+        o.on("--tail", "Only show lines appended after launch (default: replay the whole file first)") { @options[:from_start] = false }
+        o.on("--from-start", "Replay the entire log file (this is the default)") { @options[:from_start] = true }
+        o.on("--limit N", Integer, "Max number of items to keep in memory (default: 500)") { |n| @options[:limit] = n }
+        o.on("--port PORT", Integer, "Web server port (default: 9292)") { |p| @options[:port] = p }
+        o.on("--host HOST", "Web server host (default: 127.0.0.1)") { |h| @options[:host] = h }
+        o.on("--no-open", "Don't open the browser automatically") { @options[:open_browser] = false }
+        o.on("-h", "--help", "Show this help") do
+          puts o
+          exit
+        end
+      end.parse!(@argv)
+    end
+
+    def start_web(store)
+      Web.store = store
+      # Disable Sinatra's own INT/TERM traps. We can't stop Puma::Launcher from
+      # installing its handlers, so we run Puma on a background thread and
+      # install our own traps *after* Puma is up — last-trap-wins.
+      Web.set :traps, false
+      url = "http://#{@options[:host]}:#{@options[:port]}/"
+      puts "llv listening on #{url}"
+
+      server_thread = Thread.new do
+        Web.run!(host: @options[:host], port: @options[:port], quiet: true)
+      rescue StandardError => e
+        $stderr.puts "llv web server error: #{e.class}: #{e.message}"
+      end
+
+      # Give Puma a moment to install its launcher signal handlers, then
+      # override them with ours.
+      sleep 0.5
+      install_traps
+
+      if @options[:open_browser]
+        Thread.new do
+          require "launchy"
+          Launchy.open(url)
+        rescue StandardError
+          # the URL is printed above; user can open it manually
+        end
+      end
+
+      server_thread.join
+    end
+  end
+end

data/lib/llv/group_store.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Llv
+  # Thread-safe store of grouped log items. Maintains insertion order
+  # newest-first, evicts oldest beyond `limit`, and publishes events to any
+  # number of subscribers (web SSE, TUI, tests).
+  class GroupStore
+    include MonitorMixin
+
+    Group = Struct.new(
+      :id, :kind, :title, :started_at, :finished_at, :status, :duration_ms, :lines,
+      keyword_init: true
+    ) do
+      def summary
+        {
+          id: id,
+          kind: kind,
+          title: title,
+          started_at: started_at,
+          finished_at: finished_at,
+          status: status,
+          duration_ms: duration_ms,
+          line_count: lines.length
+        }
+      end
+
+      def to_h_full
+        summary.merge(lines: lines.map(&:dup))
+      end
+    end
+
+    Line = Struct.new(:type, :payload, :raw, :plain, :at, keyword_init: true)
+
+    def initialize(limit: 500)
+      super()
+      @limit = limit
+      @by_id = {}
+      @order = []   # newest first
+      @subscribers = []
+      @seq = 0
+    end
+
+    def ingest(event)
+      synchronize do
+        gid = event.group_id || "untagged"
+        new_group = !@by_id.key?(gid)
+        group = @by_id[gid] ||= build_group(gid, event)
+
+        if new_group
+          @order.unshift(gid)
+          enforce_limit
+        end
+
+        update_title(group, event)
+        update_lifecycle(group, event)
+        append_line(group, event)
+
+        broadcast(new_group ? :group_created : :group_updated, group)
+        broadcast(:group_completed, group) if event.type == :request_completed || event.type == :job_performed
+        group
+      end
+    end
+
+    def list(limit: nil, kind: nil)
+      synchronize do
+        ids = @order
+        ids = ids.select { |id| @by_id[id].kind == kind } if kind
+        ids = ids.first(limit) if limit
+        ids.map { |id| @by_id[id].summary }
+      end
+    end
+
+    def fetch(id)
+      synchronize { @by_id[id]&.to_h_full }
+    end
+
+    def subscribe(&block)
+      synchronize { @subscribers << block }
+      block
+    end
+
+    def unsubscribe(handle)
+      synchronize { @subscribers.delete(handle) }
+    end
+
+    def size
+      synchronize { @order.length }
+    end
+
+    private
+
+    def build_group(gid, event)
+      Group.new(
+        id: gid,
+        kind: event.group_kind,
+        title: event.group_title || default_title(event),
+        started_at: Time.now,
+        finished_at: nil,
+        status: nil,
+        duration_ms: nil,
+        lines: []
+      )
+    end
+
+    def default_title(event)
+      case event.group_kind
+      when :http then "HTTP request"
+      when :job then "Job"
+      else "Untagged"
+      end
+    end
+
+    def update_title(group, event)
+      group.title = event.group_title if event.group_title && (group.title.nil? || group.title == default_title(event))
+    end
+
+    def update_lifecycle(group, event)
+      case event.type
+      when :request_started
+        group.started_at = Time.now
+      when :request_completed
+        group.finished_at = Time.now
+        group.status = event.payload[:status]
+        group.duration_ms = event.payload[:duration_ms]
+      when :job_performing
+        group.started_at = Time.now
+      when :job_performed
+        group.finished_at = Time.now
+        group.status = "ok"
+        group.duration_ms = event.payload[:duration_ms]
+      when :job_retry_stopped
+        group.status = "stopped"
+      end
+    end
+
+    def append_line(group, event)
+      group.lines << Line.new(
+        type: event.type,
+        payload: event.payload,
+        raw: event.raw,
+        plain: event.plain,
+        at: (@seq += 1)
+      )
+    end
+
+    def enforce_limit
+      while @order.length > @limit
+        evicted = @order.pop
+        @by_id.delete(evicted)
+        broadcast(:group_evicted, Group.new(id: evicted))
+      end
+    end
+
+    def broadcast(type, group)
+      @subscribers.each do |sub|
+        begin
+          sub.call(type, group)
+        rescue StandardError
+          # don't let one bad subscriber kill ingestion
+        end
+      end
+    end
+  end
+end