run_kit 0.1.0

data/lib/run_kit/shell.rb

@@ -0,0 +1,307 @@
+# Shared runtime helpers for text/csv/json IO, shell cmds, banners, etc.
+# note: instance methods will be private due to module_function
+
+module RunKit
+  module Shell
+    module_function
+
+    #
+    # file read/write, including gz
+    #
+
+    def file_read(path)
+      Pathname(path).then do |path|
+        data = path.read
+        data = gunzip(data) if path.extname == ".gz"
+        data
+      end
+    end
+
+    def file_write(path, str)
+      path = Pathname(path)
+      atomic_write(path) do |tmp|
+        str = gzip(str) if path.extname == ".gz"
+        tmp.write(str)
+      end
+    end
+
+    #
+    # json file read/write, including gz
+    #
+
+    def json_read(path, symbolize_names: true) = JSON.parse(file_read(path), symbolize_names:)
+    def json_write(path, json) = file_write(path, JSON.pretty_generate(json))
+    def jsonl_read(path, symbolize_names: true) = file_read(path).split("\n").map { JSON.parse(_1, symbolize_names:) }
+    def jsonl_write(path, json) = file_write(path, json.map { JSON.generate(_1) }.join("\n"))
+
+    #
+    # gzip/gunzip data
+    #
+
+    def gzip(str)
+      Zlib::GzipWriter.new(StringIO.new).tap do
+        _1.write(str)
+      end.close.string
+    end
+
+    def gunzip(str_gz)
+      gz = Zlib::GzipReader.new(StringIO.new(str_gz))
+      gz.read
+    ensure
+      gz&.close
+    end
+
+    #
+    # CSV read/write
+    #
+
+    def csv_read(path, infer: false)
+      io = StringIO.new(file_read(path))
+      rows = CSV.read(io, encoding: "bom|utf-8")
+
+      headers = rows.shift.map(&:to_sym)
+      klass = Struct.new(*headers)
+
+      rows.map do |row|
+        row = row.map { _infer_csv(_1) } if infer
+        klass.new(*row)
+      end
+    end
+
+    def csv_write(path, rows, headers: nil)
+      atomic_write(path) do |tmp|
+        CSV.open(tmp, "wb") { _csv_write0(_1, rows, headers:) }
+      end
+    end
+
+    def csv_write_stdout(rows, headers: nil)
+      CSV($stdout) { _csv_write0(_1, rows, headers:) }
+    end
+
+    #
+    # shell/shell!
+    #
+
+    # Run a command via Open3.capture2e. `cmd` can be passed as:
+    #
+    # - shell("git status")      # a single string
+    # - shell("git", "status")   # varargs strings
+    # - shell(["git", "status"]) # an array of strings
+    #
+    # Prefer arrays so escaping stays explicit and Ruby handles argument
+    # boundaries for you. Single strings are convenient but put escaping
+    # responsibility on the caller. `vars:` lets you interpolate `{{ hi }}` into
+    # the command before it runs. `Pathname` values get shell-escaped, which is
+    # real nice here.
+    #
+    # Returns `[stdout_and_stderr, exit_code]`
+    def shell(*cmd, vars: nil)
+      output, status, _ = _shell(*cmd, vars:)
+      [output, status]
+    end
+
+    # like shell, but raises on non zero exit code. returns stdout_and_stderr otherwise
+    def shell!(*cmd, vars: nil)
+      output, status, cmd = _shell(*cmd, vars:)
+      raise "#{cmd.inspect} failed #{status}\noutput: #{output}" if status != 0
+      output
+    end
+
+    # Atomically transform src into dst.
+    def shell_transform!(*cmd, src:, dst:, force: false)
+      src, dst = Pathname(src), Pathname(dst)
+      in_place = src.abs == dst.abs
+      raise Errno::EEXIST, dst.to_s if dst.exist? && !force && !in_place
+
+      dst.dirname.mkdir
+      tmp = nil
+      Tempfile.create([".tmp-", dst.extname], dst.dirname.to_s) do |tmpfile|
+        tmp = Pathname(tmpfile.path)
+        tmpfile.close
+        shell!(*cmd, vars: {src:, dst: tmp})
+        cp_metadata(src, tmp)
+        # Temp lives beside dst, so rename replaces it atomically; do not use mv.
+        tmp.rename(dst)
+      end
+      dst
+    ensure
+      tmp&.rm
+    end
+
+    # copy mtime and perms from src => dst
+    def cp_metadata(src, dst)
+      src, dst = Pathname(src), Pathname(dst)
+      stat = src.stat
+      dst.chmod(stat.mode)
+      dst.chown(stat.uid, stat.gid)
+      dst.touch(mtime: stat.mtime)
+    end
+
+    # Kill a process, ignore failure
+    def kill_process(pid)
+      Process.kill("KILL", pid)
+    rescue Errno::ESRCH
+    end
+
+    # one-liners
+    def glob(pats) = Pathname.glob(pats).uniq.sort
+    def installed?(cmd) = shell("sh", "-c", "command -v #{cmd.shellescape}")[1] == 0
+    def lines_in_file(path) = shell!("wc", "-l", path).strip.split.first.to_i
+    def md5(str) = Digest::MD5.hexdigest(str)
+    def program_name = Pathname($PROGRAM_NAME).basename
+    def sha256(str) = Digest::SHA256.hexdigest(str)
+
+    #
+    # banner/warning/fatal
+    #
+
+    def banner(str, color: :green)
+      puts Term.paint_banner("[#{_now.strftime("%H:%M:%S")}] #{str.ljust(72)} ", color)
+    end
+
+    def warning(str)
+      banner(str, color: :peach)
+    end
+
+    def fatal(str)
+      banner(str, color: :red)
+      exit(1)
+    end
+
+    # Ask the user a question via stderr, then return true if they enter YES, yes, y, etc.
+    def prompt?(prompt = "Proceed?")
+      $stderr.write("#{prompt} (y/n) ")
+      $stderr.flush
+      ch = $stdin.gets || "no"
+      ch.match?(/^y/i)
+    end
+
+    # Fetches data from `cache` file. If there is data in the cache with the given key, then that data is returned.
+    def cache_fetch(cache:, compress: false, expires_in: nil, force: false, format: :json, symbolize: true, &)
+      cache = Pathname(cache)
+      stale = cache.exist? && expires_in && (_now - cache.mtime > expires_in.to_i)
+      data = if !cache.exist? || stale || force
+        _cache_write(cache:, compress:, expires_in:, format:, &)
+      else
+        _cache_read(cache:, compress:, expires_in:, format:)
+      end
+      data = _symbolize_keys(data) if symbolize
+      data
+    end
+
+    #
+    # helpers
+    #
+
+    # Atomically replace a file by writing to a temporary path first.
+    def atomic_write(path, &block)
+      tmp = nil
+      Pathname(path).tap do |path|
+        path.dirname.mkdir
+        tmp = Pathname("#{path}.tmp").tap(&:rm)
+        yield(tmp)
+        # Temp lives beside path, so rename replaces it atomically; do not use mv.
+        tmp.rename(path)
+      end
+    ensure
+      tmp&.rm
+    end
+
+    # low-level helper for writing csv <= rows w/ headers
+    def _csv_write0(csv, rows, headers: nil)
+      headers ||= rows.first.to_h.keys
+      csv << headers
+      rows.each do |row|
+        row = row.to_h
+        csv << headers.map { row[_1] }
+      end
+    end
+
+    # infer int/float from str
+    def _infer_csv(str)
+      case str
+      when /\A-?\d+\z/ then return str.to_i
+      when /\A-?\d+[.\d]+\z/ then return str.to_f
+      end
+      str
+    end
+
+    # shell helper
+    def _shell(*cmd, vars: nil)
+      begin
+        cmd = _shell_cmd(cmd, vars:)
+        output, status = Open3.capture2e(*cmd)
+        status = status.exitstatus
+      rescue Errno::ENOENT => ex
+        output, status = ex.message, 127
+      end
+      [output.strip, status, cmd]
+    end
+
+    def _shell_cmd(cmd, vars: nil)
+      cmd = cmd.first if cmd.one? && (cmd.first.is_a?(Array) || cmd.first.is_a?(String))
+      if vars
+        raise ArgumentError, "cmd must be string with vars: {...}" if !cmd.is_a?(String)
+        cmd = vars.reduce(cmd) do |memo, (k, v)|
+          k = "{{#{k}}}"
+          raise ArgumentError, "#{cmd.inspect} does not contain #{k}" if !memo.include?(k)
+
+          v = case v
+          when Array then v.shelljoin
+          when Pathname then v.escape
+          else; v.to_s
+          end
+          memo.gsub(k, v)
+        end
+      end
+      Array(cmd).map(&:to_s)
+    end
+
+    def _cache_read(cache:, compress: false, expires_in: nil, format: :json)
+      data = cache.binread
+      data = gunzip(data) if compress
+      case format
+      when :bin then data.force_encoding("ascii-8bit")
+      when :json then JSON.parse(data)
+      when :jsonl then data.split("\n").map { JSON.parse(_1) }
+      when :marshal then Marshal.load(data)
+      when :str, :string then data.force_encoding("utf-8")
+      else; raise "unknown format #{format.inspect}"
+      end
+    end
+
+    def _cache_write(cache:, compress: false, expires_in: nil, format: :json, &)
+      yield.tap do
+        data = case format
+        when :bin, :str, :string then _1.to_s
+        when :json then _1.to_json
+        when :jsonl then _1.map(&:to_json).join("\n")
+        when :marshal then Marshal.dump(_1)
+        else; raise "unknown format #{format.inspect}"
+        end
+        data = gzip(data) if compress
+        cache.binwrite(data)
+      end
+    end
+
+    # note: no activesupport dependency
+    def _symbolize_keys(obj)
+      case obj
+      when Hash
+        obj.to_h do |k, v|
+          k = begin
+            k.to_sym
+          rescue
+            k
+          end
+          [k, _symbolize_keys(v)]
+        end
+      when Array then obj.map { _symbolize_keys(_1) }
+      else; obj
+      end
+    end
+
+    # we don't want activesupport, force getlocal
+    def _now = Time.now.getlocal
+  end
+end

