run_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4f28d8c9977c242536eb737cdde4f7723df1cdaf7b094efcf724562c2fd0f1e
+  data.tar.gz: fe8f3c3a1479f61483137e0ae96a72b2adc0e78b0ccb611130c0d13afbcdd627
+SHA512:
+  metadata.gz: 176389146afcdc0646319c3911024ff6903dcfb4836ac54f86e6f0d7ca9557c71b3a00e3d4295f7ea53c6e5751dcc8f55eb45713da71e6d32083fcbd9feb7b9e
+  data.tar.gz: 784fc1c1c4702adca3504ca13ea1c713172df14791adfb355755dd97ea9e89d570f8f664d28cdd7b8bfcdf08a18d9c520b43dc2e6219a3a9df5285d8cea0877f

data/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    paths-ignore: ["**/*.md"]
+  workflow_dispatch:
+
+permissions: { contents: read } # (zizmor)
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix: { platform: [ubuntu-latest, macos-latest] }
+    runs-on: ${{ matrix.platform }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 (zizmor)
+        with: { persist-credentials: false } # (zizmor)
+      - uses: jdx/mise-action@7e36c90d9ab29c415a2384db3006f3ec8a8cc654 # v4 (zizmor)
+        with: { experimental: true }
+      - run: just check

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/
+# gems don't need to include this since the gemspec is enough
+Gemfile.lock

data/.justfile

@@ -0,0 +1,60 @@
+default: test
+
+#
+# check and friends
+#
+
+check:
+  if [ "{{os()}}" != "windows" ]; then just lint ; fi
+  just test
+  just banner "✓ check ✓"
+
+fmt: (lint "-a")
+
+outdated:
+  just banner Here are the easy ones:
+  bundle outdated --filter-minor || true
+  just banner The full list:
+  bundle outdated || true
+
+pry:
+  bundle exec pry -I lib -r run_kit.rb
+
+lint *ARGS:
+  just banner lint...
+  rubocop {{ARGS}}
+
+test *ARGS:
+  just banner rake test {{ARGS}}
+  rake test {{ARGS}}
+
+# run tests repeatedly
+test-watch *ARGS:
+  watchexec --stop-timeout=0 --clear clear just test "{{ARGS}}"
+
+#
+# publish
+#
+
+gem-local:
+  just banner rake install:local...
+  rake install:local
+
+publish: check
+  just banner rake release...
+  rake release
+  just banner "✓ publish ✓"
+
+
+#
+# banner
+#
+
+set quiet
+
+banner +ARGS:  (_banner '\e[48;2;064;160;043m' ARGS)
+warning +ARGS: (_banner '\e[48;2;251;100;011m' ARGS)
+fatal +ARGS:   (_banner '\e[48;2;210;015;057m' ARGS)
+  exit 1
+_banner BG +ARGS:
+  printf '\e[38;5;231m{{BOLD+BG}}[%s] %-72s {{NORMAL}}\n' "$(date +%H:%M:%S)" "{{ARGS}}"

data/.mise.toml

@@ -0,0 +1,11 @@
+[env]
+_.path = ['{{config_root}}/bin']
+
+[hooks]
+postinstall = ["bundle install"]
+
+[tools]
+just = "latest"
+prek = "latest"
+python = "latest"
+ruby = "latest"

data/.rubocop.yml

@@ -0,0 +1,61 @@
+require:
+  - standard
+
+inherit_gem:
+  standard: config/ruby-3.3.yml
+  standard-custom: config/base.yml
+  standard-performance: config/base.yml
+
+plugins:
+  - standard-custom
+  - standard-performance
+  - rubocop-performance
+
+AllCops:
+  # We completely override Exclude rather than using `inherit_mode: merge` because
+  # we want to undo the exclusion of `bin/*` from rubocop-rails. So we must recreate the
+  # full exclusion list from all of our parent configs.
+  Exclude:
+    - .git/**/*
+    - tmp/**/*
+    - vendor/**/*
+  NewCops: enable
+  SuggestExtensions: false
+
+#
+# fight with standardrb!
+#
+
+Bundler/OrderedGems: { Enabled: true } # sort Gemfile
+Lint/MissingSuper: { Enabled: true } # must call `super`
+Lint/NonLocalExitFromIterator: { Enabled: false } # allow return in iterators
+Lint/RedundantDirGlobSort: { Enabled: true } # glob already sorted
+Naming/FileName: { Enabled: true } # duh
+Naming/MemoizedInstanceVariableName: { Enabled: true } # clean memo ivars
+Naming/MethodName: { Enabled: true } # keep method names conventional
+Performance/MapCompact: { Enabled: true } # filter_map-ish style
+Performance/RegexpMatch: { Enabled: false } # local style is fine
+Performance/SelectMap: { Enabled: true } # filter_map-ish style
+Style/BlockDelimiters: { Enabled: true } # do/end vs braces
+Style/ClassAndModuleChildren: { Enabled: true, EnforcedStyle: nested } # explicit nesting
+Style/ClassMethodsDefinitions: { Enabled: true } # avoid "class << self"
+Style/CollectionCompact: { Enabled: true } # compact over reject
+Style/CollectionMethods: { Enabled: true } # modern collection helpers
+Style/FrozenStringLiteralComment: { Enabled: true, EnforcedStyle: never } # nope
+Style/HashEachMethods: { Enabled: true } # each_key/value helpers
+Style/HashSyntax: { EnforcedShorthandSyntax: always } # modern hash syntax
+Style/HashTransformKeys: { Enabled: true } # transform_keys
+Style/HashTransformValues: { Enabled: true } # transform_values
+Style/MinMax: { Enabled: true } # minmax when fitting
+Style/NestedTernaryOperator: { Enabled: false } # we do this sometimes
+Style/NonNilCheck: { Enabled: false } # allow x != nil for clarity
+Style/PreferredHashMethods: { Enabled: true } # modern hash helpers
+Style/RedundantAssignment: { Enabled: false } # allows s=xxx;s=yyy;s
+Style/RedundantInitialize: { Enabled: true } # remove pointless initialize
+Style/RedundantReturn: { Enabled: false } # sometimes we do this while working on something
+Style/SelectByRegexp: { Enabled: true } # grep-like selection
+Style/StringConcatenation: { Enabled: true } # interpolation
+Style/SymbolArray: { Enabled: true } # %i for symbol arrays
+Style/TrailingCommaInArrayLiteral: { EnforcedStyleForMultiline: consistent_comma } # commas!!
+Style/TrailingCommaInHashLiteral: { EnforcedStyleForMultiline: consistent_comma } # commas!!
+Style/WordArray: { Enabled: true } # %w for word arrays

data/AGENTS.md

@@ -0,0 +1,29 @@
+# Style
+
+1. Keep code/docs/output simple and concise.
+2. Comment major methods and tricky code.
+3. Put only trivial one-liners under `# one-liners`.
+4. Prefer readers over ivars except for assignment or type hints.
+5. Prefer `each`/ranges over `while`; counters are `idx`.
+6. Treat String as immutable: use `StringIO buf`, arrays + `join`, substitution, or interpolation. Never add frozen-string comments.
+7. Prefer truthy checks over `nil?` when `false` is not distinct.
+8. Always nest module/class declarations; never declare them with constant paths such as `module RunKit::Options`.
+9. Do not change `.rubocop.yml` without asking.
+10. Keep PR/commit text succinct: one or two sentences tops. PR titles should be only a few words.
+
+# Tests
+
+1. Run `just test` after every change.
+2. Mirror each source file with one `*_test.rb`; generally use one test method per public method.
+3. Namespace tests to mirror production modules.
+4. Use `new.tap { _1... }` to set up important objects.
+5. Assert observable behavior or state, not incidental mutator return values.
+6. Prefer table cases, shared helpers, and custom assertions.
+7. Derive table messages from inputs; hand-name only opaque proc cases.
+8. Inline one-use table literals directly into `each`; do not name them.
+9. Give complicated classes a rich `test_basic` covering their main behavior end to end.
+10. Prefer a few end-to-end behavior tests over exhaustive trivial method coverage.
+11. Fixtures such as `test/smoke.rb` are exempt from test style conventions.
+12. Use `just test-regen` only for intentional snapshot updates; review generated `*.expected` files.
+13. Stdout/stderr are fine when relevant. Prefer `assert_equal`/`assert_raises`; never use `refute`.
+14. Usually assert only the exception class; check messages only when wording is user-facing behavior.

data/Gemfile

@@ -0,0 +1,13 @@
+source "https://rubygems.org"
+gemspec
+
+group :development, :test do
+  gem "amazing_print"
+  gem "minitest", "~> 6.0"
+  gem "minitest-hooks"
+  gem "mocha"
+  gem "pry", require: false
+  gem "rake", require: false
+  gem "ruby-lsp", require: false
+  gem "standard", "~> 1.56", require: false, platform: :mri
+end

data/README.md

@@ -0,0 +1,107 @@
+# RunKit [![ci](https://github.com/gurgeous/run_kit/actions/workflows/ci.yml/badge.svg)](https://github.com/gurgeous/run_kit/actions/workflows/ci.yml)
+
+RunKit is a small toolkit for cli. It provides option parsing, shell and file helpers, term colors, and a handful of core extensions.
+
+### Installation
+
+```ruby
+# install gem
+$ gem install run_key
+
+# or add to your Gemfile
+gem "run_key"
+```
+
+## RunKit::Options
+
+Featureful cli arg parser based on [spinel-slap](https://github.com/gurgeous/spinel-slap), which combines the best bits from [slop rb](https://github.com/leejarvis/slop) and [clap rs](https://github.com/clap-rs/clap).
+
+```ruby
+options = RunKit.parse do |o|
+  o.int "-n", "--count <n>", "How many times to run", default: 1
+  o.str "--mode <mode>", "Run quickly, or not", choices: %w[fast slow]
+  o.positional "<url>", "url to fetch"
+end
+
+# #<data count=1, mode="slow", url="https://demo.org", _args=[]>
+```
+
+Automatic `--help` for the above. Uses color and wraps to terminal:
+
+<img width="379" height="108" alt="image" src="https://github.com/user-attachments/assets/3d11c8ca-6b57-4dec-9c11-28bf23162ded" />
+
+## RunKit::Shell
+
+`RunKit::Shell` is a mixin with many helpers for bin scripts:
+
+| Function                       | Description                                         |
+| ------------------------------ | --------------------------------------------------- |
+| `csv_read` / `csv_write`       | Read/write CSV (add .gz for gzip)                   |
+| `file_read` / `file_write`     | Atomic read/write files (add .gz for gzip)          |
+| `json_read` / `json_write`     | Atomic read/write json (add .gz for gzip)           |
+| `jsonl_read / `jsonl_write`    | Atomic read/write jsonl (add .gz for gzip)          |
+|                                |
+| `csv_write_stdout`             | Write CSV to stdout                                 |
+| `gunzip` / `gzip`              | (De)compress a string                               |
+| `atomic_write`                 | Atomically replace a file                           |
+| `cache_fetch`                  | Populate/fetch from file cache w/ block             |
+| `cp_metadata`                  | Copy file metadata from src to dst                  |
+| `glob`                         | Find sorted/uniq paths                              |
+| `lines_in_file`                | Count lines in file using `wc`                      |
+|                                |
+| `shell`                        | Run command and return status                       |
+| `shell!`                       | Run command or raise                                |
+| `shell_transform!`             | Atomically transform from src => dst via cmd        |
+| `installed?`                   | Check command availability                          |
+| `kill_process`                 | Kill process if present                             |
+|                                |
+| `banner` / `warning` / `fatal` | Pretty banner in green, orange or red (fatal exits) |
+| `program_name`                 | Return executable name                              |
+| `prompt?`                      | Ask use for confirmation                            |
+| `md5` / `sha256`               | Hash strings                                        |
+
+### RunKit CoreExt
+
+RunKit also installs a small set of core extensions to assist with bin scripts.
+
+| Function                                     | Description               |
+| -------------------------------------------- | ------------------------- |
+| `Enumerable#mean`                            | Mean                      |
+| `Enumerable#stddev`                          | Standard deviation        |
+| `Enumerable#variance`                        | Statistical variance      |
+| `Enumerable#tally_sorted`                    | Tally and sort values     |
+|                                              |
+| `Enumerator#with_progressbar`                | Iterate with progress bar |
+|                                              |
+| `Hash#hash_sort_by`                          | Sort hash                 |
+| `Hash#sort_by_key`                           | Sort hash, by keys        |
+| `Hash#sort_by_value`                         | Sort hash, by values      |
+| `Hash#to_struct`                             | Convert hash to Struct    |
+|                                              |
+| `Numeric#sqrt`                               | Square root               |
+|                                              |
+| `Pathname#abs`                               | Expand to absolute path   |
+| `Pathname#cd`                                | cd                        |
+| `Pathname#chmod`                             | chmod                     |
+| `Pathname#chmod_r`                           | chmod recursively         |
+| `Pathname#chown`                             | chown                     |
+| `Pathname#chown_r`                           | chown recursively         |
+| `Pathname#cp`                                | cp -rf                    |
+| `Pathname#ln`                                | ln                        |
+| `Pathname#mkdir`                             | mkdir -p                  |
+| `Pathname#mv`                                | mv                        |
+| `Pathname#rm`                                | rm                        |
+| `Pathname#rm_rf`                             | rm -rf                    |
+| `Pathname#touch`                             | touch                     |
+| `Pathname#escape`                            | Escape path for shell     |
+|                                              |
+| `String#blue` (also green/organge/red/muted) | White text on color bg    |
+| `String#without_curly`                       | Replace curly quotes      |
+
+Note: There has been some effort to get the Pathname helpers into Ruby itself, without much success.
+
+### Changelog
+
+#### 0.1.0 (unreleased)
+
+- first

data/Rakefile

@@ -0,0 +1,14 @@
+require "bundler/setup"
+require "rake/testtask"
+require "bundler"
+Bundler::GemHelper.install_tasks
+
+Rake::TestTask.new do
+  # let the user pass *.rb on the command line
+  files = ARGV.grep(%r{^test/.*\.rb$}).sort
+  _1.test_files = files.empty? ? FileList["test/**/*_test.rb"] : files
+  # autoload test_helper
+  _1.ruby_opts = ["-w", "-r#{File.realpath("test/test_helper.rb")}"]
+end
+
+task default: :test

data/demo.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require_relative "lib/run_kit"
+
+options = RunKit.parse do |o|
+  o.int "-n", "--count <n>", "How many times to run", default: 1
+  o.str "--mode <mode>", "Run quickly, or not", choices: %w[fast slow]
+  o.positional "<url>", "url to fetch"
+end
+
+p options

data/lib/run_kit/core_ext.rb

@@ -0,0 +1,116 @@
+module RunKit
+  module CoreExt
+    module Enumerable
+      def tally_sorted
+        keyfn = case find { _1 }
+        when ::String then -> { _1&.downcase || "\uffff" }
+        when ::Numeric then -> { _1 || Float::MAX }
+        when ::Array then -> { _1 || [] }
+        when TrueClass, FalseClass then -> { (_1 != nil) ? (_1 ? 0 : 1) : Float::MAX }
+        end
+
+        unsorted = tally
+        begin
+          unsorted.sort_by { [-_2, keyfn&.call(_1)] }
+        rescue ArgumentError, NoMethodError
+          keyfn = nil # mixed types, don't sort on key
+          retry
+        end.to_h
+      end
+
+      def variance(sample: true)
+        n = length
+        return if (sample && n < 2) || (!sample && n.zero?)
+        mu = mean
+        denom = sample ? (n - 1) : n
+        sum(0.0) { (_1 - mu)**2 } / denom
+      end
+
+      # one-liners
+      def mean = empty? ? nil : sum(0.0) / length
+      def stddev(sample: true) = variance(sample:)&.sqrt
+    end
+
+    # each.with_progresbar
+    module Enumerator
+      def with_progressbar(options = {}, &block)
+        defaults = {
+          format: "%j%% %B #{RunKit::Term.paint_ansi("%c/%u %e", RunKit::Term.ansi256_fg(242))}",
+          progress_mark: RunKit::Term.paint_ansi("━", RunKit::Term.ansi256_fg(46)),
+          remainder_mark: RunKit::Term.paint_ansi("━", RunKit::Term.ansi256_fg(237)),
+          output: $stdout.isatty ? $stdout : $stderr,
+          total: size,
+          length: 72,
+        }
+        options = defaults.merge(options)
+
+        return enum_for(__method__) if !block
+
+        if !options[:hide]
+          bar = ProgressBar.create(options)
+        end
+        RunKit::Term.with_hidden_cursor(options[:output]) do
+          each do
+            bar&.increment
+            yield(_1)
+          end
+        end
+      end
+    end
+
+    module Hash
+      def hash_sort_by(&) = sort_by(&).to_h
+      def sort_by_key = hash_sort_by { _1 }
+      def sort_by_value = hash_sort_by { _2 }
+      def to_struct = Struct.new(*keys.map(&:to_sym)).new(*values)
+    end
+
+    module Numeric
+      def sqrt = Math.sqrt(self)
+    end
+
+    module Pathname
+      # one-liners
+      def abs = expand_path
+      def cd(...) = FileUtils.cd(self, ...)
+      def chmod_r(mode, **kwargs) = FileUtils.chmod_R(mode, self, **kwargs)
+      def chown_r(user, group, **kwargs) = FileUtils.chown_R(user, group, self, **kwargs)
+      def cp(dest, **kwargs) = FileUtils.cp_r(self, dest, **kwargs.merge(preserve: true))
+      def escape = Shellwords.escape(to_s)
+      def ln(...) = FileUtils.ln_sf(self, ...)
+      def mv(...) = FileUtils.mv(self, ...)
+      def rm(...) = FileUtils.rm_f(self, ...)
+      def rm_rf(...) = FileUtils.rm_rf(self, ...)
+      def touch(...) = FileUtils.touch(self, ...)
+
+      # Replacements for Pathname built-ins removed below.
+      def self.included(base)
+        base.remove_method :mkdir, :chown, :chmod
+      end
+
+      def chmod(mode, **kwargs) = FileUtils.chmod(mode, self, **kwargs)
+      def chown(user, group, **kwargs) = FileUtils.chown(user, group, self, **kwargs)
+      def mkdir(...) = FileUtils.mkdir_p(self, ...)
+    end
+
+    module String
+      # remove smart quotes
+      def without_curly = tr("“”‘’", "\"\"''")
+
+      # don't judge
+      def blue = RunKit::Term.paint_banner(self, :blue)
+      def green = RunKit::Term.paint_banner(self, :green)
+      def orange = RunKit::Term.paint_banner(self, :peach)
+      def red = RunKit::Term.paint_banner(self, :red)
+      def muted = RunKit::Term.paint_muted(self)
+    end
+  end
+end
+
+# mix them in
+::Enumerable.include RunKit::CoreExt::Enumerable
+::Enumerator.include RunKit::CoreExt::Enumerator
+::Hash.include RunKit::CoreExt::Hash
+::Numeric.include RunKit::CoreExt::Numeric
+::Pathname.include RunKit::CoreExt::Pathname
+::String.include RunKit::CoreExt::String

data/lib/run_kit/options/color.rb

@@ -0,0 +1,30 @@
+#
+# A simple color toggle that can format text. If unset infer from stdout.tty.
+#
+
+module RunKit
+  module Options
+    class Color
+      attr_reader :enabled
+      alias_method :enabled?, :enabled
+
+      def initialize(enabled)
+        @enabled = enabled.nil? ? $stdout.tty? : enabled
+      end
+
+      # one-liners
+      def blue(str) = paint8(str, :blue)
+      def cyan(str) = paint8(str, :cyan)
+      def green(str) = paint8(str, :green)
+      def magenta(str) = paint8(str, :magenta)
+      def red(str) = paint8(str, :red)
+      def yellow(str) = paint8(str, :yellow)
+
+      protected
+
+      def paint8(str, ansi8)
+        enabled? ? Term.paint8(str, ansi8) : str
+      end
+    end
+  end
+end

data/lib/run_kit/options/config.rb

@@ -0,0 +1,123 @@
+#
+# Config users setup with `RunKit::Options.parse`. Records flags, positionals, help text,
+# etc.
+#
+
+module RunKit
+  module Options
+    class Config
+      attr_accessor :app_name, :banner, :color, :exit, :help, :naked, :version
+      attr_reader :flags, :help_flag, :lookup, :positionals, :separators, :version_flag
+      alias_method :naked?, :naked
+
+      def initialize
+        @app_name = File.basename($PROGRAM_NAME)
+        @naked = true
+        @lookup = {}
+        @flags, @positionals, @separators = [], [], []
+      end
+
+      # Add a positional param declared as `<url>`.
+      def pos(meta, help = "")
+        Positional.new(meta:, help:).tap do
+          raise ArgumentError, "duplicate positional #{_1.key}" if key?(_1.key)
+          positionals << _1
+          lookup[_1.key] = _1
+        end
+      end
+
+      # Add separator text at the current point in generated help.
+      def sep(text = "")
+        [flags.length, text].tap do
+          separators << _1
+        end
+      end
+
+      #
+      # flags
+      #
+
+      def bool(*opts, default: nil, required: false)
+        add_flag(Flag.new(:bool, opts, default:, required:))
+      end
+
+      def float(*opts, default: nil, required: false, choices: nil)
+        add_flag(Flag.new(:float, opts, default:, required:, choices:))
+      end
+
+      def int(*opts, default: nil, required: false, choices: nil)
+        add_flag(Flag.new(:int, opts, default:, required:, choices:))
+      end
+
+      def path(*opts, default: nil, required: false, choices: nil)
+        add_flag(Flag.new(:path, opts, default:, required:, choices:))
+      end
+
+      def str(*opts, default: nil, required: false, choices: nil)
+        add_flag(Flag.new(:str, opts, default:, required:, choices:))
+      end
+
+      def sym(*opts, default: nil, required: false, choices: nil)
+        add_flag(Flag.new(:sym, opts, default:, required:, choices:))
+      end
+
+      # long-form aliases
+      alias_method :boolean, :bool
+      alias_method :integer, :int
+      alias_method :pathname, :path
+      alias_method :positional, :pos
+      alias_method :separator, :sep
+      alias_method :string, :str
+      alias_method :symbol, :sym
+
+      # handy helpers
+      def defaults
+        flags.filter_map do
+          next if _1.required || _1 == help_flag || _1 == version_flag
+          [_1.key, _1.default]
+        end.to_h
+      end
+
+      # one-liners
+      def flag(switch) = lookup[switch]
+      def flag?(switch) = lookup.key?(switch)
+      def key?(key) = lookup.key?(key)
+      def required = flags.select(&:required?)
+
+      # Complete one-time setup after the caller has declared overrides.
+      def prepare!
+        return if @prepared
+        @prepared = true
+        @exit ||= lambda { |status| Kernel.exit(status) }
+        @help_flag = add_builtin(["-h", "--help"], "Show this message")
+        @version_flag = add_builtin(["-v", "--version"], "Show version") if version
+      end
+
+      protected
+
+      # Add help/version flags, but only for switches the user did not override.
+      def add_builtin(switches, help_text)
+        unused = switches.select { !flag?(_1) }
+        return if unused.empty?
+        add_flag(Flag.new(:bool, unused + [help_text]))
+      end
+
+      def add_flag(flag)
+        # dup check
+        raise ArgumentError, "reserved flag key: _args" if flag.key == :_args
+        raise ArgumentError, "dup flag key: #{flag.key}" if key?(flag.key)
+        flag.switches.each do
+          raise ArgumentError, "dup flag switch: #{_1}" if flag?(_1)
+        end
+
+        # append
+        flags << flag
+        lookup[flag.key] = flag
+        flag.switches.each { lookup[_1] = flag }
+
+        # return flag
+        flag
+      end
+    end
+  end
+end