booker 1.2.1 → 2.0.0

data/lib/booker/config.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+# configuation - which platform we are on, how to open a link, and where the
+# bookmarks live
+
+require "yaml"
+
+require_relative "output"
+
+using Booker::Colors
+
+module Booker
+  # detect operating system
+  module OS
+    def self.windows? = RUBY_PLATFORM.match?(/cygwin|mswin|mingw|bccwin|wince|emx/)
+
+    def self.mac? = RUBY_PLATFORM.match?(/darwin/)
+
+    def self.linux? = !(windows? || mac?)
+  end
+
+  # return browser (chrome) opening command
+  module Browser
+    def browse
+      if OS.windows?
+        # alternatively, start seems to work - probably check if powershell v cygwin?
+        '/cygdrive/c/Program\ Files\ \(x86\)/Google/Chrome/Application/chrome.exe '
+      elsif OS.mac?
+        "open "
+      else
+        # linux? is defined as "neither of the above", so there is no fourth
+        # branch for #browse to fall out of and return nil from
+        "xdg-open "
+      end
+    end
+
+    # what an explicit scheme looks like. #domain and #prep are two halves of
+    # one grammar - is this a url, does it already say how to fetch it - so both
+    # read the rule from here rather than spelling it out twice and drifting
+    SCHEME = /[a-z][a-z0-9+.-]*:\/\//i
+
+    # does this argument look like a website rather than a search term? an
+    # explicit scheme, or a bare host with a dot and an alphabetic tld. every
+    # tld has to work: completion inserts real bookmark urls, and the old
+    # (io|com|net|org|...) list sent .dev and .ai off to the search engine
+    def domain
+      %r{\A(?:#{SCHEME}\S+|(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}(?::\d+)?(?:[/?#]\S*)?)\z}io
+    end
+
+    # only a bare host needs a scheme invented for it. testing for "http" alone
+    # sent everything else down the same branch, so a completed
+    # chrome://bookmarks/ came out as http://chrome://bookmarks/
+    def prep(url)
+      /\A#{SCHEME}/io.match?(url) ? url : "http://" + url
+    end
+  end
+
+  # configuration
+  class Config
+    VALID = [:searcher, :bookmarks, :browser, :picker].freeze
+    HOME = ENV.fetch("HOME", "/usr/local/").freeze
+    YAMLCONF = (HOME + "/.booker.yml").freeze
+
+    class << self
+      # one instance per run. Bookmarks, Picker and the CLI want the same
+      # answers, and one Config apiece meant parsing the yaml three times,
+      # discovering three times, and warning three times to say it once
+      def default = @default ||= new
+
+      # the memo outlives a single example, so the suite drops it between them
+      def reset! = @default = nil
+    end
+
+    def initialize
+      # the yaml file if there is one, and only work out the defaults when
+      # there is not: discovery walks every chrome profile directory to answer
+      # a question the config file has already answered
+      @config = read(YAMLCONF) || {
+        browser: "open ",
+        searcher: "https://google.com/search?q=",
+        bookmarks: detect_default_bookmarks
+      }
+
+      # prune bad config keys
+      @config.each_key do |k|
+        if !VALID.include? k.to_sym
+          warn "Failure:".red + " Bad key found in config file: #{k}"
+          exit 1
+        end
+      end
+    end
+
+    def detect_default_bookmarks
+      # Return ALL available bookmark sources (Chrome, Firefox, Safari)
+      all_sources = discover_all_bookmark_sources
+
+      # If we found sources, return them all; otherwise return a default single path
+      if all_sources.empty?
+        # Fallback to macOS Chrome default for backward compatibility
+        HOME + "/Library/Application Support/Google/Chrome/Profile 1/Bookmarks"
+      else
+        all_sources
+      end
+    end
+
+    def discover_all_bookmark_sources = Sources.discover
+
+    def read(file)
+      # #write emits symbol keys, so they have to be permitted on the way back
+      YAML.safe_load_file(file, permitted_classes: [Symbol])
+    rescue Errno::ENOENT
+      warn "Warning: ".yel +
+        "YAML configuration file couldn't be found. Using defaults."
+      warn "Suggest: ".grn + "booker --install config"
+      false
+    rescue Psych::Exception
+      # every psych failure means the same thing here - an unusable config to
+      # fall back from rather than crash on. rescuing SyntaxError alone let
+      # anchors through as an AliasesNotEnabled backtrace under psych 4
+      warn "Warning: ".red +
+        "YAML configuration file could not be read. Using defaults."
+      false
+    end
+
+    # used for creating and updating the default configuration
+    def write(k = nil, v = nil)
+      @config[k] = v unless k.nil? # update users yaml config file
+      File.write(YAMLCONF, @config.to_yaml)
+    end
+
+    # always an array, so callers never branch on it: configs written before
+    # multi-source support hold a single path string
+    def bookmarks = Array(@config[:bookmarks])
+
+    def searcher = @config[:searcher]
+
+    # the finder command with its flags, split with Shellwords rather than
+    # handed to a shell. nil means "auto detect fzf", which is why #write leaves
+    # it out of the defaults: #initialize exits on keys it does not know, so a
+    # config naming it is unreadable by a booker predating the key
+    def picker = @config[:picker]
+  end
+
+  # where browsers keep their bookmarks. one implementation, shared by the
+  # auto-detection Config falls back on and by `booker --install bookmarks` -
+  # the installer's job is to show what auto-detection would find, so a second
+  # copy of these paths guarantees it eventually shows something else. nothing
+  # here tags a source: Bookmarks.source_for reads that off the filename
+  module Sources
+    CHROME = [
+      "/Library/Application Support/Google/Chrome",      # macOS
+      "/Library/Application Support/Chromium",           # macOS Chromium
+      "/.config/google-chrome",                          # Linux
+      "/.config/chromium",                               # Linux Chromium
+      "/snap/chromium/common/chromium",                  # Linux (snap)
+      "/snap/chromium/current/.config/chromium",         # Linux (snap alt)
+      "/AppData/Local/Google/Chrome/User Data"           # Windows
+    ].freeze
+
+    FIREFOX = [
+      "/.mozilla/firefox",                               # Linux
+      "/snap/firefox/common/.mozilla/firefox",           # Linux (snap)
+      "/Library/Application Support/Firefox",            # macOS
+      "/AppData/Roaming/Mozilla/Firefox"                 # Windows
+    ].freeze
+
+    SAFARI = "/Library/Safari/Bookmarks.plist"
+
+    class << self
+      def discover = (chrome + firefox + safari).uniq
+
+      # every places.sqlite named by a profiles.ini. any Path= counts, and the
+      # [Install...] block firefox also writes names a profile already listed,
+      # hence the uniq
+      def profiles(ini_path, base)
+        File.readlines(ini_path).filter_map do |line|
+          key, value = line.strip.split("=", 2)
+          next unless key == "Path" && value
+
+          db = File.join(base, value.strip, "places.sqlite")
+          db if File.exist?(db)
+        end.uniq
+      end
+
+      private
+
+      def chrome
+        expand(CHROME).flat_map do |base|
+          # one level down, not "**": chrome puts Bookmarks directly inside a
+          # profile directory, and the rest of the tree is Cache and Service
+          # Worker storage - tens of thousands of files to walk for nothing. the
+          # second pattern covers a base that already names a profile. globbing
+          # relative to base keeps a metacharacter in the path itself - a
+          # profile named "Chrome [work]", say - out of the pattern
+          Dir.glob(["Bookmarks", "*/Bookmarks"], base: base)
+            .map { |relative| File.join(base, relative) }
+            .select { |file| File.file?(file) }
+        rescue
+          # Skip if we can't read this directory
+          []
+        end
+      end
+
+      def firefox
+        expand(FIREFOX).flat_map do |base|
+          ini = File.join(base, "profiles.ini")
+          File.exist?(ini) ? profiles(ini, base) : []
+        end
+      end
+
+      def safari
+        path = Config::HOME + SAFARI
+        File.exist?(path) ? [path] : []
+      end
+
+      def expand(bases) = bases.map { |b| Config::HOME + b }.select { |b| Dir.exist?(b) }
+    end
+  end
+end

data/lib/booker/installer.rb

@@ -0,0 +1,396 @@
+# frozen_string_literal: true
+
+# everything behind `booker --install`: shell completion, the config file,
+# finding browser bookmarks, and the opt-in safari permission walkthrough
+
+require "fileutils"
+require "open3"
+
+require_relative "output"
+
+using Booker::Colors
+
+module Booker
+  class Installer
+    include Output
+
+    # shells we ship completion for, and where those scripts live
+    SHELLS = %w[zsh bash fish].freeze
+
+    # what ~/.zshrc needs for a script in ~/.zsh/completion to be found
+    ZSHRC_LINES = [
+      "fpath=(~/.zsh/completion $fpath)",
+      "autoload -Uz compinit && compinit"
+    ].freeze
+    COMPLETIONS_DIR = File.expand_path("../../completions", __dir__).freeze
+
+    # if any of these exist, bash-completion is installed and will autoload our
+    # script out of the XDG user directory
+    BASH_COMPLETION_MARKERS = [
+      "/usr/share/bash-completion/bash_completion",
+      "/etc/bash_completion",
+      "/usr/local/etc/profile.d/bash_completion.sh",
+      "/opt/homebrew/etc/profile.d/bash_completion.sh"
+    ].freeze
+
+    # 'all' expands to the full install list (including opt-in safari)
+    ALL = %w[completion config bookmarks safari].freeze
+
+    def install(args)
+      args.flat_map { |target| /^all$/i.match?(target) ? ALL : target }
+        .each { |target| install_one(target) }
+    end
+
+    def install_one(target)
+      if /comp/i.match?(target) # completion for every shell on this machine
+        install_completion
+      elsif (shell = SHELLS.find { |s| target.downcase.include?(s) })
+        install_completion_for(shell) # completion for one named shell
+      elsif /book/i.match?(target) # bookmarks installation
+        install_bookmarks
+      elsif /conf/i.match?(target) # default config file generation
+        install_config
+      elsif /safari/i.match?(target) # opt-in Safari FDA setup (macOS only)
+        install_safari
+      else # unknown argument passed into install
+        pexit "Failure: ".red + "unknown installation option (#{target})"
+      end
+    end
+
+    # install completion for every supported shell present on this machine, so a
+    # zsh user who also drops into bash gets both without running install twice
+    def install_completion
+      found, missing = SHELLS.partition { |shell| shell_present?(shell) }
+
+      if found.empty?
+        puts "Warning: ".yel + "no supported shell found (#{SHELLS.join(", ")})"
+        return
+      end
+
+      found.each { |shell| install_completion_for(shell) }
+
+      puts "Skip: ".yel + "#{missing.join(", ")} not installed" unless missing.empty?
+    end
+
+    # every shell in SHELLS has an install_completion_<shell>, so adding a fourth
+    # means adding the script, the method, and the SHELLS entry - nothing here
+    def install_completion_for(shell)
+      send("install_completion_#{shell}")
+    end
+
+    def install_completion_zsh
+      # check if zsh is even installed for this user - capture3 raises
+      # Errno::ENOENT when it is not, same as the backtick this replaces
+      begin
+        out, _err, _status = Open3.capture3("zsh", "-c", "echo $fpath")
+        fpath = out.split(" ")
+      rescue
+        pexit "Failure: ".red + "zsh is probably not installed, could not find $fpath"
+      end
+
+      # Try user-writable directories first, then system directories
+      user_home = home
+      writable_dirs = fpath.select do |fp|
+        fp.start_with?(user_home) && File.directory?(fp) && File.writable?(fp)
+      end
+
+      # If no user-writable directories, try to create one
+      if writable_dirs.empty?
+        user_completion_dir = File.join(user_home, ".zsh", "completion")
+        begin
+          # mkdir_p is happy either way, but saying "Created" every time a
+          # developer reinstalls is a small lie about what just happened
+          existed = File.directory?(user_completion_dir)
+          FileUtils.mkdir_p(user_completion_dir)
+          writable_dirs << user_completion_dir
+          puts "Created user completion directory: #{user_completion_dir}".yel unless existed
+
+          # Auto-configure .zshrc if it exists
+          zshrc = File.join(user_home, ".zshrc")
+          if File.exist?(zshrc)
+            # the marker is the directory, not the whole block: a zshrc that
+            # already puts it on $fpath is configured, however it spelled the
+            # compinit call next to it
+            append_once(zshrc, ZSHRC_LINES, marker: ".zsh/completion", label: "~/.zshrc") do
+              puts "Run: ".yel + "source ~/.zshrc".cyan + " to activate"
+            end
+          else
+            puts "Add this to your ~/.zshrc: ".yel + "fpath=(~/.zsh/completion $fpath)".cyan
+          end
+        rescue
+          # Couldn't create user dir, try system dirs as fallback
+        end
+      end
+
+      # Try writable directories first, then all directories as fallback
+      dirs_to_try = writable_dirs + fpath.reject { |fp| writable_dirs.include?(fp) }
+
+      success = false
+      dirs_to_try.each do |fp|
+        next unless File.directory?(fp)
+
+        begin
+          # nothing is autoloaded here on purpose: `zsh -c 'autoload -U
+          # _booker'` loaded it into a subshell that exited on the next line.
+          # clear_zsh_compdump below is what reaches a new shell
+          File.write(File.join(fp, "_booker"), completion_script("_booker"))
+          puts "Success: ".grn + "installed zsh autocompletion in #{fp}"
+          success = true
+          break
+        rescue
+          # Try next directory silently
+        end
+      end
+
+      if success
+        clear_zsh_compdump
+      else
+        puts "Warning: ".yel + "Could not install ZSH completion to any directory in $fpath"
+        puts "Try manually: ".grn + "mkdir -p ~/.zsh/completion && booker --install zsh"
+      end
+    end
+
+    # compinit caches what it found in $fpath, so a shell started against an old
+    # dump keeps describing the completion booker just replaced. dropping the
+    # cache - zsh rebuilds it on the next start - is how a new script reaches
+    # the next shell. nothing helps the shell you ran this from, which autoloaded
+    # _booker for the life of the session, hence the unfunction advice
+    def clear_zsh_compdump
+      base = ENV["ZDOTDIR"] || home
+      dumps = Dir.glob(File.join(base, ".zcompdump*"))
+      return if dumps.empty?
+
+      dumps.each do |dump|
+        File.delete(dump)
+      rescue
+        # a dump we cannot remove is not worth failing an install over
+      end
+
+      puts "Refreshed: ".grn + "zsh completion cache (rebuilds on next shell)"
+    end
+
+    # bash-completion (when installed) autoloads from the XDG user directory.
+    # Without it there is nothing doing the loading, so fall back to a plain
+    # directory plus a source line in ~/.bashrc.
+    def install_completion_bash
+      autoloaded = bash_completion_present?
+      dir = if autoloaded
+        File.join(xdg_data_home, "bash-completion", "completions")
+      else
+        File.join(home, ".bash_completion.d")
+      end
+
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, "booker"), completion_script("booker.bash"))
+      puts "Success: ".grn + "installed bash completion in #{dir}"
+
+      # with bash-completion installed there is nothing left to wire up
+      unless autoloaded
+        append_once(
+          File.join(home, ".bashrc"),
+          "[ -f ~/.bash_completion.d/booker ] && . ~/.bash_completion.d/booker"
+        )
+      end
+
+      puts "Run: ".yel + "source ~/.bashrc".cyan + " to activate"
+    rescue => e
+      puts "Warning: ".yel + "could not install bash completion (#{e.message})"
+    end
+
+    # fish autoloads anything in its completions directory, so there is no rc
+    # file to edit here
+    def install_completion_fish
+      dir = File.join(xdg_config_home, "fish", "completions")
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, "booker.fish"), completion_script("booker.fish"))
+      puts "Success: ".grn + "installed fish completion in #{dir}"
+      puts "Run: ".yel + "exec fish".cyan + " to activate"
+    rescue => e
+      puts "Warning: ".yel + "could not install fish completion (#{e.message})"
+    end
+
+    # read one of the shipped completion scripts (completions/ sits next to lib/,
+    # and is listed in the gemspec so it ships with the gem)
+    def completion_script(name)
+      File.read(File.join(COMPLETIONS_DIR, name))
+    rescue Errno::ENOENT
+      pexit "Failure: ".red + "completion script #{name} missing from #{COMPLETIONS_DIR}"
+    end
+
+    # Picker.which, not `sh -c "command -v"`: a fork per shell to answer a PATH
+    # question booker already knows how to answer in process
+    def shell_present?(shell) = !Picker.which(shell).nil?
+
+    def bash_completion_present?
+      BASH_COMPLETION_MARKERS.any? { |marker| File.exist?(marker) }
+    end
+
+    # append to an rc file once - install is expected to be re-runnable without
+    # stacking up duplicates. `marker` is what counts as "already there" when
+    # that is narrower than what gets written; `label` is the name shown
+    def append_once(rcfile, lines, marker: lines, label: rcfile)
+      if File.exist?(rcfile) && File.read(rcfile).include?(marker)
+        puts "#{label} already configured".grn
+        return
+      end
+
+      File.open(rcfile, "a") do |f|
+        f.puts "\n# Booker completion"
+        f.puts lines
+      end
+      puts "Added completion to #{label}".grn
+      yield if block_given?
+    end
+
+    def home
+      ENV["HOME"] || "/usr/local"
+    end
+
+    def xdg_data_home
+      ENV["XDG_DATA_HOME"] || File.join(home, ".local", "share")
+    end
+
+    def xdg_config_home
+      ENV["XDG_CONFIG_HOME"] || File.join(home, ".config")
+    end
+
+    # locate bookmarks files, show the user, write the choice to the config.
+    # the search is Sources.discover, the same code auto-detection falls back
+    # on, so this offers exactly what booker would find on its own
+    def install_bookmarks
+      puts "searching for browser bookmarks..."
+      begin
+        bms = Sources.discover
+
+        if bms.empty? # no bookmarks found
+          puts "Failure: ".red + "bookmarks file could not be found."
+          raise
+        elsif bms.length == 1
+          # Auto-select if only one source found
+          selected = bms.first
+          puts "Found bookmark source: #{bookmark_type_label(Bookmarks.source_for(selected))} #{selected}".yel
+          save_bookmarks(selected, "config file updated with your bookmarks")
+        else # have user select a file
+          puts "select bookmarks source: "
+
+          # Offer "ALL" as first option if multiple sources found
+          puts "0".grn + " - " + "[ALL SOURCES]".cyan + " (search across all browsers)"
+
+          bms.each_with_index do |path, i|
+            label = bookmark_type_label(Bookmarks.source_for(path), color: true)
+            puts (i + 1).to_s.grn + " - " + label + " " + path
+          end
+
+          input = gets
+          raise "No input provided" if input.nil?
+          selection = input.chomp.to_i
+
+          if selection == 0
+            # User selected "ALL" - save array of all paths
+            puts "Selected: ".yel + "All sources (#{bms.length} bookmark files)"
+            Config.default.write(:bookmarks, bms)
+            puts "Success: ".grn + "config file updated to search all bookmark sources"
+          else
+            save_bookmarks(bms[selection - 1], "config file updated with your bookmarks")
+          end
+        end
+      rescue => e
+        puts e.message
+        pexit "Failure: ".red + "could not add bookmarks to config file ~/.booker"
+      end
+    end
+
+    def save_bookmarks(selected, message)
+      puts "Selected: ".yel + selected
+      Config.default.write(:bookmarks, selected)
+      puts "Success: ".grn + message
+    end
+
+    # the label and its color come off the browser table, so a fourth browser
+    # is a row there rather than two more branches here
+    def bookmark_type_label(type, color: false)
+      browser = Bookmarks::BROWSERS[type]
+      return "[?]" if browser.nil?
+
+      color ? Colors.paint(browser[:label], browser[:color]) : browser[:label]
+    end
+
+    def install_config
+      Config.default.write
+      puts "Success: ".grn + "example config file written to ~/.booker"
+    rescue
+      pexit "Failure: ".red + "could not write example config file to ~/.booker"
+    end
+
+    # Opt-in Safari setup: walks through granting Full Disk Access so booker
+    # can read ~/Library/Safari/Bookmarks.plist. Not included in the default
+    # --install flow because it requires a TCC permission grant.
+    def install_safari
+      plist = File.join(home, "Library/Safari/Bookmarks.plist")
+      fda_url = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"
+
+      unless RUBY_PLATFORM.include?("darwin")
+        puts "Skip: ".yel + "Safari support is macOS-only."
+        return
+      end
+
+      unless File.exist?(plist)
+        puts "Skip: ".yel + "Safari bookmarks not found at #{plist}"
+        puts "Hint: ".grn + "launch Safari at least once, then re-run."
+        return
+      end
+
+      if safari_readable?(plist)
+        puts "PASS: ".grn + "Safari bookmarks are already readable."
+        return
+      end
+
+      puts "Safari stores bookmarks at:"
+      puts "  #{plist}".cyan
+      puts
+      puts "That file is protected by macOS TCC. Grant Full Disk Access to one of:"
+      puts
+      puts "  [A] ".cyan + "Your terminal app".yel + " (simplest; inherited by any tool)"
+      puts "  [B] ".cyan + "/usr/bin/plutil only".yel + " (narrower scope)"
+      puts
+      print "Pick [A] or [B] (default A): "
+      $stdout.flush
+      choice = $stdin.gets.to_s.strip.upcase
+      choice = "A" if choice.empty?
+      pexit "Error: ".red + "invalid choice." unless %w[A B].include?(choice)
+
+      puts
+      puts "Opening the Full Disk Access pane..."
+      system("open", fda_url)
+      puts
+
+      puts "In the pane that just opened:"
+      if choice == "A"
+        puts "  1. Click ".yel + "+".cyan + ", add your terminal app from /Applications"
+        puts "  2. Toggle it ".yel + "on".cyan
+        puts "  3. ".yel + "Fully quit".cyan + " the terminal (Cmd+Q), reopen it,"
+        puts "     and re-run ".yel + "booker --install safari".cyan + " to verify."
+      else
+        puts "  1. Click ".yel + "+".cyan
+        puts "  2. Press ".yel + "Cmd+Shift+G".cyan + " (opens 'Go to Folder')".yel
+        puts "  3. Type ".yel + "/usr/bin/plutil".cyan + " and press Return".yel
+        puts "  4. Click ".yel + "Open".cyan + ", then toggle it ".yel + "on".cyan
+        puts
+        print "Press Return once you've added plutil and toggled it on... "
+        $stdout.flush
+        $stdin.gets
+
+        if safari_readable?(plist)
+          puts "PASS: ".grn + "Safari bookmarks are now readable."
+        else
+          puts "FAIL: ".red + "still can't read the bookmarks file."
+          puts "Try fully quitting the terminal (Cmd+Q) and re-running."
+        end
+      end
+    end
+
+    def safari_readable?(plist)
+      system("plutil", "-lint", "-s", plist, out: File::NULL, err: File::NULL)
+    end
+  end
+end