data/lib/run_kit/term.rb

@@ -0,0 +1,201 @@
+# ANSI-aware terminal helpers.
+module RunKit
+  module Term
+    module_function
+
+    #
+    # terminal helpers
+    #
+
+    # Calculate terminal width, defaulting to 48x80.
+    def winsize(...)
+      IO.console&.winsize(...) || [48, 80]
+    end
+
+    def with_hidden_cursor(output)
+      output.write CURSOR_HIDE
+      yield
+    ensure
+      output.write CURSOR_SHOW
+    end
+
+    # Measure characters while ignoring ANSI control sequences.
+    def width(str) = str.gsub(ANSI_RE, "").length
+
+    # Return word-wrapped text. ANSI escapes are taked into account, but we do
+    # not wrap colored regions across lines.
+    def wrap(str, truncate_to)
+      return "" if str.empty?
+
+      lines, words = [], []
+      tokens = str.split(/[ \t\r]+|(\n)/).reject(&:empty?) # words and newlines
+      tokens.each do |word|
+        if word == "\n"
+          lines << words.join(" ")
+          words = []
+          next
+        end
+        if !words.empty? && width("#{words.join(" ")} #{word}") > truncate_to
+          lines << words.join(" ")
+          words = []
+        end
+
+        words << word
+      end
+      lines << words.join(" ") unless words.empty?
+      lines << "" if tokens.last == "\n"
+      lines.join("\n")
+    end
+
+    #
+    # painting color strings
+    #
+
+    PALETTE = {
+      # catppuccin latte
+      rosewater: "#dc8a78",
+      flamingo: "#dd7878",
+      pink: "#ea76cb",
+      mauve: "#8839ef",
+      red: "#d20f39",
+      maroon: "#e64553",
+      peach: "#fe640b",
+      yellow: "#df8e1d",
+      green: "#40a02b",
+      teal: "#179299",
+      sky: "#04a5e5",
+      sapphire: "#209fb5",
+      blue: "#1e66f5",
+      lavender: "#7287fd",
+      text: "#4c4f69",
+      subtext1: "#5c5f77",
+      subtext0: "#6c6f85",
+      overlay2: "#7c7f93",
+      overlay1: "#8c8fa1",
+      overlay0: "#9ca0b0",
+      surface2: "#acb0be",
+      surface1: "#bcc0cc",
+      surface0: "#ccd0da",
+      base: "#eff1f5",
+      mantle: "#e6e9ef",
+      crust: "#dce0e8",
+
+      # some basic colors
+      white: "#ffffff",
+      black: "#000000",
+      muted: "#585858",
+    }
+
+    def paint8(str, color) = paint_ansi(str, BOLD, ansi8_fg(color))
+    def paint_ansi(str, *codes) = "#{CSI}#{codes.join(";")}m#{str}#{RESET}"
+    def paint_muted(str) = paint_ansi(str, ansi_fg(:muted))
+    def paint_banner(str, color) = paint_ansi(str, BOLD, ansi_fg(:white), ansi_bg(color))
+
+    #
+    # ANSI escape codes and colors. ANSI itself supports three different colors
+    # schemes (8-color table, 256 indexed color cube, and full rgb). We have
+    # helpers for each.
+    #
+
+    ANSI_RE = /\e\[[\d;]*m/
+    ESC = "\e"
+    CSI = "#{ESC}["
+    BOLD = "1"
+    RESET = "#{CSI}0m"
+    CURSOR_HIDE = "#{CSI}?25l"
+    CURSOR_SHOW = "#{CSI}?25h"
+
+    #
+    # ansi rgb / direct / 24m color formatting. This is the easiest to use and
+    # almost always the right choice.
+    #
+
+    def ansi_fg(color) = "38;2;#{to_rgb(color).join(";")}"
+    def ansi_bg(color) = "48;2;#{to_rgb(color).join(";")}"
+
+    #
+    # ANSI 8-color table, map from color symbol to color index. Use this if you
+    # want to paint in the user's own terminal color palette. Not good for
+    # reverse color or fine control.
+    #
+
+    ANSI8 = {black: 0, red: 1, green: 2, yellow: 3, blue: 4, magenta: 5, cyan: 6, white: 7, default: 9}
+
+    def ansi8_fg(name8) = 30 + ANSI8.fetch(name8)
+    def ansi8_bg(name8) = 40 + ANSI8.fetch(name8)
+
+    #
+    # ANSI 256 indexed color cube. Rarely used. If you want to use ansi 256 for
+    # compat or perf reasons, choose your color palette in advance instead of
+    # converting on the fly with this stuff.
+    #
+
+    def ansi256_fg(color) = "38;5;#{to_256(color)}"
+    def ansi256_bg(color) = "48;5;#{to_256(color)}"
+
+    def ansi256_cube
+      @ansi256_cube ||= begin
+        cube = [0x00, 0x5f, 0x87, 0xaf, 0xd7, 0xff]
+        rgb_for = ->(idx) do
+          if idx >= 232
+            r = g = b = 8 + (idx - 232) * 10
+          else
+            off = idx - 16
+            r = cube[(off / 36) % 6]
+            g = cube[(off / 6) % 6]
+            b = cube[(off / 1) % 6]
+          end
+          [r, g, b]
+        end
+        Array.new(256) { rgb_for.call(_1) if _1 >= 16 }
+      end
+    end
+
+    #
+    # color converters. `color` is any of:
+    # - nil
+    # - an ansi 256 color cube index
+    # - an [r,g,b] channel array
+    # - a hex color string "#rrggbb"
+    # - one of our named PALETTE symbols
+    #
+
+    HEX_RE = /\A#[\da-f]{6}\z/i
+
+    def to_256(color)
+      case color
+      when nil then return
+      when (0..255) then return color
+      end
+      rgb = to_rgb(color)
+      (16..255).min_by do |idx|
+        rgb.zip(ansi256_cube[idx]).sum { |a, b| (a - b)**2 }
+      end
+    end
+
+    def to_hex(color)
+      case color
+      when nil then color
+      when (16..255) then rgb_to_hex(ansi256_cube[color])
+      when Array then rgb_to_hex(color)
+      when HEX_RE then color
+      when Symbol then PALETTE.fetch(color)
+      else; raise "unknown color format #{color.inspect}"
+      end
+    end
+
+    def to_rgb(color)
+      case color
+      when nil then color
+      when (16..255) then ansi256_cube[color]
+      when Array then color
+      when HEX_RE then hex_to_rgb(color)
+      when Symbol then hex_to_rgb(PALETTE.fetch(color))
+      else; raise "unknown color format #{color.inspect}"
+      end
+    end
+
+    def hex_to_rgb(hex) = hex.delete_prefix("#").scan(/../).map { _1.to_i(16) }
+    def rgb_to_hex(rgb) = sprintf("#%02x%02x%02x", *rgb)
+  end
+end

data/lib/run_kit.rb

@@ -0,0 +1,22 @@
+require "csv"
+require "digest"
+require "fileutils"
+require "io/console"
+require "json"
+require "open3"
+require "pathname"
+require "ruby-progressbar"
+require "shellwords"
+require "stringio"
+require "tempfile"
+require "zlib"
+
+require_relative "run_kit/core_ext"
+require_relative "run_kit/term"
+require_relative "run_kit/options"
+require_relative "run_kit/shell"
+
+# handy entry point for RunKit::Options
+module RunKit
+  def self.parse(...) = Options.parse(...)
+end

data/prek.toml

@@ -0,0 +1,46 @@
+#
+# args: [--severity=error]
+#
+# prek install
+# prek run
+# prek run --all-files
+#
+
+[[repos]]
+repo = "https://github.com/pre-commit/pre-commit-hooks"
+rev = "v6.0.0"
+hooks = [
+  { id = "check-added-large-files" },              # reject large files from git
+  { id = "check-case-conflict" },                  # detect filename case collisions
+  { id = "check-executables-have-shebangs" },      # verify shebangs for shell scripts
+  { id = "check-json" },                           # validate json files
+  { id = "check-merge-conflict" },                 # detect merge markers
+  { id = "check-shebang-scripts-are-executable" }, # verify shell script perms
+  { id = "check-symlinks" },                       # detect broken symlinks
+  { id = "check-toml" },                           # validate toml files
+  { id = "check-yaml" },                           # validate yaml file
+  { id = "detect-private-key" },                   # reject private keys
+  { id = "end-of-file-fixer" },                    # ensure final newline
+  { id = "mixed-line-ending" },                    # normalize line endings
+  { id = "trailing-whitespace" },                  # remove trailing whitespace
+]
+
+[[repos]]
+repo = "https://github.com/rhysd/actionlint"
+rev = "v1.7.12"
+hooks = [ { id = "actionlint" } ] # lint github actions
+
+[[repos]]
+repo = "https://github.com/Yelp/detect-secrets"
+rev = "v1.5.0"
+hooks = [ { id = "detect-secrets" } ] # detect committed secrets
+
+[[repos]]
+repo = "https://github.com/koalaman/shellcheck-precommit"
+rev = "v0.11.0"
+hooks = [ { id = "shellcheck" } ] # lint shell scripts
+
+[[repos]]
+repo = "https://github.com/zizmorcore/zizmor-pre-commit"
+rev = "v1.28.0"
+hooks = [ { id = "zizmor" } ] # github actions security

data/run_kit.gemspec

@@ -0,0 +1,23 @@
+Gem::Specification.new do |s|
+  s.name = "run_kit"
+  s.version = "0.1.0"
+  s.authors = ["Adam Doppelt"]
+  s.email = "amd@gurge.com"
+  s.summary = "Run kit."
+  s.homepage = "https://github.com/gurgeous/run_kit"
+  s.license = "MIT"
+  s.required_ruby_version = ">= 3.2.0"
+  s.metadata = {
+    "homepage_uri" => s.homepage,
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => s.homepage,
+  }
+
+  # what's in the gem?
+  s.files = `git ls-files`.split("\n").grep_v(%r{^(bin|test)/})
+  s.require_paths = ["lib"]
+
+  # gem dependencies
+  s.add_dependency "csv", "~> 3.3"
+  s.add_dependency "ruby-progressbar", "~> 1.13"
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: run_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Adam Doppelt
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: ruby-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+email: amd@gurge.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".justfile"
+- ".mise.toml"
+- ".rubocop.yml"
+- AGENTS.md
+- Gemfile
+- README.md
+- Rakefile
+- demo.rb
+- lib/run_kit.rb
+- lib/run_kit/core_ext.rb
+- lib/run_kit/options.rb
+- lib/run_kit/options/color.rb
+- lib/run_kit/options/config.rb
+- lib/run_kit/options/flag.rb
+- lib/run_kit/options/help.rb
+- lib/run_kit/options/main.rb
+- lib/run_kit/options/parser.rb
+- lib/run_kit/options/positional.rb
+- lib/run_kit/shell.rb
+- lib/run_kit/term.rb
+- prek.toml
+- run_kit.gemspec
+homepage: https://github.com/gurgeous/run_kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/gurgeous/run_kit
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gurgeous/run_kit
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Run kit.
+test_files: []