cinnabar 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b77622e5e559801f83245411e113493c2735390a17cbd93cd3286a2db1c8b5a
-  data.tar.gz: 80654c7b5dcaf3debb68aaed1dabbe4f4391eff86269da91bb532aac0b79196a
+  metadata.gz: b8b6184f3c8af69dfce30f53af0f8fcad8b34a380dae6bc3e21c32f3bde4753b
+  data.tar.gz: aa0f40c2a071eb846d01db60bdf60a9b738d8a3f0fe76e70bf57d48fa670376b
 SHA512:
-  metadata.gz: 0e2f058289338aee86c2eca9f5b33cb4d98c55669f98677ca2cc8967e390231cb8b54479acccedafef9166d28f60d9dde8bbfbc60e7db20b846ce372ffda8d70
-  data.tar.gz: d8ee09d5461bfbb40aa21b4b2ba155bd33d765630034815843d358d11c01ac5b70b089c72242deba02ba5ffcae60f64e9c0f2133cc392da04e922de49bd8eeb9
+  metadata.gz: 866a074b21a09531dd22c8f237f25ea9b86f96c2a431d99b010d7b375def9f58947f244ee67d4177c442c82bc16b7b4c578ad75ad5768ac90baae009663d714a
+  data.tar.gz: 5f65f8f023ba4281cc6afb755f8ab3f5f73faa627096a81cb2c78734ef14b36f686ee87ddd91912b07c2d8630a79730c2c7a3918be5723a7aa9ed2b87b388d8f

data/.rubocop.yml

@@ -26,6 +26,8 @@ Style/Documentation:
   Enabled: false
 Style/ClassAndModuleChildren:
   EnforcedStyle: compact
+Style/RescueModifier:
+  Enabled: false
 
 # https://docs.rubocop.org/rubocop/cops_metrics.html
 Metrics/MethodLength:
@@ -42,4 +44,3 @@ Layout/MultilineMethodCallIndentation:
 Naming/AsciiIdentifiers:
   # AsciiConstants: false
   Enabled: false
-

data/docs/ChangeLog.md

@@ -1,5 +1,18 @@
 # ChangeLog
 
+## v0.0.4 (2026-01-15)
+
+> TL;DR: Refactor Path logic, introduce GemPath & Utils, update CI loading, and adjust RuboCop rules
+
+- Introduced `Cinnabar::GemPath` and replaced legacy `Cinnabar::Path` gem‑loading logic.
+- Updated `ci.rb` to use `new_gem_path_proc` and JSON cache file.
+- Updated gem_path cache format:
+  - DSL:`"#{k1}#{2spaces}#{v1}"` => json: `{"#{k1}": [v1, v2]}`
+- Removed large monolithic gem‑path utilities from `path.rb`.
+- Added `Cinnabar::Utils`
+- Adjusted `.rubocop.yml`: disabled `Style/RescueModifier`.
+- Added **misc/firb**
+
 ## v0.0.2 (2026-01-05)
 
 - fix ruby v4.0.0 compatibility

data/docs/Readme-zh.md

@@ -24,9 +24,10 @@
 2.  朱砂有毒。这个项目是为了 **猛、糙、快** (a.k.a. *Dirty and Quick*) 的目的而开发的，可能会产生意料之外的副作用（它并非完全无害）。
 3.  朱砂是一种硫化汞 (HgS) 的矿物，呈深红色，而 Ruby 也是一种深红色的宝石。给一个 Ruby 项目取名为 “Cinnabar（朱砂）” 非常贴切。
 
-## API DOC
+## 文档
 
