oops-cli 0.1.0

data/lib/oops/cli.rb

@@ -0,0 +1,186 @@
+require "optparse"
+
+module Oops
+  module CLI
+    # Raised for a usage error; the message is printed after "oops: " and the
+    # exit code is 2.
+    class UsageError < StandardError; end
+
+    # Raised when the command cannot do its job; exit code 1.
+    class Failure < StandardError; end
+
+    NO_CLIPBOARD = "no clipboard tool found (tried pbcopy, wl-copy, xclip, xsel, clip.exe, OSC 52).".freeze
+    POSITIVE_INTEGER = /\A\d+\z/
+
+    def self.run(argv, env: ENV, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      case argv.first
+      when "record" then return record(argv.drop(1), env: env, stdin: stdin, stdout: stdout, stderr: stderr)
+      when "init" then return init(argv.drop(1), stdout: stdout, stderr: stderr)
+      when "doctor" then return doctor(argv.drop(1), env: env, stdin: stdin, stdout: stdout)
+      when "pause", "resume" then return toggle(argv.first, argv.drop(1), env: env, stdout: stdout)
+      end
+
+      options = { head: nil, tail: nil, github: false, show_secrets: false }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: oops [N | err] [options]\n       oops init <shell> | pause | resume | doctor"
+        o.on("--github", "Format for a GitHub issue or PR comment") { options[:github] = true }
+        o.on("--tail N", "Keep only the last N output lines") { |v| options[:tail] = positive(v, "--tail") }
+        o.on("--head N", "Keep only the first N output lines") { |v| options[:head] = positive(v, "--head") }
+        o.on("--show-secrets", "Do not mask secrets or apply the replace table") { options[:show_secrets] = true }
+        o.on("-v", "--version", "Print version and exit") do
+          stdout.puts "oops #{VERSION}"
+          return 0
+        end
+        o.on("-h", "--help", "Print this help and exit") do
+          stdout.puts o
+          return 0
+        end
+      end
+      copy(target(parser.parse(argv)), options, env: env, stdout: stdout, stderr: stderr)
+    rescue OptionParser::ParseError, UsageError => e
+      stderr.puts "oops: #{e.message}"
+      2
+    rescue Failure => e
+      stderr.puts "oops: #{e.message}"
+      1
+    end
+
+    def self.positive(value, name)
+      raise UsageError, "#{name} must be a positive integer" unless value.match?(POSITIVE_INTEGER) && value.to_i >= 1
+
+      value.to_i
+    end
+
+    # Positional arguments: none (the last command), N (the last N commands)
+    # or "err" (the last failed command). Returns 1, N or :err.
+    def self.target(args)
+      raise UsageError, "unexpected argument: #{args[1]}" if args.size > 1
+
+      arg = args.first
+      return 1 if arg.nil?
+      return :err if arg == "err"
+      return positive(arg, "N") if arg.match?(/\A[+-]?\d/)
+
+      raise UsageError, "unknown command: #{arg}"
+    end
+
+    def self.copy(target, options, env:, stdout:, stderr:)
+      log = recording_log(env)
+      raise Failure, "recording is paused. Run  oops resume  first." if log.paused?
+
+      config = Config.load(env: env)
+      config.warnings.each { |w| stderr.puts "oops: warning: #{w}" }
+      records = target == :err ? [log.last_failed].compact : log.last(target)
+      raise Failure, (target == :err ? "no failed command found." : "no command found yet.") if records.empty?
+
+      home = env["HOME"].to_s.empty? ? Dir.home : env["HOME"]
+      result = Formatter.new(config: config, home: home, **options).format(records)
+      backend = Clipboard.detect(config.clipboard, env: env)
+      raise Failure, NO_CLIPBOARD if backend.nil?
+
+      begin
+        backend.copy(result.text)
+      rescue Clipboard::Error => e
+        raise Failure, e.message
+      end
+      stdout.puts "copied: $ #{report_command(result.command_line)} (#{report_counts(result)})"
+      0
+    end
+
+    def self.report_command(command_line)
+      first, rest = command_line.to_s.split("\n", 2)
+      rest ? "#{first} ..." : first.to_s
+    end
+
+    def self.report_counts(result)
+      counts = "#{result.lines} lines"
+      result.masked_count.positive? ? "#{counts}, #{result.masked_count} secrets masked" : counts
+    end
+
+    # The session log of the recorder this shell runs under. Raises Failure
+    # when there is none.
+    def self.recording_log(env)
+      path = env["OOPS_SESSION"].to_s
+      return SessionLog.new(path) if !path.empty? && File.file?(path)
+
+      shell, rc = env["SHELL"].to_s.end_with?("bash") ? %w[bash ~/.bashrc] : %w[zsh ~/.zshrc]
+      raise Failure, "not recording in this shell. Add  eval \"$(oops init #{shell})\"  " \
+                     "to #{rc} (after whatever puts oops's Ruby on PATH, as early as possible) " \
+                     "and open a new tab."
+    end
+
+    # `oops pause` / `oops resume`: the marker goes through the pty to the
+    # recorder; the flag file tells `oops` (and `doctor`) the state. The
+    # recorder only obeys a marker that agrees with the flag file, so the
+    # file changes first.
+    def self.toggle(name, args, env:, stdout:)
+      raise UsageError, "usage: oops #{name}" unless args.empty?
+
+      log = recording_log(env)
+      if name == "pause"
+        log.pause!
+        write_marker(Marker.pause, env: env, stdout: stdout)
+      else
+        log.resume!
+        write_marker(Marker.resume, env: env, stdout: stdout)
+      end
+      0
+    end
+
+    # Like the shell hooks, write straight to the recorded terminal: with
+    # stdout redirected (`oops pause >/dev/null`) the recorder would never see
+    # the marker although the flag file already says "paused". Without a
+    # terminal that can be opened, stdout is used.
+    def self.write_marker(marker, env:, stdout:)
+      tty = env["OOPS_TTY"].to_s
+      unless tty.empty?
+        begin
+          return File.open(tty, File::WRONLY | File::NOCTTY) { |io| io.write(marker) }
+        rescue SystemCallError, IOError
+          nil
+        end
+      end
+      stdout.write marker
+      stdout.flush
+    end
+
+    # `oops doctor`: diagnostics on stdout; always exits 0.
+    def self.doctor(args, env:, stdin:, stdout:)
+      raise UsageError, "usage: oops doctor" unless args.empty?
+
+      config = Config.load(env: env)
+      tty = Tty.name(stdin)
+      stdout.write Doctor.report(env: env, config: config, sessions_dir: Paths.sessions_dir(env: env), tty: tty)
+      0
+    rescue StandardError => e
+      raise if e.is_a?(UsageError)
+
+      stdout.puts "doctor: #{e.message}"
+      0
+    end
+
+    # `oops record [--] <shell> [args...]`
+    def self.record(args, env:, stdin:, stdout:, stderr:)
+      args = args.drop(1) if args.first == "--"
+      Recorder.new(args, env: env, stdin: stdin, stdout: stdout, stderr: stderr).run
+    end
+
+    # `oops init zsh|bash`: prints the snippet for `eval "$(oops init zsh)"`.
+    def self.init(args, stdout:, stderr:)
+      supported = ShellInit::SHELLS.join(", ")
+      if args.size != 1
+        stderr.puts "oops: usage: oops init <shell> (supported: #{supported})"
+        return 2
+      end
+      unless ShellInit::SHELLS.include?(args.first)
+        stderr.puts "oops: unsupported shell: #{args.first} (supported: #{supported})"
+        return 2
+      end
+      stdout.write ShellInit.snippet(args.first, bin: File.expand_path($PROGRAM_NAME))
+      0
+    end
+
+    private_class_method :positive, :target, :copy, :report_command, :report_counts, :recording_log, :toggle,
+                         :write_marker, :doctor
+  end
+end

data/lib/oops/clipboard.rb

@@ -0,0 +1,218 @@
+require "tempfile"
+
+module Oops
+  # Clipboard backends and detection of the best one for this environment.
+  module Clipboard
+    class Error < StandardError; end
+
+    # Seconds to wait for a clipboard command before giving up.
+    TIMEOUT = 5
+    # The wait polls for the command's exit: it starts with short sleeps (the
+    # command usually finishes within a few milliseconds) and doubles up to
+    # POLL_MAX.
+    POLL_MIN = 0.001
+    POLL_MAX = 0.01
+    # Bytes of a failing command's stderr kept in the error message.
+    MAX_STDERR = 2048
+
+    # Shared process handling: text goes in through a temp file on stdin and
+    # output goes to temp files, so a daemonized child (xclip, wl-copy) that
+    # keeps inheriting those descriptors can never block us. We only wait for
+    # the direct child; on a timeout its whole process group is killed.
+    module Runner
+      module_function
+
+      def run(label, argv, text, timeout: TIMEOUT)
+        Tempfile.create("oops-in", binmode: true) do |input|
+          Tempfile.create("oops-err", binmode: true) do |err|
+            input.write(text)
+            input.flush
+            input.rewind
+            status = spawn_and_wait(label, argv, input, err, timeout)
+            next if status.success?
+
+            raise Error, "#{label} failed (#{describe(status)}): #{read_head(err)}"
+          end
+        end
+      rescue SystemCallError, IOError => e
+        raise Error, "#{label}: #{e.message}"
+      end
+
+      def spawn_and_wait(label, argv, input, err, timeout)
+        pid = Process.spawn(*argv, in: input, out: File::NULL, err: err, pgroup: true)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        delay = POLL_MIN
+        loop do
+          _, status = Process.wait2(pid, Process::WNOHANG)
+          return status if status
+
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+            kill_group(pid)
+            raise Error, "#{label} timed out after #{timeout}s"
+          end
+          sleep delay
+          delay = [delay * 2, POLL_MAX].min
+        end
+      end
+
+      # The child leads its own process group, so this also ends anything it
+      # started that is still running.
+      def kill_group(pid)
+        begin
+          Process.kill("KILL", -pid)
+        rescue SystemCallError
+          Process.kill("KILL", pid)
+        end
+        Process.wait(pid)
+      rescue SystemCallError
+        nil
+      end
+
+      def describe(status)
+        return "exit #{status.exitstatus}" if status.exited?
+        return "killed by SIG#{Signal.signame(status.termsig)}" if status.signaled?
+
+        status.to_s
+      end
+
+      def read_head(file)
+        file.rewind
+        head = file.read(MAX_STDERR + 1).to_s
+        more = head.bytesize > MAX_STDERR
+        text = head.byteslice(0, MAX_STDERR).force_encoding(Encoding::UTF_8).scrub.strip
+        more ? "#{text} ..." : text
+      end
+    end
+
+    # Runs an argv with the text on stdin.
+    class Command
+      attr_reader :name
+
+      def initialize(name, argv, encoding: nil)
+        @name = name
+        @argv = argv
+        @encoding = encoding
+      end
+
+      def copy(text)
+        text = text.dup.force_encoding(Encoding::UTF_8).scrub.encode(@encoding) if @encoding
+        Runner.run(@name, @argv, text)
+      end
+    end
+
+    # Runs a user supplied command line through sh -c.
+    class Shell
+      attr_reader :name
+
+      def initialize(cmdline)
+        @cmdline = cmdline
+        @name = cmdline.to_s.split.first || cmdline.to_s
+      end
+
+      def copy(text)
+        Runner.run(@name, ["sh", "-c", @cmdline], text)
+      end
+    end
+
+    # Writes an OSC 52 escape sequence to the terminal.
+    class Osc52
+      WARNING = "oops: warning: clipboard text truncated to fit OSC 52 limit".freeze
+
+      def initialize(tty: "/dev/tty", max_bytes: 100_000)
+        @tty = tty
+        @max_bytes = max_bytes
+      end
+
+      def name = "osc52"
+
+      def copy(text)
+        payload = [fit(text.b)].pack("m0")
+        write("\e]52;c;#{payload}\a")
+      end
+
+      private
+
+      # Keeps the tail of the bytes so the base64 form fits max_bytes, never
+      # starting in the middle of a UTF-8 character.
+      def fit(bytes)
+        limit = @max_bytes / 4 * 3
+        return bytes if bytes.bytesize <= limit
+
+        warn WARNING
+        start = bytes.bytesize - limit
+        start += 1 while start < bytes.bytesize && (bytes.getbyte(start) & 0xC0) == 0x80
+        bytes.byteslice(start..)
+      end
+
+      # One write(2) where possible, so the sequence is not split up between
+      # other output.
+      def write(data)
+        if @tty.respond_to?(:syswrite)
+          write_all(@tty, data)
+        else
+          File.open(@tty, "wb") { |f| write_all(f, data) }
+        end
+      rescue SystemCallError, IOError => e
+        raise Error, "osc52: cannot write to #{@tty.respond_to?(:syswrite) ? 'tty' : @tty}: #{e.message}"
+      end
+
+      def write_all(io, data)
+        data = data.b
+        until data.empty?
+          written = io.syswrite(data)
+          data = data.byteslice(written..)
+        end
+      end
+    end
+
+    KNOWN = {
+      "pbcopy" => ["pbcopy"],
+      "wl-copy" => ["wl-copy"],
+      "xclip" => ["xclip", "-selection", "clipboard"],
+      "xsel" => ["xsel", "--clipboard", "--input"],
+      "clip.exe" => ["clip.exe"]
+    }.freeze
+
+    DEFAULT_WHICH = ->(cmd) { system("command -v #{cmd} >/dev/null 2>&1") }
+
+    module_function
+
+    def command_backend(name)
+      Command.new(name, KNOWN.fetch(name), encoding: (name == "clip.exe" ? "UTF-16LE" : nil))
+    end
+
+    def detect(setting, env: ENV, which: DEFAULT_WHICH, platform: RUBY_PLATFORM, proc_version: nil)
+      setting = setting.to_s.strip
+      setting = "auto" if setting.empty? || %w[true false].include?(setting)
+      return explicit(setting) unless setting == "auto"
+
+      auto(env, which, platform, proc_version)
+    end
+
+    def explicit(setting)
+      return Osc52.new if setting == "osc52"
+      return command_backend(setting) if KNOWN.key?(setting)
+
+      Shell.new(setting)
+    end
+
+    def auto(env, which, platform, proc_version)
+      return Osc52.new unless env["SSH_TTY"].to_s.empty?
+      return command_backend("pbcopy") if platform.include?("darwin") && which.call("pbcopy")
+      return command_backend("clip.exe") if wsl?(proc_version) && which.call("clip.exe")
+      return command_backend("wl-copy") if !env["WAYLAND_DISPLAY"].to_s.empty? && which.call("wl-copy")
+
+      unless env["DISPLAY"].to_s.empty?
+        %w[xclip xsel].each { |n| return command_backend(n) if which.call(n) }
+      end
+      Osc52.new
+    end
+
+    def wsl?(proc_version)
+      proc_version ||= File.exist?("/proc/version") ? File.read("/proc/version") : ""
+      proc_version.match?(/microsoft/i)
+    rescue SystemCallError, IOError
+      false
+    end
+  end
+end

data/lib/oops/config.rb

@@ -0,0 +1,72 @@
+require_relative "paths"
+
+module Oops
+  # User configuration loaded from a YAML file; problems become warnings.
+  class Config
+    KNOWN_KEYS = %w[replace secrets clipboard].freeze
+
+    attr_reader :replace, :secrets, :clipboard, :warnings
+
+    def self.load(path = nil, env: ENV)
+      new(path || Paths.config_file(env: env))
+    end
+
+    def initialize(path)
+      @replace = {}
+      @secrets = []
+      @clipboard = "auto"
+      @warnings = []
+      read(path)
+    end
+
+    private
+
+    def read(path)
+      return unless File.file?(path)
+
+      # Loaded here, not at the top: most runs have no config file, and the
+      # library takes about 5 ms to load.
+      require "yaml"
+      data = YAML.safe_load_file(path)
+      return if data.nil?
+      return @warnings << "could not parse #{path}: top level must be a mapping" unless data.is_a?(Hash)
+
+      apply(data)
+    rescue Psych::Exception, SystemCallError => e
+      @warnings << "could not parse #{path}: #{e.message}"
+    end
+
+    def apply(data)
+      (data.keys.map(&:to_s) - KNOWN_KEYS).each { |k| @warnings << "unknown key: #{k}" }
+      apply_replace(data["replace"]) if data.key?("replace")
+      apply_secrets(data["secrets"]) if data.key?("secrets")
+      apply_clipboard(data["clipboard"]) if data.key?("clipboard")
+    end
+
+    # YAML reads `clipboard: true` (or false) as a boolean; as a command it
+    # would run `sh -c true` and copy nothing, so both mean auto.
+    def apply_clipboard(value)
+      text = value.to_s.strip
+      @clipboard = text.empty? || %w[true false].include?(text) ? "auto" : value.to_s
+    end
+
+    def apply_replace(value)
+      return @warnings << "replace must be a mapping; ignored" unless value.is_a?(Hash)
+
+      pairs = value.map { |k, v| [k.to_s, v.to_s] }
+      @replace = pairs.sort_by { |k, _| -k.length }.to_h
+    end
+
+    def apply_secrets(value)
+      return @warnings << "secrets must be a list; ignored" unless value.is_a?(Array)
+
+      value.each do |src|
+        next @warnings << "blank secret pattern ignored" if src.to_s.strip.empty?
+
+        @secrets << Regexp.new(src.to_s)
+      rescue RegexpError => e
+        @warnings << "invalid secret pattern #{src.inspect}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/oops/doctor.rb

@@ -0,0 +1,133 @@
+require_relative "clipboard"
+
+module Oops
+  # `oops doctor`: one `label: value` line per check (spec 7.8). Best effort:
+  # it never raises, whatever state the environment is in.
+  module Doctor
+    module_function
+
+    def report(env:, config:, sessions_dir:, tty:, which: Clipboard::DEFAULT_WHICH)
+      lines = []
+      lines.concat(recording_lines(env, tty))
+      lines << shell_line(env)
+      lines << clipboard_line(config, env, which)
+      lines << "config: #{config_line(env, config)}"
+      lines << sessions_line(sessions_dir)
+      lines << "ruby: #{RUBY_VERSION} (#{RUBY_PLATFORM})"
+      lines.concat(warnings(env))
+      "#{lines.join("\n")}\n"
+    end
+
+    def recording_lines(env, tty)
+      session = env["OOPS_SESSION"].to_s
+      return ["recording: no"] if session.empty?
+
+      lines = []
+      state = File.file?(session) ? session : "#{session} - log file missing"
+      lines << "recording: yes (#{state})"
+      lines << terminal_line(env["OOPS_TTY"].to_s, tty.to_s)
+      status = read_status(session)
+      lines << "log writable: #{status == 'ok' ? 'yes' : 'no'} (#{status.empty? ? 'no status file' : status})"
+      lines << "paused: #{File.exist?("#{session}.paused") ? 'yes' : 'no'}"
+      lines
+    end
+
+    def terminal_line(recorded, here)
+      return "this terminal: recorded" if !here.empty? && recorded == here
+
+      "this terminal: not the recorded tty (this: #{here.empty? ? 'unknown' : here}, " \
+        "recorded: #{recorded.empty? ? 'unknown' : recorded})"
+    end
+
+    def read_status(session)
+      File.read("#{session}.status").strip
+    rescue SystemCallError, IOError
+      ""
+    end
+
+    def shell_line(env)
+      shell = File.basename(env["SHELL"].to_s)
+      shell = "unknown" if shell.empty?
+      version = shell_version(env)
+      hooks = env["__OOPS_SEQ"].to_s.empty? ? "missing" : "installed"
+      "shell: #{[shell, version].compact.join(' ')}, hooks: #{hooks}"
+    end
+
+    def shell_version(env)
+      env["ZSH_VERSION"] || env["BASH_VERSION"]
+    end
+
+    def clipboard_line(config, env, which)
+      backend = Clipboard.detect(config.clipboard, env: env, which: which)
+      "clipboard: #{backend.name}"
+    rescue StandardError => e
+      "clipboard: unknown (#{e.message})"
+    end
+
+    def config_line(env, config)
+      path = Paths.config_file(env: env)
+      state = if config.warnings.any? then config.warnings.join("; ")
+              elsif File.file?(path) then "ok"
+              else "missing"
+              end
+      "#{path} (#{state})"
+    rescue StandardError => e
+      "unknown (#{e.message})"
+    end
+
+    # Counts the session logs themselves, not their .status/.paused files.
+    def sessions_line(dir)
+      return "sessions: 0 logs, 0.0 MB" unless File.directory?(dir)
+
+      logs = Dir.children(dir).map { |n| File.join(dir, n) }.select { |f| f.end_with?(".jsonl") && File.file?(f) }
+      bytes = logs.sum { |f| File.size(f) }
+      "sessions: #{logs.size} #{logs.size == 1 ? 'log' : 'logs'}, #{format('%.1f', bytes / 1_048_576.0)} MB"
+    rescue SystemCallError
+      "sessions: unreadable"
+    end
+
+    def warnings(env)
+      env["SHELL"].to_s.end_with?("bash") ? bash_warnings(env) : []
+    rescue StandardError
+      []
+    end
+
+    def bash_warnings(env)
+      home = env["HOME"].to_s.empty? ? Dir.home : env["HOME"]
+      rc = File.join(home, ".bashrc")
+      return [] unless File.file?(rc)
+
+      lines = after_init_line(File.read(rc).force_encoding(Encoding::UTF_8).scrub)
+      out = []
+      if lines.any? { |l| sets_debug_trap?(l) }
+        out << "warning: ~/.bashrc sets a DEBUG trap, which can replace the oops hook; " \
+               "set it before the oops init line or chain it"
+      end
+      if lines.any? { |l| l.match?(/\A(export\s+)?PROMPT_COMMAND=["']?(?!.*PROMPT_COMMAND)/) }
+        out << "warning: ~/.bashrc assigns PROMPT_COMMAND without appending; " \
+               "this can drop the oops hook if it runs after the oops init line"
+      end
+      out
+    rescue SystemCallError, IOError
+      []
+    end
+
+    # The rc lines after the `oops init bash` line, without comments. Settings
+    # made before that line are taken over by the snippet, so only later ones
+    # can drop the hooks; without an init line there is nothing to check.
+    def after_init_line(text)
+      lines = text.lines.map { |l| l.strip.sub(/(?:\A|\s+)#.*\z/, "") }
+      init = lines.index { |l| l.match?(/oops['"]?\s+init\s+bash\b/) }
+      init ? lines.drop(init + 1) : []
+    end
+
+    # `trap ... DEBUG` that sets a trap; `trap - DEBUG` (reset), `trap -p`
+    # and `trap -l` do not.
+    def sets_debug_trap?(line)
+      args = line[/\Atrap\s+(.*)/, 1]
+      return false if args.nil? || args.match?(/\A-(?:[pl]\b|\s|\z)/)
+
+      args.match?(/\bDEBUG\b/)
+    end
+  end
+end