ready 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 456956b1ac3139ec747542b6b3c38462e4a4016404345930207a36114767b288
-  data.tar.gz: 5c12ad3085a8d16064f6fc2cf3cd9864a827624ae7aa42812d1a0d4e37fc620e
+  metadata.gz: fecb44116c404a5eeefe685cdaafc2b785c57480ade703fb02bd6c6f05fbc794
+  data.tar.gz: 3f641b0e7cb187f7f18f761f2de5e7d269af0532f1b47103efaae1d054bf8ad8
 SHA512:
-  metadata.gz: a350d3b345d9c2bf0eee35816f2b2af3eea33d5a9b4ea6f1c8213d0ff6cf1cfbdb1fc4a92dc68a317604a98ce875ffbfd2ad6f7f2d166cb6b35029a8b83d2a59
-  data.tar.gz: 5bdf1c8d1cdaa141028ca2ffba6c1cb016839884607de0d12aba9bc141a73cd4aa1cb66dfc885ad6198b0394ca1f69ed3647df81e97c010294de2ed7c08fb4b4
+  metadata.gz: a5fcba05fafe2c0f5ae82bfcba271e48f6a5fefe52ded9b3c49175c071174287d2afab742705f1369cd586bd8db039aebe20286d6f0e80bc9eadb0cb2074126b
+  data.tar.gz: 41b2773cf859b8fac712b8dfa4587aa993b3c60bd86518f09d5eab2d973e0a8d4eea873e8776f25d9afbad13edaabc5289882515164c741bc924f423366238a8

data/.rubocop.yml

@@ -17,10 +17,23 @@ plugins:
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 4.0
+  # Lint at the gem's supported floor (ready.gemspec's required_ruby_version),
+  # which CI also exercises -- not the 4.0.1 dev pin -- so accidental
+  # 4.0-only syntax is caught rather than shipped to 3.4 users.
+  TargetRubyVersion: 3.4
   Exclude:
-    - bin/*
+    # Stock bundler scripts; bin/bench is ours and stays linted.
+    - bin/console
+    - bin/setup
     - vendor/**/*
+    # Vendored read-only reference copy of an external gem; not this project's
+    # code (it is also gitignored, so CI never sees it).
+    - references/**/*
+    # Standalone runtime helper scripts -- a doc formatter and the rdoc `ri`
+    # patch -- with their own conventions, not the gem's authored library code.
+    - extra/**/*
+    # Gitignored scratch: benchmark run logs and throwaway report-parsing scripts.
+    - log/**/*
     - lib/core_ext/**/*
     - rakelib/project.rb
     - rakelib/project_version.rb
@@ -128,6 +141,12 @@ Claude/MysteryRegex:
 Style/MutableConstant:
   EnforcedStyle: literals
 
+# Data.define subclassing keeps the class body a real class body, so constants
+# holding instances of the class (e.g. Span::TABLE) live where they belong;
+# the block form would bind them lexically to the enclosing namespace.
+Style/DataInheritance:
+  Enabled: false
+
 # Shared test contexts legitimately define many helpers.
 RSpec/MultipleMemoizedHelpers:
   Max: 10
@@ -151,6 +170,35 @@ Style/Documentation:
   Exclude:
     - "spec/**/*"
 
+# E2E specs share one expensive by-server across examples via before(:all) and
+# hold it in an instance variable; that is intentional here.
+RSpec/BeforeAfterAll:
+  Exclude:
+    - "spec/e2e/**/*"
+
+RSpec/InstanceVariable:
+  Exclude:
+    - "spec/e2e/**/*"
+
+# E2E examples are longer by nature (shell/server setup + several aggregated
+# structural assertions per example).
+RSpec/ExampleLength:
+  Exclude:
+    - "spec/e2e/**/*"
+
+# The e2e and benchmark suites are grouped by test type, not class namespace,
+# so their paths deliberately do not mirror the described constant.
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - "spec/e2e/**/*"
+    - "spec/bench/**/*"
+
+# Ready::Bench::Report is a waterfall renderer whose job is to write to stdout;
+# it lives under spec/support only so Zeitwerk autoloads it.
+RSpec/Output:
+  Exclude:
+    - "spec/support/bench/**/*"
+
 # Trailing commas in multiline literals and arguments.
 Style/TrailingCommaInArrayLiteral:
   EnforcedStyleForMultiline: comma
@@ -183,3 +231,10 @@ RSpec/NamedSubject:
 # have_file_content matcher accepts a filename string in expect()
 RSpec/ExpectActual:
   Enabled: false