data/lib/booker/output.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# terminal width, colored strings, and exiting with a message: the presentation
+# helpers the rest of booker leans on
+
+require "io/console"
+
+module Booker
+  # int number of columns on screen, answered in process rather than by a `tput
+  # cols` subshell on every run. io/console reads /dev/tty rather than stdout,
+  # so a width still comes back through a pipe, and nil when there is no
+  # terminal at all - a completion subshell, or ci
+  module Term
+    def self.width
+      @width ||= IO.console&.winsize&.last&.nonzero? ||
+        ENV["COLUMNS"]&.to_i&.nonzero? ||
+        100
+    end
+  end
+
+  # compl. color codes space
+  CODEWIDTH = 16
+
+  # print a message and stop, for the cli and the installer both reporting a
+  # failure and exiting in one breath. stderr, not stdout: stdout is the data
+  # channel the completion scripts read
+  module Output
+    def pexit(msg, sig = 1)
+      warn msg
+      exit sig
+    end
+  end
+
+  # "Success: ".grn at every call site, but as a refinement rather than an open
+  # class: a gem claiming String#red for the whole process is taking a name it
+  # does not own. files that want these say `using Booker::Colors` at the top
+  module Colors
+    CODES = {red: 31, grn: 32, yel: 33, blu: 34, cyan: 36}.freeze
+
+    class << self
+      # nil means decide per call from the environment; true or false forces it,
+      # which is what the specs do since their $stdout is never a terminal
+      attr_writer :enabled
+
+      # honor NO_COLOR (no-color.org), and skip the escapes when stdout is not a
+      # terminal - otherwise `booker > out.txt` and `booker | less` fill up with
+      # raw \033[ sequences
+      def enabled?
+        return @enabled unless @enabled.nil?
+
+        ENV["NO_COLOR"].to_s.empty? && $stdout.tty?
+      end
+
+      # color by name, reachable without the refinement. a caller holding the
+      # color as data - the browser table's :yel, say - cannot go through the
+      # refined methods, because refinements are invisible to send
+      def paint(str, name)
+        return str unless enabled?
+
+        "\033[0;#{CODES.fetch(name)};49m#{str}\033[0;0m"
+      end
+    end
+
+    refine String do
+      def window(width)
+        if length >= width
+          self[0..width - 1]
+        else
+          ljust(width)
+        end
+      end
+
+      def blu = Colors.paint(self, :blu)
+
+      def cyan = Colors.paint(self, :cyan)
+
+      def yel = Colors.paint(self, :yel)
+
+      def grn = Colors.paint(self, :grn)
+
+      def red = Colors.paint(self, :red)
+    end
+  end
+end