-![ClassDiagram](../misc/assets/svg/ClassDiagram.svg)
+[![ClassDiagram](../misc/assets/svg/ClassDiagram.svg)](https://raw.githubusercontent.com/2moe/cinnabar/refs/heads/main/misc/assets/svg/ClassDiagram.svg)
 
 - Github Pages: <https://2moe.github.io/cinnabar>
-
+- [变更日志](./ChangeLog.md)
+- 详见[英文 Readme](./Readme.md)

data/docs/Readme.md

@@ -24,11 +24,12 @@ A:
 2. Cinnabar is toxic. This project was developed for *Dirty and Quick* purposes and may produce unexpected side effects—in a sense, it is not entirely harmless.
 3. Cinnabar, a mineral form of mercury sulfide (HgS), is a deep red-colored stone. And ruby is also a deep red stone. Naming a Ruby project "Cinnabar" is particularly fitting.
 
-## API DOC
+## Documentation
 
-![ClassDiagram](../misc/assets/svg/ClassDiagram.svg)
+[![ClassDiagram](../misc/assets/svg/ClassDiagram.svg)](https://raw.githubusercontent.com/2moe/cinnabar/refs/heads/main/misc/assets/svg/ClassDiagram.svg)
 
 - Github Pages: <https://2moe.github.io/cinnabar>
+- [ChangeLog](./ChangeLog.md)
 
 ## Quick Start
 
@@ -156,3 +157,25 @@ jobs:
       .▷(upper)
       .▷ :puts #=> "FOO"
 ```
+
+### String To Pathname
+
+```ruby,yaml
+- run: |
+    __dir__.to_path #  Same as Pathname(__dir__)
+      .join('tmp')
+```
+
+### GemPath
+
+#### Faster IRB
+
+> **NON CI Environment**
+
+1. run: [misc/firb/install-cinnabar.ps1](../misc/firb/install-cinnabar.ps1)
+2. Enter `${XDG_CACHE_HOME:-~/.cache}/ruby/firb/bin/`
+3. run
+  - [`./firb0`](../misc/firb/bin/firb0)
+  - OR `.\firb0.bat` (Windows)
+  - OR [`./firb`](../misc/firb/bin/firb)
+  - OR `.\firb.bat` (Windows)

data/lib/cinnabar/gem_path.rb

@@ -0,0 +1,435 @@
+# frozen_string_literal: true
+
+# NOTE: This file can be run independently.
+
+require 'pathname'
+
+module Cinnabar
+  # Returns a factory `Proc` that builds a {Cinnabar::GemPath} instance.
+  #
+  # This is useful when you want to defer initialization or inject a constructor-like
+  # callable into other components (e.g., configuration objects, DI containers, hooks).
+  #
+  # ## Behavior
+  #
+  # - The returned `Proc` accepts a single argument `opts`.
+  # - When called, it creates a new {Cinnabar::GemPath} with `opts`.
+  #
+  # @param opts [Hash] options forwarded to {Cinnabar::GemPath#initialize}
+  # @option opts [String] :cache_dir base directory for the JSON cache
+  # @option opts [String] :cache_file cache file name or absolute path
+  # @option opts [Array<String,Symbol>] :gems gem names to resolve
+  # @option opts [Boolean] :install_gem whether to auto-install missing gems
+  #
+  # @return [Proc] a callable object: `(opts) -> Cinnabar::GemPath`
+  #
+  # @example Build and use a resolver on demand
+  #
+  #     {
+  #        gems: %w[rdoc logger irb reline fiddle],
+  #        install_gem: true
+  #     }.then(&Cinnabar.new_gem_path_proc)
+  #      .append_load_path!
+  #
+  # @see Cinnabar::GemPath
+  def self.new_gem_path_proc = ->(opts) { Cinnabar::GemPath.new(opts) }
+end
+
+# Low-level helpers for resolving RubyGems load paths.
+#
+# This module provides the "expensive" operations: loading RubyGems, locating gem specs, and
+# optionally installing missing gems.
+#
+# ## Design goals
+#
+# - **Lazy-load RubyGems**: do not `require 'rubygems'` at file load time.
+# - **Return full require paths**: use RubyGems’ resolved paths rather than hand-joining.
+# - **Be usable by higher-level caches**: see {Cinnabar::GemPath}.
+#
+# @note These functions may perform disk I/O and can be slow.
+module Cinnabar::GemPathCore
+  module_function
+
+  # Ensures RubyGems is loaded.
+  #
+  # @note If Ruby was not started with `--disable=gems` option, this function is unnecessary.
+  #
+  # @note This function **must** be called only at the point where RubyGems is
+  #   actually needed (lazy loading).
+  #
+  # ## Behavior
+  #
+  # - If RubyGems is already available (`::Gem` and `Gem::Specification`), this is a no-op.
+  # - Otherwise, it calls `require 'rubygems'`.
+  #
+  # @return [void]
+  #
+  # @note Do not call `require 'rubygems'` outside this method.
+  def ensure_rubygems!
+    return if defined?(::Gem) && ::Gem.respond_to?(:Specification)
+
+    Kernel.require 'rubygems'
+  end
+
+  # Returns full load paths for a gem's require paths.
+  #
+  # This uses `Gem::Specification#full_require_paths`, which returns **absolute**
+  # directories that should be added to `$LOAD_PATH` to require files from the gem.
+  #
+  # @param gem_name [String] gem name (e.g. `"logger"` or `:logger`)
+  # @return [Array<String>] absolute require directories (e.g. `["/path/to/gems/foo/lib"]`)
+  #
+  # @raise [Gem::LoadError] if the gem is not installed / cannot be found
+  # @example Get full require paths
+  #   Cinnabar::GemPathCore.find_lib_paths("logger")
+  def find_lib_paths(gem_name)
+    ensure_rubygems!
+
+    Gem::Specification.find_by_name(gem_name).full_require_paths
+  end
+
+  # Returns the gem's load paths; installs the gem when missing.
+  #
+  # This method is intended for low-level bootstrap scenarios:
+  #
+  # - Try to resolve require paths via RubyGems.
+  # - If it fails, warn to stderr and attempt `Gem.install(gem)`.
+  # - Re-resolve paths after successful installation.
+  #
+  # ## Notes
+  #
+  # - This method intentionally prints warnings via {Kernel.warn}.
+  # - Avoid using "advanced" loggers here, because this method may run before
+  #   other dependencies are available.
+  #
+  # @param gem_name [String, Symbol] gem name
+  # @return [Array<String>] absolute require directories for the gem
+  #
+  # @raise [RuntimeError] if installation returns `nil` or an empty spec list
+  # @raise [Exception] any error raised by RubyGems or filesystem operations
+  #
+  # @example Resolve paths, installing automatically if missing
+  #
+  #     logger_lib_paths = Cinnabar::GemPathCore.find_or_install_lib_paths("logger")
+  def find_or_install_lib_paths(gem_name)
+    ensure_rubygems!
+
+    gem = gem_name.to_s
+    begin
+      find_lib_paths(gem)
+
+    # NOTE: Intentionally rescuing `Exception` here (see original intent).
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      Kernel.warn "[WARN] #{e}; Try installing #{gem}"
+
+      # Attempt to install; raise if installation fails.
+      specs = Gem.install(gem)
+      Kernel.raise "Failed to install #{gem}" if specs.nil? || specs.empty?
+
+      find_lib_paths(gem)
+    end
+  end
+
+  # Builds a mapping from gem name to resolved load paths.
+  #
+  # @param gems [Array<String>] gem names
+  # @param install_gem [Boolean] whether to attempt installing missing gems
+  # @return [Hash{(String)=>Array<String>}] mapping: gem_name => full require paths
+  #
+  # @example Build a mapping without installing
+  #   Cinnabar::GemPathCore.init_gem_dir_hash(%w[rdoc logger irb reline fiddle], install_gem: false)
+  def init_gem_dir_hash(gems, install_gem: true)
+    gems.map { |name|
+      paths =
+        if install_gem
+          find_or_install_lib_paths(name)
+        else
+          find_lib_paths(name)
+        end
+
+      [name, paths]
+    }.to_h
+  end
+end
+
+# Cached resolver for gem load paths.
+#
+# {Cinnabar::GemPathCore} performs expensive operations (loading RubyGems, resolving specs,
+# installing missing gems). This class adds a JSON cache layer to reuse results and
+# avoid repeated slow calls.
+#
+# ## What it caches
+#
+# - A Hash mapping `gem_name => [full_require_paths...]`
+# - Serialized to JSON on disk (see {#cache_file})
+#
+# ## Typical usage
+#
+# 1. Create an instance with a set of gems.
+# 2. Call {#append_load_path!} to add those directories to `$LOAD_PATH`.
+#
+# @note Prefer using the cache whenever possible; RubyGems operations can be slow.
+class Cinnabar::GemPath
+  # Alias to the low-level implementation module.
+  #
+  # @return [Module]
+  CoreMod = Cinnabar::GemPathCore
+
+  require 'json'
+
+  # The cache file path, gems list, and install behavior.
+  #
+  # @!attribute [rw] cache_file
+  #   @return [Pathname] cache file path (`*.json`)
+  #
+  # @!attribute [rw] gems
+  #   @return [Array<String>] normalized gem names (unique, non-empty)
+  #
+  # @!attribute [rw] install_gem
+  #   @return [Boolean] whether missing gems should be installed automatically
+  attr_accessor :cache_file, :gems, :install_gem
+
+  # The in-memory cache hash.
+  #
+  # @return [Hash{String=>Array<String>}] gem name => full require paths
+  attr_reader :cache_hash
+
+  # Default options for initialization.
+  #
+  # @return [Hash]
+  # @option cache_dir [String] directory to store cache file (default: `~/.cache/ruby`)
+  # @option cache_file [String] file name or absolute path (default: `gem_path.json`)
+  # @option gems [Array<String,Symbol>] gem names to manage
+  # @option install_gem [Boolean] whether to auto-install missing gems
+  DEFAULT_OPTS = {
+    cache_dir: File.expand_path('~/.cache/ruby'),
+    cache_file: 'gem_path.json',
+    gems: [],
+    install_gem: true,
+  }.freeze
+
+  # Creates a cache-backed gem path resolver.
+  #
+  # ## Behavior
+  #
+  # - Normalizes `gems` to unique, non-empty strings.
+  # - If cache file exists, it is decoded and then refreshed:
+  #   - Missing gems are generated and merged into the cache.
+  #   - Broken entries (paths not existing) are regenerated.
+  # - If no cache exists, it generates paths for all gems and writes the cache.
+  #
+  # @param opts [Hash] options overriding {DEFAULT_OPTS}
+  # @option opts [String] :cache_dir
+  # @option opts [String] :cache_file
+  # @option opts [Array<String,Symbol>] :gems
+  # @option opts [Boolean] :install_gem
+  #
+  # @return [Cinnabar::GemPath]
+  #
+  # @example Create and append load paths
+  #
+  #     gems = %w[rdoc logger irb reline fiddle]
+  #
+  #     { gems: }
+  #       .then { Cinnabar::GemPath.new _1 }
+  #       .append_load_path!
+  def initialize(opts = {})
+    options = DEFAULT_OPTS.merge(opts || {})
+
+    gems, cache_dir, cache_file, @install_gem =
+      options.values_at(:gems, :cache_dir, :cache_file, :install_gem)
+
+    @gems = Array(gems).map(&:to_s).reject(&:empty?).uniq
+
+    raise 'Empty @gems!' if @gems.empty?
+
+    @cache_file = init_cache_file(cache_dir, cache_file)
+    @cache_hash = {}
+
+    if @cache_file.exist?
+      decode_cache_file
+      return
+    end
+
+    merge_generated_paths!(@gems)
+  end
+
+  # Writes the in-memory cache to disk.
+  #
+  # This serializes {#cache_hash} as JSON and persists it using an atomic write
+  # strategy (see {#atomic_write_cache_file}).
+  #
+  # @return [void]
+  def update_cache_file
+    @cache_hash
+      .then { JSON.dump _1 }
+      .then { atomic_write_cache_file _1 }
+  end
+
+  # Appends cached gem paths into `$LOAD_PATH`.
+  #
+  # This is typically called after initialization. It will add each directory in the
+  # cache for the configured gems to Ruby's load path.
+  #
+  # ## Notes
+  #
+  # - This is **idempotent**: it avoids inserting duplicates.
+  # - It mutates the global `$LOAD_PATH` (`$:`).
+  #
+  # @return [void]
+  def append_load_path!
+    @cache_hash
+      .filter { |k, _| @gems.include? k.to_s }
+      .each_value do |vals|
+        Array(vals).each do |dir|
+          # $: is $LOAD_PATH
+          $:.push(dir) unless $:.include?(dir) # rubocop:disable Style/SpecialGlobalVars
+        end
+      end
+  end
+
+  protected
+
+  # Writes cache content to disk atomically.
+  #
+  # It writes to a temporary file and renames it to the final cache path.
+  # This reduces the chance of leaving a partially-written JSON file when the
+  # process crashes or is interrupted mid-write.
+  #
+  # @param content [String] serialized JSON content
+  # @return [void]
+  #
+  # @api private
+  def atomic_write_cache_file(content)
+    path = @cache_file.to_s
+    tmp = "#{path}.tmp.#{$$}" # rubocop:disable Style/SpecialGlobalVars
+    begin
+      File.write(tmp, content)
+      File.rename(tmp, path)
+    ensure
+      File.unlink(tmp) rescue nil
+    end
+  end
+
+  # Resolves the cache file path.
+  #
+  # - If `file` is absolute, it is used directly.
+  # - Otherwise, it is resolved relative to `dir`.
+  # - Ensures the directory exists (`mkpath`).
+  #
+  # @param dir [String, Pathname] base directory
+  # @param file [String, Pathname] file name or absolute path
+  # @return [Pathname] resolved cache file path
+  #
+  # @api private
+  def init_cache_file(dir, file)
+    f = Pathname(file)
+
+    if f.absolute?
+      f
+    else
+      Pathname(dir).join(f)
+    end
+      .tap { _1.dirname.mkpath }
+  end
+
+  # Attempts to decode the cache JSON file into a Hash.
+  #
+  # If decoding fails for any reason, it warns and removes the cache file, then
+  # returns an empty hash.
+  #
+  # @return [Hash] decoded hash (or `{}` if decode fails)
+  #
+  # @note This method intentionally rescues `Exception` per the original design.
+  # @api private
+  def try_decode_cache_hash
+    @cache_file
+      .read
+      .then { JSON.parse _1 }
+  rescue Exception => e # rubocop:disable Lint/RescueException
+    Kernel.warn "[WARN] Failed to decode json file; error: #{e}; unlink #{@cache_file}"
+    @cache_file.unlink
+    {}
+  end
+
+  # Decodes the cache file and refreshes any missing/broken entries.
+  #
+  # - Loads {#cache_hash} from disk.
+  # - Generates entries for missing gems in {#gems}.
+  # - Regenerates entries whose paths no longer exist on disk.
+  #
+  # @return [void]
+  #
+  # @api private
+  def decode_cache_file
+    @cache_hash = try_decode_cache_hash
+    refresh_missing_gems!
+    refresh_broken_gems!
+  end
+
+  # ===========
+  private
+
+  # Computes gems that are required but absent from the cache.
+  #
+  # @return [Array<String>]
+  def missing_gems
+    @gems - @cache_hash.keys
+  end
+
+  # Generates and merges cache entries for missing gems.
+  #
+  # @return [void]
+  def refresh_missing_gems!
+    gems = missing_gems
+    return if gems.empty?
+
+    merge_generated_paths!(gems)
+  end
+
+  # ===========
+
+  # Computes gems whose cached paths are missing on disk.
+  #
+  # @return [Array<String>]
+  def broken_gems
+    @cache_hash
+      .reject { |_, v| all_paths_exist?(v) }
+      .keys
+  end
+
+  # Checks whether all cached paths exist.
+  #
+  # @param values [Array<String>, Object] cached paths (normally an array)
+  # @return [Boolean] true if all entries exist on disk
+  def all_paths_exist?(values)
+    Array(values).all? { File.exist? _1 }
+  end
+
+  # Regenerates and merges cache entries for broken gems.
+  #
+  # @return [void]
+  def refresh_broken_gems!
+    gems = broken_gems
+    return if gems.empty?
+
+    Kernel.warn "[INFO] update gem path, key: #{gems}"
+    merge_generated_paths!(gems)
+  end
+
+  # ===========
+
+  # Generates demonstrates gem paths via {CoreMod} and persists the updated cache.
+  #
+  # @param gems [Array<String>] gem names to generate
+  # @return [void]
+  #
+  # @raise [Exception] any error raised by RubyGems resolution/installation
+  def merge_generated_paths!(gems)
+    h2 = CoreMod.init_gem_dir_hash(gems, install_gem: @install_gem)
+    return if h2.empty?
+
+    @cache_hash.merge! h2
+    update_cache_file
+  end
+end

data/lib/cinnabar/path.rb

@@ -1,24 +1,22 @@
 # frozen_string_literal: true
 
-# NOTE: This file can be run independently;
-#   Although **00_pre.rb** has already imported the relevant libraries, they still need to be imported here.
 require 'pathname'
 
 module Cinnabar
-  # Build a Proc that converts a directory-like value into a {Kernel.Pathname}.
+  # Build a Proc that converts a string value into a {Kernel.Pathname}.
   #
   # This is handy when you want to pass a converter into higher-order APIs
   # (e.g., map/filter pipelines).
   #
-  # @param dir [String, #to_s] a directory path (or any object convertible to String)
-  # @return [Proc] a lambda that maps `dir` to `Pathname(dir)`
+  # @param s [String, Pathname] a path (e.g., file/dir)
+  # @return [Proc] a lambda that maps `s` to `Pathname(s)`
   #
-  # @example Convert a list of directories to Pathname objects
+  # @example convert a list of directories to Pathname objects
   #
   #     conv = Cinnabar.to_path_proc
   #     %w[/tmp /var].map(&conv)
   #     #=> [#<Pathname:/tmp>, #<Pathname:/var>]
-  def self.to_path_proc = ->(dir) { Pathname(dir) }
+  def self.to_path_proc = ->(s) { Pathname(s) }
 end
 
 # Adds `String#to_path` as a convenience helper to convert strings into {Kernel.Pathname}.
@@ -82,172 +80,3 @@ module Cinnabar::StrToPath
     end
   end
 end
-
-module Cinnabar::Path
-  module_function
-
-  # Appends a directory to Ruby's load path (`$LOAD_PATH` / `$:`)
-  # if it is not already included.
-  #
-  # @param dir [String] directory path to add into `$LOAD_PATH`
-  # @return [void]
-  # @example
-  #
-  #     Cinnabar::Path.append_load_path '/opt/ruby/4.0.0/lib/ruby/4.0.0'
-  def append_load_path(dir)
-    # $: is an alias of $LOAD_PATH
-    $: << dir unless $:.include?(dir)
-  end
-
-  # Finds the gem's "lib directory" (via `gem which -V`) and append it to $LOAD_PATH.
-  #
-  # This method maintains a small cache file to avoid running `gem which` repeatedly.
-  # Cache format (per line):
-  #   <gem_name><two spaces><lib_dir>
-  #
-  # If the gem cannot be located, it will try to install it and retry up to `max_retries`.
-  #
-  # @param gem_name [String, Symbol] gem name to locate (default: 'logger')
-  # @param cache_file [String] cache file path (default: 'tmp/load_path.txt')
-  # @param max_retries [Integer] maximum retries for gem install + re-check (default: 2)
-  # @return [void]
-  def find_and_append_load_path(gem_name = 'logger', cache_file: 'tmp/load_path.txt', max_retries: 2)
-    pkg = gem_name.to_s
-    cache_data = decode_cache_file(cache_file)
-
-    # If cached, append immediately and return.
-    case val = cache_data&.[](pkg)
-      when nil then ()
-      else return append_load_path(val)
-    end
-
-    # Locate the gem's lib directory, installing the gem if necessary.
-    lib_dir = gem_dir_with_retry(pkg, max_retries)
-
-    # Update cache and write it back to disk.
-    cache_data[pkg] = lib_dir
-    encoded = encode_cache_hash(cache_data)
-
-    # Ensure parent directory exists, then write the cache file.
-    Kernel.Pathname(cache_file)
-      .tap { _1.dirname.mkpath }
-      .write(encoded)
-
-    # Finally, append the located directory to $LOAD_PATH.
-    append_load_path(lib_dir)
-  end
-
-  # Decodes cache file into a Hash.
-  #
-  # It ignores:
-  #
-  # - leading spaces (lstrip)
-  # - empty lines
-  # - comment lines that start with '#'
-  #
-  # Each line is split by "two spaces" into:
-  #   `key  value`
-  #
-  # @param file [String] cache file path
-  # @return [Hash{String => String}] mapping from gem name to lib dir
-  def decode_cache_file(file)
-    # If cache file does not exist, treat as empty cache.
-    return {} unless File.exist?(file)
-
-    File.foreach(file)
-      .lazy
-      .map(&:lstrip)                  # allow indentation; normalize leading spaces
-      .map(&:chomp)                   # remove trailing newline
-      .reject(&:empty?)               # drop blank lines
-      .reject { _1.start_with? '#' }  # drop comments
-      .map { |line| line.split('  ', 2) } # split into [key, value] by two spaces
-      .to_h
-  end
-
-  # Encodes a Hash into the cache file format.
-  #
-  # @param data [Hash] mapping from gem name to lib dir
-  # @return [String] encoded cache content
-  # @raise [ArgumentError] if `data` is not a Hash
-  #
-  # @example
-  #
-  #     CiPath = Cinnabar::Path
-  #
-  #     gem_home = "#{Dir.home}/.local/share/gem"
-  #     data = {
-  #       "logger" => "#{gem_home}/gems/logger-1.7.0/lib",
-  #       "irb" => "#{gem_home}/gems/irb-1.16.0/lib",
-  #       "reline" => "#{gem_home}/gems/reline-0.6.3/lib",
-  #     }
-  #     str = CiPath.encode_cache_hash(data)
-  def encode_cache_hash(data)
-    Kernel.raise ArgumentError, 'data must be a hash' unless data.is_a? ::Hash
-
-    # Use "two spaces" as a stable delimiter (same as decode).
-    data.map { |k, v| "#{k}  #{v}" }.join("\n")
-  end
-
-  # Resolves gem's lib directory by invoking:
-  #     `gem which -V <pkg>`
-  #
-  # `gem which -V` prints the resolved file path; we strip it and take its dirname.
-  #
-  # @param pkg [String] gem name
-  # @return [String] directory containing the resolved file
-  # @raise [RuntimeError] if gem which returns empty
-  #
-  # @note Please do not use `Gem::Specification` in this method,
-  # as this function and the script must remain compatible with `--disable=gems`.
-  def gem_dir(pkg)
-    path = IO.popen(%w[gem which -V] << pkg.to_s, &:read).to_s.strip
-    Kernel.raise "gem which returned empty for #{pkg}" if path.empty?
-
-    File.dirname(path)
-  end
-  private_class_method :gem_dir
-
-  # Locates the lib directory for the given gem_name; if it fails, retries by installing the gem.
-  #
-  # Behavior:
-  #
-  # - If `gem_dir` raises, print a warning and run `gem install <pkg>`.
-  # - Retry up to `max_retries`.
-  #
-  # @param gem_name [String, Symbol] gem name
-  # @param max_retries [Integer] max retry count (default: 2)
-  # @return [String] resolved lib directory
-  # @raise [RuntimeError] when install fails or retries exceed max
-  #
-  #
-  # @example
-  #
-  #     CiPath = Cinnabar::Path
-  #
-  #     dir_str = CiPath.gem_dir_with_retry("logger")
-  def gem_dir_with_retry(gem_name, max_retries = 2)
-    pkg = gem_name.to_s
-    attempts = 0
-
-    begin
-      logger_dir = gem_dir(pkg)
-    rescue StandardError => e
-      # Inform user about the failure and the planned automatic install attempt.
-      #
-      # Do not use `Sinlog.warn` or any "advanced" logger here!
-      # As this function is intended for lower-level APIs.
-      Kernel.warn "[WARN] #{e}; Try installing #{pkg}"
-
-      # Attempt to install; raise if installation fails.
-      Kernel.system "gem install #{pkg}" or Kernel.raise 'Failed to install'
-
-      attempts += 1
-      Kernel.raise 'Already retried 3 times' if attempts > max_retries
-
-      retry
-    end
-
-    logger_dir
-  end
-  # private_class_method :gem_dir_with_retry
-end

data/lib/cinnabar/utils.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Cinnabar; end
+
+module Cinnabar::Utils
+  module_function
+
+  # @note require 'rubygems'
+  def gems! = Kernel.require 'rubygems'
+end
+
+module Cinnabar::Utils::OS
+  module_function
+
+  # Returns true if running on Windows (including MSYS/MinGW/Cygwin).
+  #
+  # @param host_os [String]
+  # @return [Boolean]
+  #
+  # @example
+  #   Cinnabar::Utils::OS.windows? #=> true/false
+  def windows?(host_os = RUBY_PLATFORM)
+    host_os.match?(/bccwin|cygwin|djgpp|mingw|mswin|wince/i)
+  end
+
+  # Returns true if running on macOS (Darwin).
+  #
+  # Ruby convention prefers `macos?` over `macOS?`, but we provide both.
+  #
+  # @param host_os [String]
+  # @return [Boolean]
+  #
+  # @example
+  #   Cinnabar::Utils::OS.macos? #=> true/false
+  def macOS?(host_os = RUBY_PLATFORM) # rubocop:disable Naming/MethodName
+    host_os.match?(/darwin/i)
+  end
+
+  # Returns true if running on Linux.
+  #
+  # @param host_os [String]
+  # @return [Boolean]
+  def linux?(host_os = RUBY_PLATFORM)
+    host_os.match?(/linux/i)
+  end
+
+  # Returns true if running under WSL 2
+  #
+  # @param proc_version [String]
+  # @return [Boolean]
+  # @see wsl_1?
+  # @see wsl?
+  #
+  # @example
+  #   Cinnabar::Utils::OS.wsl_2? #=> true/false
+  def wsl_2?(proc_version = nil)
+    proc_version ||= File.read('/proc/version')
+
+    # proc_version.match?(/(?=.*microsoft)(?=.*-WSL)/)
+    proc_version.include?('microsoft') && proc_version.include?('-WSL')
+  rescue StandardError
+    false
+  end
+
+  # Returns true if running under WSL (Windows Subsystem for Linux).
+  def wsl?(proc_version = nil)
+    proc_version ||= File.read('/proc/version')
+    proc_version.match?(/(M|m)icrosoft/)
+  rescue StandardError
+    false
+  end
+
+  # Returns true if running under WSL 1
+  def wsl_1?(proc_version = nil)
+    # wsl 1: Linux version 4.4.0-26100-Microsoft (Microsoft@Microsoft.com) (gcc version 5.4.0 (GCC) ) #7309-Microsoft Fri Jan 01 08:00:00 PST 2016 # rubocop:disable Layout/LineLength
+    proc_version ||= File.read('/proc/version')
+    proc_version.include?('Microsoft')
+  rescue StandardError
+    false
+  end
+end

data/lib/cinnabar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cinnabar
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end

data/lib/cinnabar.rb

@@ -5,7 +5,9 @@
 
 require_relative 'cinnabar/00_pre'
 require_relative 'cinnabar/cmd_runner'
+require_relative 'cinnabar/gem_path' unless defined? Cinnabar::GemPathCore
 require_relative 'cinnabar/net'
 require_relative 'cinnabar/path'
 require_relative 'cinnabar/pipe'
+require_relative 'cinnabar/utils' unless defined? Cinnabar::Utils
 require_relative 'cinnabar/version'

data/misc/firb/bin/firb

@@ -0,0 +1,128 @@
+#!/usr/bin/env -S ruby --disable=gems
+# ====================
+# Depends: ruby (>= 3.1), bat | batcat, eza
+#
+# rubocop:disable Style/GlobalVars
+# rubocop:disable Style/MixinUsage
+# rubocop:disable Style/MultilineBlockChain
+# frozen_string_literal: true
+
+# ====================
+# NOTE
+#   The first launch may be slow because it generates the cache JSON.
+#   Subsequent launches reuse the cache as much as possible for the fastest startup.
+#
+# Usage:
+#   `firb` => Enter irb
+# in IRB:
+#   l           #=> `eza --icons`
+#   ll          #=> `eza --icons -lh`
+#   la          #=> `eza --icons -lah`
+#   cat 'file'  #=> `bat -Pp file`
+#   which :ruby #=> `which ruby`
+#   cdir '~/.cache' #=> `cd ~/.cache; pwd; ls`
+#   pwd         #=> Dir.pwd
+# ====================
+
+Kernel.warn "  ruby:\t#{RUBY_VERSION}" if ARGV.empty?
+
+$ruby_cache_dir = -> {
+  require 'pathname'
+
+  env_dir = ENV['xdg_cache_home'.upcase]
+  case env_dir
+    when nil, ''
+      Pathname(Dir.home).join('.cache/ruby')
+    else
+      Pathname(env_dir).join('ruby')
+  end
+}.call
+
+-> {
+  dir = $ruby_cache_dir.join('lib/cinnabar')
+
+  %w[gem_path utils]
+    .each { require dir.join(_1) }
+}.call
+
+def new_cinnabar_gem_path_class(gems)
+  {
+    cache_dir: $ruby_cache_dir,
+    gems:,
+  }
+    .then(&Cinnabar.new_gem_path_proc)
+end
+
+def require_gems = ->(gems) {
+  new_cinnabar_gem_path_class(gems)
+    .append_load_path!
+
+  gems.each { require _1 }
+}
+
+def start_irb
+  %w[
+    irb rdoc reline
+  ].tap { _1 << 'fiddle' if Cinnabar::Utils::OS.windows? }
+    .then(&require_gems)
+
+  two_spaces = '  '
+  Kernel.warn <<~GEM_VER
+    #{two_spaces}irb:\t#{IRB::VERSION}
+    #{two_spaces}rdoc:\t#{RDoc::VERSION}
+    #{Dir.pwd}
+  GEM_VER
+  IRB.start
+end
+
+def run_ruby_cli
+  require 'rbconfig'
+  ENV['RUBYOPT'] = '--disable=gems'
+  exec RbConfig.ruby, *ARGV
+end
+
+-> {
+  %w[
+    logger
+    sinlog
+    argvise
+    cinnabar
+  ]
+    .then(&require_gems)
+
+  two_spaces = '  '
+  Kernel.warn <<~GEM_VER
+    #{two_spaces}argvise:  #{Argvise::VERSION}
+    #{two_spaces}cinnabar: #{Cinnabar::VERSION}
+    #{two_spaces}sinlog:   #{Sinlog::VERSION}
+  GEM_VER
+}.call
+
+include Cinnabar::FnPipe::Mixin
+include Cinnabar::Downloader::StrMixin
+include Cinnabar::Command::ArrMixin
+include Cinnabar::Command::TaskArrMixin
+include Cinnabar::StrToPath::Mixin
+include Sinlog::Mixin
+include Argvise::HashMixin
+
+# load `which` & `sh-utils`
+-> {
+  gem = 'cinnabar'
+
+  new_cinnabar_gem_path_class([gem])
+    .cache_hash[gem]
+    .last
+    .then { File.expand_path('../misc/firb/lib', _1).to_path }
+    .tap do |dir|
+      %w[which sh_utils]
+        .each { require dir.join(_1) }
+    end
+}.call
+# require_relative '../lib/which'
+# require_relative '../lib/sh_utils'
+
+# ====================
+run_ruby_cli unless ARGV.empty?
+
+start_irb

data/misc/firb/bin/firb.bat

@@ -0,0 +1 @@
+@ruby.exe --disable=gems "%~dpn0" %*

data/misc/firb/bin/firb0

@@ -0,0 +1,80 @@
+#!/usr/bin/env -S ruby --disable=gems
+# ====================
+# Depends: ruby (>= 3.1)
+#
+# rubocop:disable Style/GlobalVars
+# frozen_string_literal: true
+
+# ====================
+# NOTE: call `Cinnabar::Utils.gems!` or `require 'rubygems'` to re-enable `::Gem` module.
+# For faster loading, consider using `gems.then(&require_gems)` instead of `require 'rubygems'`;
+# e.g., `%w[irb rdoc reline].then(&require_gems)`
+#
+# The first run automatically generates a cache JSON, so it may take a little longer.
+# On the second run and beyond, it reuses the cache whenever possible to maximize startup speed.
+#
+# Usage:
+#   - `firb0` => Start IRB
+#   - `firb0 -h` => Display help info
+#   - `firb0 -e "puts 2"` => Equivalent to `ruby -e "puts 2"`, but with `ENV['RUBYOPT'] = '--disable=gems'`
+
+Kernel.warn "  ruby:\t#{RUBY_VERSION}" if ARGV.empty?
+
+$ruby_cache_dir = -> {
+  require 'pathname'
+
+  env_dir = ENV['xdg_cache_home'.upcase]
+  case env_dir
+    when nil, ''
+      Pathname(Dir.home).join('.cache/ruby')
+    else
+      Pathname(env_dir).join('ruby')
+  end
+}.call
+
+-> {
+  dir = $ruby_cache_dir.join('lib/cinnabar')
+
+  %w[gem_path utils]
+    .each { require dir.join(_1) }
+}.call
+
+def new_cinnabar_gem_path_class(gems)
+  {
+    cache_dir: $ruby_cache_dir,
+    gems:,
+  }
+    .then(&Cinnabar.new_gem_path_proc)
+end
+
+def require_gems = ->(gems) {
+  new_cinnabar_gem_path_class(gems)
+    .append_load_path!
+
+  gems.each { require _1 }
+}
+
+def start_irb
+  %w[
+    irb rdoc reline
+  ].tap { _1 << 'fiddle' if Cinnabar::Utils::OS.windows? }
+    .then(&require_gems)
+
+  two_spaces = '  '
+
+  Kernel.warn <<~GEM_VER
+    #{two_spaces}irb:\t#{IRB::VERSION}
+    #{two_spaces}rdoc:\t#{RDoc::VERSION}
+    #{Dir.pwd}
+  GEM_VER
+
+  IRB.start
+end
+
+unless ARGV.empty?
+  require 'rbconfig'
+  ENV['RUBYOPT'] = '--disable=gems'
+  exec RbConfig.ruby, *ARGV
+end
+
+start_irb

data/misc/firb/bin/firb0.bat

@@ -0,0 +1 @@
+@ruby.exe --disable=gems "%~dpn0" %*

data/misc/firb/install-cinnabar.ps1

@@ -0,0 +1,35 @@
+#!/usr/bin/env pwsh
+# Usage:
+#   UNIX:
+#     sh install-cinnabar.ps1
+#   Windows: Copy everything in this file and paste it into PowerShell to run.
+#
+# Description: install cinnabar and copy to cache dir
+# Note: Although the shebang is `pwsh`, you can run it with POSIX sh.
+# Depens: ruby (>= 3.1)
+
+gem install cinnabar
+
+ruby -r pathname -r cinnabar -r fileutils -e "
+  gem = 'cinnabar'
+  env_dir = ENV['xdg_cache_home'.upcase]
+  cache_dir =
+    case env_dir
+      when nil, ''
+        Pathname(Dir.home).join('.cache')
+      else Pathname(env_dir)
+    end
+      .join('ruby')
+      .tap(&:mkpath)
+
+  copy_to_cache_dir = ->src { FileUtils.cp_r src, cache_dir, verbose: true }
+
+  lib_dir = Cinnabar::GemPathCore
+    .find_lib_paths(gem)
+    .first
+
+  firb = File.expand_path('../misc/firb', lib_dir)
+
+  [lib_dir, firb]
+    .each(&copy_to_cache_dir)
+"

data/misc/firb/lib/sh_utils.rb

@@ -0,0 +1,65 @@
+# Depends: bat | batcat, eza
+#
+# frozen_string_literal: true
+
+require_relative 'which'
+
+BAT_CAT_CMD = -> {
+  %w[bat batcat]
+    .each { return [_1, '-Pp'] if which(_1) }
+  ['cat']
+}.call
+
+EXA_LS_CMD = -> {
+  %w[eza exa]
+    .each { return [_1, '--icons=auto'] if which(_1) }
+  ['ls', '--color=auto']
+}.call
+
+# Similar to `cd "/path/to/dir"; pwd; ls`
+def cdir(path = Dir.home)
+  path = path_sym_to_str(path)
+  File
+    .expand_path(path)
+    .then { Dir.chdir _1 }
+  puts Dir.pwd
+  system(*EXA_LS_CMD)
+end
+
+def path_sym_to_str(path)
+  path.is_a?(Symbol) ? path.to_s : path
+end
+
+def run_eza_ls(path = '.', *rest)
+  cmd = EXA_LS_CMD
+  cmd.concat(rest) unless rest.empty?
+  path = path_sym_to_str(path)
+  cmd << File.expand_path(path)
+  puts "\e[9m #{cmd} \e[0m"
+  system(*cmd)
+end
+alias l run_eza_ls
+
+def ll(path = '.', *rest)
+  argv = %w[-l -h]
+  argv.concat(rest) unless rest.empty?
+  run_eza_ls(path, *argv)
+end
+
+def la(path = '.', *rest)
+  argv = %w[-a -l -h]
+  argv.concat(rest) unless rest.empty?
+  run_eza_ls(path, *argv)
+end
+
+def cat(path, *rest)
+  cmd = BAT_CAT_CMD
+  path = path_sym_to_str(path)
+  cmd << File.expand_path(path)
+  cmd.concat(rest) unless rest.empty?
+  system(*cmd)
+end
+
+def pwd
+  Dir.pwd
+end

data/misc/firb/lib/which.rb

@@ -0,0 +1,60 @@
+# rubocop:disable Layout/LineLength
+# rubocop:disable Style/SpecialGlobalVars
+#
+# frozen_string_literal: true
+
+def capture_stdout(command)
+  out = IO.popen(command, 'r', &:read)
+  return nil unless $?.success?
+
+  out
+rescue Errno::ENOENT
+  nil
+end
+
+# @example Linux
+#
+#     which 'ls'
+#        # => ["/usr/bin/ls"]
+#     which :ruby
+#       # => ["/opt/ruby/latest/bin/ruby"]
+#
+# @example Windows
+#
+#     which :cl
+#     # => ["C:\\Program Files\\Microsoft Visual Studio\\18\\Community\\VC\\Tools\\MSVC\\14.50.35717\\bin\\Hostx64\\x64\\cl.exe"]
+def which(cmd) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+  cmd = cmd.to_s if cmd.is_a? Symbol
+  return warn 'Try: show_source your_cmd' unless cmd.is_a?(String)
+
+  probes =
+    if Cinnabar::Utils::OS.windows?
+      %w[where which command]
+    else
+      %w[which command where]
+    end
+
+  strip_cmds = ->(out) {
+    out
+      .to_s
+      .lines
+      .map(&:strip)
+      .reject(&:empty?)
+  }
+
+  probes.each do |probe|
+    out =
+      case probe
+        when 'command'
+          capture_stdout %w[sh -c].push("command -v #{cmd}")
+        else
+          capture_stdout [probe, cmd]
+      end
+    next if out.nil? || out.empty?
+
+    cmds = strip_cmds[out]
+    return cmds unless cmds.empty?
+  end
+
+  nil
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cinnabar
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - 2moe
@@ -37,10 +37,19 @@ files:
 - lib/cinnabar.rb
 - lib/cinnabar/00_pre.rb
 - lib/cinnabar/cmd_runner.rb
+- lib/cinnabar/gem_path.rb
 - lib/cinnabar/net.rb
 - lib/cinnabar/path.rb
 - lib/cinnabar/pipe.rb
+- lib/cinnabar/utils.rb
 - lib/cinnabar/version.rb
+- misc/firb/bin/firb
+- misc/firb/bin/firb.bat
+- misc/firb/bin/firb0
+- misc/firb/bin/firb0.bat
+- misc/firb/install-cinnabar.ps1
+- misc/firb/lib/sh_utils.rb
+- misc/firb/lib/which.rb
 homepage: https://github.com/2moe/cinnabar
 licenses:
 - Apache-2.0