+
+Lint/EmptyInPattern:
+  Enabled: false
+
+Metrics/MethodLength:
+  Exclude:
+    - "**/*.rake"

data/README.md

@@ -1,25 +1,92 @@
 # Ready
 
-A new Ruby gem
+Make Ruby CLIs start instantly. `ready` preloads your Ruby executables into a
+persistent [`by`][by] server and installs thin zsh stubs that dispatch to it, so
+tools like `irb`, `rails`, or `rspec` skip Ruby's startup cost on every run.
 
-## Installation
+## Requirements
 
-Install the gem and add to the application's Gemfile by executing:
+- **zsh** — the only supported shell (bash and fish are not supported)
+- **[rbenv]** — the supported Ruby version manager
+- **Ruby >= 3.4.7**
 
-    $ bundle add ready
+## Install
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Install `ready` globally as a command-line tool. Do **not** add it to a
+project's Gemfile or run `bundle add ready` / `bundle install` for it — `ready`
+manages a single machine-wide preloader, not a per-project dependency:
 
-    $ gem install ready
+```sh
+gem install ready
+```
+
+Then load the zsh plugin. `ready init` resolves the plugin's path and prints the
+line that sources it — add it to your `~/.zshrc`:
+
+```sh
+# ~/.zshrc
+eval "$(ready init)"
+```
+
+`ready init` on its own just prints that line, so you can paste it directly
+instead:
+
+```sh
+$ ready init
+source /usr/local/.../gems/ready-x.y.z/zsh/ready/ready.plugin.zsh
+```
 
 ## Usage
 
-TODO: Write usage instructions here.
+List the gems to preload and the executables to compile in `~/.readyfile`:
+
+```yaml
+gems:
+  - rails
+executables:
+  - irb
+  - rspec
+```
+
+Build every stub and start the server:
+
+```sh
+ready up
+```
+
+`irb`, `rspec`, … are now near-instant. The rest of the commands:
+
+```sh
+ready compile irb rspec   # (re)compile stubs for specific CLIs
+ready compile by          # (re)compile just the persistent `by` client
+ready compile all         # recompile everything
+ready clobber             # remove all compiled artifacts
+ready help                # full command reference
+```
+
+## Configuration
+
+`ready` is configured through environment variables — set them before the zsh
+plugin loads:
+
+| Name | Description | Default |
+|------|-------------|---------|
+| `READY_PREFIX` | Base directory for ready's runtime state (socket, builds, logs) | `/tmp/ready` |
+| `READY_SOCK_PATH` | Unix socket for the `by` preloader server | `$READY_PREFIX/ready.sock` |
+| `READY_READYFILE` | YAML file listing the gems/executables to preload | `~/.readyfile` |
+| `READY_LOG_PATH` | Log file | `$READY_PREFIX/ready.log` |
+| `READY_LOGLEVEL` | Minimum log level (`debug`, `info`, `warn`, `error`) | `info` |
+| `READY_DEBUG` | Set to `1` to force debug-level logging | `0` |
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
+After checking out the repo, run `bin/setup` to install dependencies. Then run
+`rake spec` to run the tests and `rake rubocop` to lint (`rake` runs both).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+[by]: https://github.com/jeremyevans/by
+[rbenv]: https://github.com/rbenv/rbenv

data/Rakefile

@@ -1,9 +1,100 @@
+# Everything below develops the ready gem itself (gem build/release, specs,
+# rubocop, benchmarks) and depends on dev-only gems. None of it is needed to RUN
+# ready: the runtime `ready`/`compile`/`clobber`/`ready:*` tasks live in
+# rakelib/ready.rake, which rake auto-loads independently of this file. When
+# ready runs as an installed gem the gemspec and dev gems are absent, so loading
+# this file would crash `ready up|compile|clobber` (e.g. bundler/gem_tasks
+# raising "Unable to determine name from existing gemspec"). Load the dev tasks
+# only in a source checkout, detected by the gemspec's presence.
+return unless (Pathname(__dir__) / "ready.gemspec").exist?
+
 require "bundler/gem_tasks"
 
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
+namespace :spec do
+  desc "Run the end-to-end (:e2e) specs (needs zsh + by/by-server)"
+  task :e2e do
+    ok = system({ "READY_E2E" => "1" }, RbConfig.ruby, "-S", "rspec", "--tag", "e2e")
+    abort("e2e specs failed") unless ok
+  end
+end
+
+def bench_protocol
+  executable = ENV.fetch("BENCH_EXE", "ri")
+  # TCPServer is the default workload for the default tool only; any other
+  # executable runs bare unless BENCH_ARGS says otherwise.
+  default_arguments = executable == "ri" ? "TCPServer" : ""
+  Ready::Bench::Protocol.new(
+    executable_name: executable,
+    arguments: ENV.fetch("BENCH_ARGS", default_arguments).split,
+    preload_gems: bench_preload_gems,
+    rounds: Integer(ENV.fetch("BENCH_RUNS", "15")),
+    warmups: Integer(ENV.fetch("BENCH_WARMUPS", "3")),
+  )
+end
+
+# The hot server preloads the gems a readyfile declares (BENCH_READYFILE),
+# falling back to rdoc, which ships the default tool. The build_dir is
+# irrelevant here -- only gem names are read -- but Readyfile requires an
+# existing directory, so the readyfile's own parent satisfies it.
+def bench_preload_gems
+  readyfile_path = ENV.fetch("BENCH_READYFILE", nil)
+  return ["rdoc"] if readyfile_path.nil?
+
+  readyfile_path = Pathname(readyfile_path)
+  Ready::Readyfile.open(readyfile_path, build_dir: readyfile_path.expand_path.parent).gem_names
+end
+
+def bench_runner
+  require "ready"
+  require "zeitwerk"
+  Zeitwerk::Loader.new.tap do |loader|
+    loader.inflector.inflect("cli" => "CLI")
+    loader.push_dir(Pathname(__dir__) / "spec/support", namespace: Ready)
+    loader.setup
+  end
+  Ready::Bench::Runner.new(protocol: bench_protocol)
+end
+
+# Appends this run's headline numbers so a caller sequencing several
+# benchmarks (bin/bench --plot) can chart them afterwards.
+def export_bench_results(runner, results_path)
+  results = Ready::Bench::ResultsLog.new(results_path)
+  results.append(command: runner.invocation, arm: :cold,
+                 full_milliseconds: runner.cold_summary.duration_of(:full))
+  results.append(command: runner.invocation, arm: :hot,
+                 full_milliseconds: runner.hot_summary.duration_of(:full))
+end
+
+# Plot mode (BENCH_RESULTS set by bin/bench --plot) exports the headline
+# numbers for the CLI to chart and stays silent on stdout, so the plot is the
+# only output; otherwise the full waterfall report is the output. Either way
+# the run narrates its progress to stderr.
+def run_bench(verbose:)
+  runner = bench_runner.call
+  results_path = ENV.fetch("BENCH_RESULTS", nil)
+  if results_path
+    export_bench_results(runner, results_path)
+  else
+    runner.render(verbose:)
+  end
+end
+
+desc "Print the cold-vs-hot startup waterfall (needs zsh + by-server + rbenv); bin/bench is the front door"
+task :bench do
+  run_bench(verbose: false)
+end
+
+namespace :bench do
+  desc "rake bench plus a legend table explaining every span row"
+  task :verbose do
+    run_bench(verbose: true)
+  end
+end
+
 require "rubocop/rake_task"
 RuboCop::RakeTask.new
 

data/demo/demofns.zsh

@@ -0,0 +1,34 @@
+unready_shell() {
+  local fnname=$0
+  local i
+  local -a fns=(${functions[(I)*ready_*]})
+  local -a toremove=(${0} reready)
+  local -a raliases
+  fns=(${fns:|toremove})
+
+  for i in $fns; do
+    print -u2 "Removing fn ${(qqq)i}"
+    unfunction $i
+  done
+
+  raliases=(${(k)aliases[(R)*ready*]})
+
+  for i in $raliases; do
+    print -u2 "Removing alias ${(qqq)i}"
+    unalias $i
+  done
+}
+
+reready() {
+  unready_shell
+  command pkill -f by-server
+  command ready clobber
+  yes | command gem uninstall ready || true
+  command bundle exec rake clobber
+  command bundle exec rake build
+  command gem install \
+    --conservative \
+    --no-document \
+    --no-update-sources \
+    --local pkg/ready*
+}

data/demo/rubyconf.rec

@@ -0,0 +1,40 @@
+%rec: Issue
+%key: Id
+%typedef: text_t regexp /^.*$/
+%typedef: Owner_t enum me claude
+%typedef: Status_t enum open in_progress complete
+%type: Id int
+%type: Title line
+%type: Desc text_t
+%type: Owner Owner_t
+%type: Status Status_t
+%type: Updated date
+%auto: Id Updated
+%mandatory: Title Desc Owner Status
+
+Id: 0
+Updated: Mon, 13 Jul 2026 20:59:56 -0500
+Title: Tough items still not figured out
+Desc: 
++ 1. By needs a few patches: 
++   a. Need to provide process substitution support - the process sub fds also need to be passed via send_io
++ 2. Interactives like ssh, fzf, irb and friends can be unpredictable and extremely difficult to debug/test
++   a. kamal ssh not working e2e
++   b. irb occasionally spits out bizarre errors
++   c. SIGINT currently kills the whole process, rather than propogating to the interactive
+Owner: me
+Status: open
+
+Id: 1
+Updated: Mon, 13 Jul 2026 21:08:41 -0500
+Title: ready compile should default to all - shouldn't be required
+Desc:
+Owner: me
+Status: open
+
+Id: 2
+Updated: Mon, 13 Jul 2026 22:06:59 -0500
+Title: Interesting quirks
+Desc: 1. bundler/setup and bundle exec were causing major issues, took a lot of debugging but eventually traced the RUBYOPT env var being set by bundler. the zsh stubs surgically remove that env variable before loading the stub (doesn't affect global env, just the run)
+Owner: me
+Status: open

data/exe/ready

@@ -1,3 +1,20 @@
 #!/usr/bin/env ruby
 
-require "ready"
+# Use Bundler when developing against a checkout (a Gemfile is present in the
+# gem root), but stay bundler-free in production so an installed `ready` gem
+# resolves its dependencies through RubyGems. Requiring bundler/setup directly
+# (rather than invoking via `bundle exec`) means production installs (which
+# ship no Gemfile, per the gemspec's file list) run without Bundler at all.
+# In a dev checkout Bundler is active and, as expected, propagates
+# `-rbundler/setup` in RUBYOPT to child processes; the generated zsh stubs strip
+# that at runtime (see fn.zsh.erb).
+gemfile = File.expand_path("../Gemfile", __dir__)
+
+if File.exist?(gemfile)
+  ENV["BUNDLE_GEMFILE"] ||= gemfile
+  require "bundler/setup"
+end
+
+require_relative "../lib/ready"
+
+Ready::CLI.start

data/extra/browse.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env zsh
+emulate -L zsh
+setopt extendedglob
+
+zmodload zsh/zutil
+
+local -A opts
+zparseopts -D -E -F -M -A opts \
+  - \
+  -style: \
+  -reg \
+  -preview \
+  -glow \
+  -rif \
+  f:=-format \
+  -format:
+
+(( $? == 0 )) || return 1
+
+zmodload -F zsh/files b:zf_mkdir
+zmodload zsh/mapfile
+mapfile[/tmp/fzf/state//reg]=""
+
+typeset -gx RIF=$(( $+opts[--rif] ))
+typeset -gx RI_REG=$(( $+opts[--reg] ))
+typeset -gx FORMAT=${${opts[--format]:-markdown}#=}
+typeset -gx GLOW=$(( $+opts[--glow] ))
+typeset -gx STYLE=${${opts[--style]:-dark}#=}
+typeset -gx TIMEFMT='%U user %S system %P cpu %*E total'
+typeset -gx _RI_SELF=${0:A}
+typeset -gx _RI_FIFO=$(mktemp -u)
+typeset -gx _RI_FD_RW _RI_FD_R
+
+typeset -g FZFX=~/repos/vault/wip/fzfx.sh
+
+local script_dir=${0:A:h}
+local rif=$script_dir/rif2
+local formatter=$script_dir/formatter.rb
+local ready_build=/tmp/ready/builds.zwc
+
+if [[ -f $ready_build ]]; then
+  fpath+=(${ready_build:P})
+  autoload -Uz ${ready_build:P}
+else
+  print -u2 -P "%F{yellow}Warning: ready build zwc not found"
+  exit 1
+fi
+
+if ! [[ -f $formatter ]]; then
+  print -u2 "%F{red}%BError:%b Cannot locate %Bformatter.rb%b%f"
+  return 1
+fi
+
+mkfifo $_RI_FIFO
+
+exec {_RI_FD_RW}<>$_RI_FIFO
+exec {_RI_FD_R}<$_RI_FIFO
+
+trap "exec {_RI_FD_RW}>&- {_RI_FD_R}>&-; rm -f $_RI_FIFO" EXIT INT TERM
+
+glow() {
+  emulate -L zsh
+  setopt extendedglob
+  CLICOLOR_FORCE=1 command glow --style $STYLE $@
+}
+
+display() {
+  emulate -L zsh
+
+  if ! (( GLOW )); then
+    command cat
+  else
+    $script_dir/by $formatter \
+    | gawk '
+		/`{3}ruby/{block=1; print; next}
+		/`{3}/{block=0; print; next}
+		block==1{gsub(/^    /,"")}
+		{print}
+' | glow
+  fi
+}
+
+preview() {
+  emulate -L zsh
+  setopt extendedglob
+  local rc
+  local -a ri_args=(--format=$FORMAT)
+  local -a rif_args=(--forcebat)
+  local -a rif2_args
+
+  if (( RIF )); then
+    autoload -Uz +X rif
+    rif_args+=(${@:#-*})
+    rif2_args+=(${@:#-*})
+    $rif ${(z)rif2_args}; rc=$?
+
+    if (( rc != 0 )); then
+      print -u2 -P "%F{yellow}No matches found for %B$@%b%f"
+    fi
+    return $rc
+  fi
+
+  {
+    if (( $RI_REG )); then
+      command ri $ri_args $@
+    else
+      # normally would pass ri_args here but args present keeps triggering Test::Unit
+      $script_dir/ready_ri $@
+    fi
+  } | display
+}
+
+printrez() {
+  local arr_name=${1:?}
+  local item=${${(P)arr_name}[-1]}
+  local rc
+  local -a lines
+  ($script_dir/ready_ri --list $item  2>/dev/null) \
+    | {
+    read line && lines+=($line)
+    read line && lines+=($line)
+    read line && lines+=($line)
+    read line && lines+=($line)
+    if [[ $lines =~ '--list' ]]; then
+      $script_dir/ready_ri "$item#" 2>/dev/null
+    else
+      print -r -l -- $lines
+      cat
+    fi
+  } | $script_dir/finder.sh
+}
+
+local -a stack
+if (( $+opts[--preview] )); then
+  preview $@
+  return $?
+else
+  while true; do
+    if (( $#stack == 0 )); then
+      result=$( printrez stack)
+      rc=$?
+
+      if [[ -z $result ]]; then
+        break
+        return $rc
+      fi
+      stack+=($result)
+    else
+      result=$(printrez stack)
+
+      rc=$?
+
+      if (( rc == 0 )) && (( ${#${result#[A-Z]}} != $#result )); then
+        stack+=($result)
+        continue
+      else
+        stack=(${stack[1,-2]})
+      fi
+    fi
+  done
+fi

data/extra/finder.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env sh
+
+FZFX="$HOME/repos/vault/wip/fzfx.sh"
+
+exec "$FZFX" \
+  --ansi \
+  --reverse \
+  --preview='preview {}' \
+  --bind='change:first' \
+  --bind='focus:bg-transform-preview-label(print_timing)' \
+  --bind='start:execute-silent(initialize)+bg-transform-footer(flip_toggle glow; print_mode)+refresh-preview' \
+  --bind='alt-m:execute-silent(change_mode)+bg-transform-footer(print_mode)+refresh-preview' \
+  --bind='alt-g:execute-silent(toggle_glow)+bg-transform-footer(print_mode)+refresh-preview' \
+  --bind='tab:execute-silent(toggle_source)+refresh-preview' \
+  --preview-window='70%,wrap' \
+--inject '
+      initialize() {
+				create_toggle rif
+	      create_toggle glow
+
+	      if (( RI_REG )); then
+		      state_set reg 1
+	      else
+		      state_set reg 0
+	      fi
+      }
+
+      print_timing() {
+	zmodload zsh/system
+	sysread -i ${_RI_FD_R} -o 1
+      }
+
+      print_mode() {
+				emulate -L zsh
+				local mode
+
+	      if _is_reg; then
+		      mode="%BNORMAL%b"
+	      else
+		      mode="%B%F{green}RIZZ%f%b"
+	      fi
+
+				if get_toggle glow; then
+					mode="$mode + %F{magenta}glow%f"
+				fi
+				print -P -- ${mode}
+      }
+
+      toggle_glow() {
+	      flip_toggle glow
+      }
+
+		  toggle_source() {
+				flip_toggle rif
+			}
+
+      change_mode() {
+	      if _is_reg; then
+	        state_set reg 0
+	      else
+	        state_set reg 1
+	      fi
+      }
+
+      preview() {
+          if _is_reg; then
+						RI_REG=1
+					else
+						RI_REG=0
+					fi
+
+          local -a args=(--preview)
+
+					if (( RI_REG )); then
+						args+=(--reg)
+					fi
+
+					if get_toggle glow; then
+						args+=(--glow)
+					fi
+
+					if get_toggle rif; then
+						args+=(--rif)
+					fi
+
+					{ time $_RI_SELF --style $STYLE -f $FORMAT ${(z)args} -- $@ 2>&1 } 2>&$_RI_FD_RW
+				}
+
+      _is_reg() {
+	      integer value=$(state_get reg)
+	      if (( value )); then
+		      return 0;
+	      else
+		      return 1
+	      fi
+      }
+      '