cinnabar 0.0.0 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6647629512489671373fd91ffdd165fcdc08306caad030e7ad827adefb070bf5
-  data.tar.gz: 24e45eca6665b1a715dc9b7cd58547b6e6bb4ffbc1777a6250c8d55f537acaed
+  metadata.gz: 0d07b1f0ca422a414fa67b7017920940bd12eadfe4f2d104de088e6ce67c9def
+  data.tar.gz: a2065bf84722d56727ce1d12602ef3d498d0026ba420f3e213ce5b9d24fdd558
 SHA512:
-  metadata.gz: 9de983869bf035c25dcadaab1f4b803a46e2dabc48e1d5bfe42ca4314006f9b13f1aa7bebb37fbbfb226c266fd0689dec57b15c0957735137349e9b9b0bf2a79
-  data.tar.gz: 53d3feb704e7004cb4ba194854186a543fe0d42a9fca1abe5a689aba9464bac1ad7d6f30cdd83214710dd6543a1a2be260b3ea6568d459ea5b6bfa77358a6cc4
+  metadata.gz: ca95b7d444e89dd2c169d16b1255779c482dd4ed36bda09f7050a2d6c99f1049e27e52c660b4a2c35f0045b0c668a2954f7b982006257f3f74dcdb0a71a9d03c
+  data.tar.gz: 7da5135f3602cf662ea4bbc53e86cada66dc5d5601223600beaf53ac56d05262d7bb518a18cbfa2c22fc9128184032882c885e2906c438c3a7c7a00de8c3a69f

data/.rubocop.yml

@@ -36,7 +36,7 @@ Layout/CaseIndentation:
   EnforcedStyle: end
   IndentOneStep: true
 Layout/MultilineMethodCallIndentation:
-  EnforcedStyle: indented_relative_to_receiver
+  EnforcedStyle: indented
 
 
 Naming/AsciiIdentifiers:

data/.yardopts

@@ -0,0 +1,4 @@
+--markup markdown
+--title 'Cinnabar'
+--protected
+--no-private

data/docs/ChangeLog.md

@@ -0,0 +1,5 @@
+# ChangeLog
+
+## v0.0.2 (2026-01-05)
+
+- fix ruby v4.0.0 compatibility

data/docs/Readme-zh.md

@@ -24,41 +24,9 @@
 2.  朱砂有毒。这个项目是为了 **猛、糙、快** (a.k.a. *Dirty and Quick*) 的目的而开发的，可能会产生意料之外的副作用（它并非完全无害）。
 3.  朱砂是一种硫化汞 (HgS) 的矿物，呈深红色，而 Ruby 也是一种深红色的宝石。给一个 Ruby 项目取名为 “Cinnabar（朱砂）” 非常贴切。
 
-## 快速上手
+## API DOC
 
-Github Actions for cinnabar
+![ClassDiagram](../misc/assets/svg/ClassDiagram.svg)
 
-```yaml
-env:
-  # Speeds up script startup by disabling RubyGems
-  RUBYOPT: "--disable=gems"
-  default_ci_shell: ruby cinnabar/ci.rb {0}
+- Github Pages: <https://2moe.github.io/cinnabar>
 
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        shell: ${{env.default_ci_shell}}
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: clone cinnabar
-        uses: actions/checkout@v6
-        with:
-          repository: 2moe/cinnabar
-          path: cinnabar
-          ref: v0.0.0
-
-      - name: (example) run cargo command
-        run: |
-          {
-            cargo: (),
-            build: (),
-            profile: 'release',
-            verbose: true,
-            target: 'x86_64-unknown-linux-musl'
-          }
-            .to_argv
-            .run
-```

data/docs/Readme.md

@@ -24,6 +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
+
+![ClassDiagram](../misc/assets/svg/ClassDiagram.svg)
+
+- Github Pages: <https://2moe.github.io/cinnabar>
+
 ## Quick Start
 
 Github Actions for cinnabar
@@ -33,6 +39,8 @@ env:
   # Speeds up script startup by disabling RubyGems
   RUBYOPT: "--disable=gems"
   default_ci_shell: ruby cinnabar/ci.rb {0}
+  # optional values: debug, info, warn, error, fatal, unknown
+  RUBY_LOG: debug
 
 jobs:
   build:
@@ -48,7 +56,7 @@ jobs:
         with:
           repository: 2moe/cinnabar
           path: cinnabar
-          ref: v0.0.0
+          ref: v0.0.2
 
       - name: (example) run cargo command
         run: |
@@ -60,5 +68,91 @@ jobs:
             target: 'x86_64-unknown-linux-musl'
           }
             .to_argv
-            .run
+            .run_cmd
+```
+
+## Examples
+
+### Command Runner
+
+#### `.run` + pass stdin data
+
+```ruby,yaml
+- run: |
+    opts = { stdin_data: "Hello", allow_failure: true }
+    stdout = %w[wc -m].run(opts:)
+
+    stdout.to_i == 5 #=> true
+```
+
+#### `.async_run` + log
+
+```ruby,yaml
+- run: |
+    'building wasi file...'.log_dbg
+    task = {
+      cargo: (),
+      b: (),
+      r: true,
+      target: 'wasm32-wasip2'
+    } .to_argv
+      .async_run
+
+    # log_dbg, log_info, log_warn, log_err, log_fatal, log_unk
+    "You can now do other things without waiting for
+    the process to complete.".log_dbg
+
+    stdout, status = task.wait_with_output
+    stdout.log_info
+    raise "wasi" unless status.success?
+```
+
+#### `.async_run` + pass stdin data
+
+```ruby,yaml
+- run: |
+    stdin_data = <<~'QMP_JSON'
+      { "execute":"qmp_capabilities" }
+      { "execute":"query-cpu-model-expansion",
+        "arguments":{"type":"full","model":{"name":"host"}} }
+      { "execute":"quit" }
+    QMP_JSON
+
+    # opts = { stdin_data:, stdin_binmode: false }
+    opts = { stdin_data: }
+
+    accel = %w[kvm hvf whpx].join ':'
+    task = {
+      'qemu-system-x86_64': (),
+      machine: "accel=#{accel}",
+      cpu: 'host',
+      display: 'none',
+      nodefaults: true,
+      no_user_config: true,
+      qmp: 'stdio',
+    } .to_argv_bsd
+      .async_run(opts:)
+
+    stdout, status = task.wait_with_output
+    stdout.log_info if status.success?
+```
+
+### Downloader
+
+```ruby,yaml
+- run: |
+    url = 'https://docs.ruby-lang.org/en/master'
+    url.download
+    # OR: url.download({out_dir: "/tmp", file_name: "index.html"})
+```
+
+### Function Pipe
+
+```ruby,yaml
+- run: |
+    upper = ->s { s.upcase }
+
+    'Foo'
+      .▷(upper)
+      .▷ :puts #=> "FOO"
 ```

data/lib/cinnabar/00_pre.rb

@@ -2,14 +2,13 @@
 
 # Define Cinnabar first to prevent errors when creating Cinnabar::SubMod
 # (compact ClassAndModuleChildren)
-#
 # ------------------
 
+# @see https://github.com/2moe/cinnabar
 module Cinnabar; end
 
+require 'pathname'
+
 # To ensure compatibility with "--disable=gems" (allowing users to pre-require),
 # add conditional checks before requiring these libraries.
 require 'sinlog' unless defined? Sinlog::VERSION
-# require 'argvise' unless defined? Argvise::VERSION
-
-require 'pathname'

data/lib/cinnabar/cmd_runner.rb

@@ -1,162 +1,511 @@
+# typed: false
 # frozen_string_literal: true
 
 module Cinnabar::Command
   module_function
 
+  require 'open3'
   using Sinlog::Refin
 
-  # This lambda function is capable of running system command.
+  # Executes the command synchronously (blocking) and returns its standard output.
   #
-  # = Example
+  # @raise [RuntimeError] when `allow_failure: false` and the process exits with non-zero status
   #
-  #     using Cinnabar::FnPipe::Refin
+  # @example pass env
   #
   #     Cmd = Cinnabar::Command
-  #     %w[sleep 3].▷ Cmd.run
-  def run
-    ->(array) do
-      'Running system cmd'.log_dbg
-      array.log_info
-      success = system(*array)
-      Kernel.raise "Command failed: #{array.join(' ')}" unless success
+  #     cmd_arr = %w[sh -c] << 'printf $WW'
+  #     env_hash = {WW: 2}
+  #     opts = {allow_failure: true}
+  #     output = Cmd.run(cmd_arr, env_hash, opts:)
+  #     output.to_i == 2 #=> true
+  #
+  # @example pass stdin data
+  #
+  #     opts = {stdin_data: "Hello\nWorld\n"}
+  #     output = Cinnabar::Command.run(%w[wc -l], opts:)
+  #     output.to_i == 2 #=> true
+  #
+  # @param cmd_arr [Array<String>] The command and its arguments (e.g., `%w[printf hello]`).
+  # @param env_hash [#to_h] Environment variables to pass to the command.
+  # @param opts [Hash]
+  #
+  #   - Only the `:allow_failure` is extracted and handled explicitly;
+  #   - all other keys are passed through to **Open3.capture2** unchanged.
+  #
+  # @option opts [Boolean] :allow_failure
+  #   Indicates whether the command is allowed to fail.
+  #
+  # @return [String, nil] the standard output of the command.
+  #
+  # @see async_run
+  def run(cmd_arr, env_hash = nil, opts: {}) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    'Running and capturing the output of a system command.'.log_dbg
+    cmd_arr.log_info
+    "opts: #{opts}".log_dbg
+
+    allow_failure = opts.delete(:allow_failure) || false
+
+    final_env = normalize_env(env_hash)
+
+    begin
+      stdout, status =
+        if final_env.nil?
+          Open3.capture2(*cmd_arr, opts)
+        else
+          Open3.capture2(final_env, *cmd_arr, opts)
+        end
+    rescue StandardError => e
+      Kernel.raise e unless allow_failure
+      e.log_err
+      return stdout
     end
+
+    return stdout if status.success?
+
+    err_msg = "Command failed: #{cmd_arr.join(' ')}"
+    Kernel.raise err_msg unless allow_failure
+
+    err_msg.log_err
+    stdout
   end
 
-  # Lambda that runs system command in the background.
+  # Executes a system command using Ruby's `Kernel.system`.
   #
-  # @raise [RuntimeError] if the process exits with non-zero status
+  # It runs the command synchronously, blocks until completion, and does not capture stdout or stderr.
   #
-  # = Example
+  # @param cmd_arr [Array<String>] The command and its arguments as an array,
+  #   e.g., `%w[ls -lh]`.
+  #
+  # @param env_hash [#to_h] Environment variables to pass to the command.
+  # @param opts [Hash]
+  #
+  #   - Only the `:allow_failure` is extracted and handled explicitly;
+  #   - all other keys are passed through to `Kernel.system` unchanged.
+  #
+  # @option opts [Boolean] :allow_failure
+  #   Indicates whether the command is allowed to fail.
+  #   If true, the method will return false instead of raising an exception when the
+  #   command exits with a non-zero status.
+  #
+  # @see https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Options
+  #
+  # @example pwd
   #
   #     Cmd = Cinnabar::Command
-  #     pid = %w[sleep 5].then(&Cmd.run_in_bg)
-  def run_in_bg
-    ->(array) do
-      'Running system cmd in the background'.log_dbg
-      array.log_info
-      Process.spawn(*array)
+  #     opts = {chdir: '/tmp', allow_failure: true}
+  #     Cmd.run_cmd(%w[pwd], opts:)
+  #
+  # @example pass env
+  #
+  #     Cmd = Cinnabar::Command
+  #     cmd_arr = %w[sh -c] << 'printf $WW'
+  #     env_hash = {WW: 2}
+  #     Cmd.run_cmd(cmd_arr, env_hash)
+  #
+  # @return [Boolean] Returns true if the command succeeds (exit status 0),
+  #   or false if it fails and `allow_failure` is true.
+  # @raise [RuntimeError] Raises an error if the command fails and `allow_failure` is false.
+  def run_cmd(cmd_arr, env_hash = nil, opts: {})
+    'Running system command'.log_dbg
+    cmd_arr.log_info
+    "opts: #{opts}".log_dbg
+
+    allow_failure = opts.delete(:allow_failure) || false
+    exception = !allow_failure
+    "exception: #{exception}".log_dbg
+    options = opts.merge({ exception: })
+
+    final_env = normalize_env(env_hash)
+    if final_env.nil?
+      Kernel.system(*cmd_arr, options)
+    else
+      Kernel.system(final_env, *cmd_arr, options)
     end
   end
 
-  # ---------------
+  # @param hash [#to_h]
+  # @return [Hash{String => String}, nil] a hash where both keys and values are strings
+  def normalize_env(hash)
+    return nil if hash.nil?
+    return nil if hash.respond_to?(:empty?) && hash.empty?
+
+    hash.to_h { |k, v| [k.to_s, v.to_s] }
+      .tap { "normalized_env:#{_1}".log_dbg }
+  end
 
-  # Lambda that waits for a child process to complete and checks its status.
+  # Launch a command asynchronously (non-blocking) and return its stdout stream and process waiter.
   #
-  # This method requires the child process to exit with a successful status;
-  # otherwise, it will raise an error.
+  # This is a sugar over **Open3.popen2**, intended to start a subprocess
+  # and **immediately** hand back:
   #
-  # = Example
+  #    1. an `IO` for reading the command's stdout, and
+  #    2. a `Process::Waiter` (a thread-like object) that can be awaited later.
   #
-  #     using Cinnabar::FnPipe::Refin
+  # - If `:stdin_data` is provided, the data will be written to
+  #   the child's stdin and the stdin will be closed.
+  # - When `:stdin_data` is absent, stdin is simply closed and
+  #   the method returns immediately without blocking on output.
+  #
+  # @param cmd_arr [Array<String>] The command and its arguments (e.g., `%w[printf hello]`).
+  # @param env_hash [#to_h] Optional environment variables;
+  #   keys/values will be normalized by {#normalize_env} before being passed to the child.
+  #
+  # @param opts [Hash] Additional options.
+  #
+  #   - Only the following keys are extracted and handled explicitly;
+  #     - :stdin_data
+  #     - :binmode
+  #     - :stdin_binmode
+  #     - :stdout_binmode
+  #
+  #   all other keys are passed through to **Open3.popen2** unchanged.
+  #
+  # @option opts [String, #readpartial] :stdin_data
+  #   Data to write to the child's stdin. If it responds to `#readpartial`,
+  #   it will be streamed via **IO.copy_stream**;
+  #
+  # @option opts [Boolean] :binmode
+  #   When `true`, set both stdin and stdout to binary mode (useful for binary data).
+  #
+  # @option opts [Boolean] :stdin_binmode
+  #   Sets only stdin to binary mode.
+  #
+  # @option opts [Boolean] :stdout_binmode
+  #   Sets only stdout to binary mode.
+  #
+  # @return [Array(IO, Process::Waiter)] A pair `[stdout_io, waiter]`:
+  #
+  #   - `stdout_io` is an `IO` for reading **stdout**
+  #   - `waiter` is a `Process::Waiter`;
+  #     - call `waiter.value` to get `Process::Status`;
+  #     - or `waiter.join` to block until the process exits.
+  #
+  # @raise [StandardError] Reraises any non-`Errno::EPIPE` exception encountered while writing to stdin.
+  #   `Errno::EPIPE` is logged and swallowed.
+  #
+  # @example start a process and later wait for it
+  #
+  #     Cmd = Cinnabar::Command
+  #     stdout_fd, waiter = Cmd.async_run(['sh', '-c', 'echo hello; sleep 1; echo done'])
+  #
+  #     output, status = Cmd.wait_with_output(stdout_fd, waiter)
+  #
+  # @example pass stdin data
   #
   #     Cmd = Cinnabar::Command
-  #     %w[sleep 3]
-  #       .▷(Cmd.run_in_bg) #=> pid
-  #       .▷(Cmd.wait_task)
-  #
-  def wait_task
-    ->(pid) do
-      "wait pid: #{pid}".log_dbg
-      Process.wait(pid)
-      status = $? # rubocop:disable Style/SpecialGlobalVars
-      "child_status: #{status}".log_dbg
-      Kernel.raise %(Command failed with "#{status}") unless status.success?
+  #     opts = {stdin_data: "Run in the background" }
+  #     io_and_waiter = Cmd.async_run(%w[wc -m], opts:)
+  #
+  #     output, status = Cmd.wait_with_output(*io_and_waiter)
+  #     status.success?   #=> true
+  #     output.to_i == 21 #=> true
+  #
+  # @see wait_with_output
+  # @see run
+  def async_run(cmd_arr, env_hash = nil, opts: {}) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/PerceivedComplexity,Metrics/CyclomaticComplexity
+    "Asynchronously executing system command: #{cmd_arr}".log_dbg
+    "opts: #{opts}".log_dbg
+
+    stdin_data = opts.delete(:stdin_data)
+    binmode = opts.delete(:binmode)
+    stdin_binmode = opts.delete(:stdin_binmode)
+    stdout_binmode = opts.delete(:stdout_binmode)
+
+    'async_run() does not support the :allow_failure option.'.log_warn if opts.delete(:allow_failure)
+
+    final_env = normalize_env(env_hash)
+
+    stdin, stdout, waiter =
+      if final_env.nil?
+        Open3.popen2(*cmd_arr, opts)
+      else
+        Open3.popen2(final_env, *cmd_arr, opts)
+      end
+
+    if binmode
+      stdin.binmode
+      stdout.binmode
+    else
+      stdin.binmode if stdin_binmode
+      stdout.binmode if stdout_binmode
+    end
+
+    # Non-blocking: no stdin to write; return immediately
+    unless stdin_data
+      stdin.close
+      return [stdout, waiter]
+    end
+
+    begin
+      if stdin_data.respond_to? :readpartial
+        IO.copy_stream(stdin_data, stdin)
+      else
+        stdin.write stdin_data
+      end
+    rescue Errno::EPIPE => e
+      e.log_err
+    rescue StandardError => e
+      "Failed to write stdin data: #{e}".log_err
+      Kernel.raise e
+    ensure
+      stdin.close
     end
+    [stdout, waiter]
+  end
+
+  # Waits for a process to finish and reads all remaining output from its stdout.
+  #
+  # @param io_fd [IO] The IO object connected to the process's stdout (or combined stdout & stderr).
+  # @param waiter [Process::Waiter] The waiter thread returned by **Open3.popen2** or **Open3.popen2e**.
+  #
+  # @return [Array(String, Process::Status)] A two-element array:
+  #
+  #   - The full output read from `io_fd`.
+  #   - The **Process::Status** object representing the process's exit status.
+  #
+  # @example Wait for process and capture output
+  #
+  #   require 'sinlog'
+  #   using Sinlog::Refin
+  #
+  #   Cmd = Cinnabar::Command
+  #
+  #   fd, waiter = %w[ruby -e].push('sleep 2; puts "OK"')
+  #                 .then { Cmd.async_run(_1) }
+  #
+  #   "You can now do other things without waiting for the process to complete.".log_dbg
+  #
+  #   "blocking wait".log_info
+  #   output, status = Cmd.wait_with_output(fd, waiter)
+  #
+  #   "Exit code: #{status.exitstatus}".log_warn unless status.success?
+  #   "Output:\n#{output}".log_info
+  #
+  # @note This method blocks until the process exits and all output is read.
+  # @see async_run
+  def wait_with_output(io_fd, waiter)
+    status = waiter.value
+    output = io_fd.read
+    io_fd.close
+    [output, status]
   end
-  # ---------------
 end
 
 module Cinnabar::Command
-  module ArrayExt
-    def run
-      Cinnabar::Command.run.call(self)
+  # The foundation of {ArrRefin} and {ArrMixin}
+  # @see Cinnabar::Command.run
+  # @see Cinnabar::Command.async_run
+  # @see Cinnabar::Command.run_cmd
+  module ArrExt
+    # Executes the command synchronously (blocking) and returns its standard output.
+    #
+    # @note self [`Array<String>`]: The command and its arguments (e.g., `%w[printf hello]`).
+    #
+    # @param env_hash [#to_h] Environment variables to pass to the command.
+    # @param opts [Hash]
+    #
+    #   - Only the `:allow_failure` is extracted and handled explicitly;
+    #   - all other keys are passed through to **Open3.capture2** unchanged.
+    #
+    # @raise [StandardError] when `allow_failure: false` and the process exits with non-zero status
+    #
+    # @return [String, nil] the standard output of the command.
+    # @see Cinnabar::Command.run
+    #
+    # @example pass stdin data
+    #
+    #     using Cinnabar::Command::ArrRefin
+    #     # OR: include Cinnabar::Command::ArrMixin
+    #
+    #     opts = {allow_failure: true, stdin_data: "Hello\nWorld\n"}
+    #     output = %w[wc -l].run(opts:)
+    #     output.to_i == 2 unless output.nil? #=> true
+    #
+    # @note This method blocks until the process completes.
+    def run(env_hash = nil, opts: {})
+      Cinnabar::Command.run(self, env_hash, opts:)
+    end
+
+    # Starts a command asynchronously using this `Array<String>`.
+    #
+    # @note self [`Array<String>`]: The command and its arguments (e.g., `%w[printf hello]`).
+    #
+    # @param env_hash [#to_h] Optional environment variables.
+    # @param opts [Hash]
+    #
+    # @see Cinnabar::Command.async_run
+    #
+    # @return [Array(IO, Process::Waiter)] a pair `[stdout_io, waiter]`
+    #
+    # @example pass stdin data
+    #
+    #     using Cinnabar::Command::ArrRefin
+    #     # OR: include Cinnabar::Command::ArrMixin
+    #
+    #     opts = {stdin_data: "Hello\nWorld\n"}
+    #     io_and_waiter = %w[wc -l].async_run(opts:)
+    #     output, status = Cinnabar::Command.wait_with_output *io_and_waiter
+    #     output.to_i == 2 #=> true
+    def async_run(env_hash = nil, opts: {})
+      Cinnabar::Command.async_run(self, env_hash, opts:)
     end
 
-    # Spawns system command (runs in the background)
-    def run_in_bg
-      Cinnabar::Command.run_in_bg.call(self)
+    # @note self [`Array<String>`]: The command and its arguments (e.g., `%w[printf hello]`).
+    #
+    # @example pwd
+    #
+    #     using Cinnabar::Command::ArrRefin
+    #     # OR: include Cinnabar::Command::ArrMixin
+    #
+    #     opts = {chdir: '/tmp', allow_failure: true}
+    #     status = %w[pwd].run_cmd(opts:)
+    #
+    # @example pass env
+    #
+    #     using Cinnabar::Command::ArrRefin
+    #
+    #     env_hash = {WW: 2}
+    #     status =
+    #        %w[sh -c]
+    #          .push('printf $WW')
+    #          .run_cmd(env_hash)
+    #
+    #     status == true
+    #
+    # @return [Boolean]
+    # @see Cinnabar::Command.run_cmd
+    def run_cmd(env_hash = nil, opts: {}) # rubocop:disable Style/OptionalBooleanParameter
+      Cinnabar::Command.run_cmd(self, env_hash, opts:)
     end
   end
 
   # ---------------------
 
-  # monkey patching: Array#run, Array#run_in_bg
+  # Monkey patching: Array#run, Array#async_run, Array#run_cmd
+  #
+  # @example run
+  #
+  #     include Cinnabar::Command::ArrMixin
+  #
+  #     stdout = %w[printf World].run
+  #     stdout == "World" #=> true
+  #
+  # @example async_run
+  #
+  #     include Cinnabar::Command::ArrMixin
+  #
+  #     fd, waiter = %w[ruby -e].push('sleep 2; puts "OK"').async_run
+  #
+  #     status = waiter.value
+  #     status.success?  #=> true
+  #
+  #     output = fd.read.chomp
+  #     fd.close
+  #     output == 'OK' #=> true
   #
-  # == Example
+  # @example async_run + wait_with_output
   #
   #     include Cinnabar::Command::ArrMixin
+  #     include Cinnabar::Command::TaskArrMixin
   #
-  #     %w[ls -l].run
+  #     task = %w[ruby -e].push('sleep 2; puts "OK"').async_run
   #
-  #     pid = %w[sleep 3].run_in_bg
+  #     output, status = task.wait_with_output
+  #
+  #     status.success?  #=> true
+  #     output.chomp == 'OK' #=> true
+  #
+  # @see ArrExt
   module ArrMixin
-    def self.included(_host) = ::Array.include ArrayExt
+    def self.included(_host) = ::Array.include ArrExt
   end
 
-  # Refinements: Array#run, Array#run_in_bg
+  # Refinements: Array#run, Array#async_run, Array#run_cmd
   #
-  # = Examples
-  #
-  # == Simple
+  # @example run
   #
   #     using Cinnabar::Command::ArrRefin
   #
-  #     %w[ls -l].run
-  #     #=> execute system('ls', '-l')
+  #     stdout =
+  #       %w[ruby -e]
+  #         .push('print 2')
+  #        .run
+  #
+  #     stdout.to_i == 2   #=> true
   #
-  # == Argvise + run_in_bg
+  # @example run(opts:)
   #
   #     using Cinnabar::Command::ArrRefin
+  #
+  #     opts = { allow_failure: true, stdin_data: "Hello" }
+  #
+  #     stdout = %w[wc -m].run(opts:)
+  #
+  #     stdout.to_i == 5   #=> true
+  #
+  # @example Argvise + run_async
+  #
+  #     require 'argvise'
+  #     require 'cinnabar'
+  #
   #     using Argvise::HashRefin
+  #     using Cinnabar::Command::ArrRefin
+  #     using Cinnabar::Command::TaskArrRefin
   #
-  #     pid = {
+  #     task = {
   #       cargo: (),
-  #       run: (),
+  #       b: (),
+  #       r: true,
   #       target: "wasm32-wasip2"
-  #     }.to_argv.run_in_bg
-  #     #=> execute Process.spawn('cargo', 'run', '--target', 'wasm32-wasip2')
+  #     }
+  #       .to_argv
+  #       .run_async
+  #
+  #     stdout, status = task.wait_with_output
+  #     status.success? #=> true
   #
+  # @see ArrExt
   module ArrRefin
     refine ::Array do
-      import_methods ArrayExt
+      import_methods ArrExt
     end
   end
 end
 
 module Cinnabar::Command
-  module IntegerExt
-    def wait_task
-      Cinnabar::Command.wait_task.call(self)
-    end
-  end
-
-  # ---------------------
-
-  # Monkey Patching: Integer#wait_task
+  # The foundation of {TaskArrRefin} and {TaskArrMixin}
+  # @see Cinnabar::Command.wait_with_output
   #
-  # == Example
+  # @example simple
   #
-  #     include Cinnabar::Command::IntMixin
+  #     using Cinnabar::Command::ArrRefin
+  #     using Cinnabar::Command::TaskArrRefin
+  #     # OR: include Cinnabar::Command::TaskArrMixin
+  #
+  #     task = %w[ruby -e]
+  #             .push('sleep 2; puts "OK"')
+  #             .async_run
   #
-  #     pid = %w[sleep 3].run_in_bg
-  #     p "wait 3s"
-  #     pid.wait_task
-  module IntMixin
-    def self.included(_host) = ::Integer.include IntegerExt
+  #     stdout, status = task.wait_with_output
+  #     status.success? #=> true
+  module TaskArrExt
+    def wait_with_output
+      Cinnabar::Command.wait_with_output(*self)
+    end
   end
 
-  # Refinement: Integer#wait_task
-  #
-  # == Example
-  #
-  #     using Cinnabar::Command::IntRefin
-  #
-  #     pid = %w[sleep 3].run_in_bg
-  #     p "wait 3s"
-  #     pid.wait_task
-  module IntRefin
-    refine ::Integer do
-      import_methods IntegerExt
+  # Refinement: Array#wait_with_output
+  # @see TaskArrExt
+  module TaskArrRefin
+    refine ::Array do
+      import_methods TaskArrExt
     end
   end
+
+  # Monkey Patching: Array#wait_with_output
+  # @see TaskArrExt
+  module TaskArrMixin
+    def self.included(_host) = ::Array.include TaskArrExt
+  end
 end

data/lib/cinnabar/net.rb

@@ -5,19 +5,33 @@ module Cinnabar::Downloader
 
   require 'open-uri'
 
-  # == Example
+  DEFAULT_DL_OPTS = {
+    out_dir: 'tmp', file_name: nil,
+  }.freeze
+
+  # @example
   #
   #     url = 'https://docs.ruby-lang.org/en/3.4/OpenURI.html'
   #     opts = { out_dir: "tmp", file_name: "doc.html" }
   #     DL = Cinnabar::Downloader
   #     DL.download(url, opts)
   #
-  # == Params
+  # @param url [String] e.g., **https://url.local**
+  #
+  # @param opts [Hash] Options for customizing the download behavior.
+  #   e.g., `{out_dir: 'download', file_name: nil, headers: {'User-Agent' => "aria2/1.37.0"}}`
   #
-  # - url: [String] e.g., https://url.local
-  # - opts: [Hash] e.g., `{out_dir: 'download', file_name: nil, headers: {'User-Agent' => "aria2/1.37.0"}}`
-  def download(url, opts)
+  # @option opts [String] :out_dir
+  #   Directory where the downloaded file will be saved.
+  # @option opts [String, nil] :file_name
+  #   Name of the output file. If nil, it will be inferred from the URL.
+  # @option opts [Hash{String => String}] :headers
+  #   Optional HTTP headers to include in the request.
+  # @return [Integer]
+  def download(url, opts = {})
+    opts = DEFAULT_DL_OPTS.merge(opts)
     out_dir, file_name, headers = opts.values_at(:out_dir, :file_name, :headers)
+    out_dir = '.' if out_dir.nil?
 
     headers = build_headers(headers)
     parsed_url = Kernel.URI(url)
@@ -30,7 +44,7 @@ module Cinnabar::Downloader
       .then { IO.copy_stream(_1, file_path.to_s) }
   end
 
-  # => ::Hash
+  # @return [Hash]
   def build_headers(headers)
     base_headers = {
       'User-Agent' => 'Mozilla/5.0 (Linux; aarch64 Wayland; rv:138.0) Gecko/20100101 Firefox/138.0',
@@ -38,7 +52,7 @@ module Cinnabar::Downloader
     base_headers.merge(headers || {}).transform_keys(&:to_s)
   end
 
-  # => ::String
+  # @return [String]
   def determine_filename(file_name, parsed_url)
     filename = file_name || File.basename(parsed_url.path || '')
     case filename.strip
@@ -47,7 +61,7 @@ module Cinnabar::Downloader
     end
   end
 
-  # => Kernel.Pathname
+  # @return [Pathname]
   def setup_file_path(out_dir, file_name)
     Kernel.Pathname(out_dir)
       .tap(&:mkpath)
@@ -56,37 +70,53 @@ module Cinnabar::Downloader
 end
 
 module Cinnabar::Downloader
-  module StringExt
-    def download(out_dir: 'tmp', file_name: nil, headers: {})
-      Cinnabar::Downloader.download(self, { out_dir:, file_name:, headers: })
+  # The foundation of {StrRefin} and {StrMixin}
+  module StrExt
+    # @see Cinnabar::Downloader.download
+    #
+    # @param opts [Hash] Options for customizing the download behavior.
+    #   e.g., `{out_dir: 'download', file_name: nil, headers: {'User-Agent' => "aria2/1.37.0"}}`
+    #
+    # @option opts [String] :out_dir
+    # @option opts [String, nil] :file_name
+    # @option opts [Hash{String => String}] :headers
+    # @return [Integer]
+    def download(opts = {})
+      Cinnabar::Downloader.download(self, opts)
     end
   end
 
   # -------------
 
-  # = Example
+  # @example
   #
   #     include Cinnabar::Downloader::StrMixin
   #
-  #     url = 'https://docs.ruby-lang.org'
+  #     url = 'https://docs.ruby-lang.org/en/master'
   #
   #     url.download
-  #     # OR: url.download(out_dir: "tmp", file_name: "custom.html")
+  #     # OR: url.download({out_dir: "tmp", file_name: "custom.html"})
+  #
+  # @see Cinnabar::Downloader.download
+  # @see StrExt
   module StrMixin
-    def self.included(_host) = ::String.include StringExt
+    def self.included(_host) = ::String.include StrExt
   end
 
-  # = Example
+  # @example
   #
   #     using Cinnabar::Downloader::StrRefin
   #
-  #     url = 'https://docs.ruby-lang.org/en/master/OpenURI.html'
+  #     url = 'https://docs.ruby-lang.org/en/master'
   #
   #     url.download
-  #     # OR: url.download(out_dir: "/tmp", file_name: "index.html")
+  #     # OR: url.download({out_dir: "/tmp", file_name: "index.html"})
+  #
+  # @see Cinnabar::Downloader.download
+  # @see StrExt
   module StrRefin
     refine ::String do
-      import_methods StringExt
+      import_methods StrExt
     end
   end
 end

data/lib/cinnabar/path.rb

@@ -0,0 +1,253 @@
+# 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}.
+  #
+  # 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)`
+  #
+  # @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) }
+end
+
+# Adds `String#to_path` as a convenience helper to convert strings into {Kernel.Pathname}.
+#
+# This module supports two integration styles:
+#
+# - {Cinnabar::StrToPath::Mixin}: globally extends {String} (monkey patch).
+# - {Cinnabar::StrToPath::Refin}: lexically-scoped extension via refinements.
+#
+# @note This feature relies on Ruby's {Pathname} class.
+#   Make sure `require "pathname"` is loaded before calling `to_path`.
+module Cinnabar::StrToPath
+  # Implementation of the `#to_path` method intended to be mixed into {String}.
+  module Ext
+    # Convert the receiver (a String) into a {Pathname}.
+    #
+    # @return [Pathname] `Pathname(self)`
+    #
+    # @example
+    #
+    #     "lib".to_path
+    #     #=> #<Pathname:lib>
+    def to_path = ::Kernel.Pathname(self)
+  end
+
+  # This is a "mixin switch": `include Cinnabar::StrToPath::Mixin` will modify
+  # {::String} for the entire process (i.e., a monkey patch).
+  #
+  # @note Side effect: this will affect *all* strings in the process, including
+  #   third-party code. If you want scoped behavior, prefer {Refin}.
+  #
+  # @example
+  #
+  #     include Cinnabar::StrToPath::Mixin
+  #
+  #     __dir__.to_path
+  #     # Same as `Pathname(__dir__)`
+  module Mixin
+    # Hook invoked when this module is included.
+    #
+    # @param _host [Module] the including host (unused)
+    # @return [void]
+    def self.included(_host) = ::String.include Ext
+  end
+
+  # Adds `String#to_path` via Ruby refinements (lexically scoped).
+  #
+  # This avoids global monkey patches. The method is only visible within scopes
+  # where `using Cinnabar::StrToPath::Refin` is active.
+  #
+  # @example
+  #
+  #     using Cinnabar::StrToPath::Refin
+  #
+  #     __dir__.to_path
+  #     # Same as `Pathname(__dir__)`
+  module Refin
+    # Refinement for {String} to import {Ext#to_path}.
+    refine ::String do
+      import_methods Ext
+    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/pipe.rb

@@ -17,7 +17,7 @@ module Cinnabar::FnPipe
 end
 
 module Cinnabar::FnPipe
-  module ObjectExt
+  module Ext
     def ▷(other) # rubocop:disable Naming/MethodName
       Cinnabar::FnPipe.▷(self, other)
     end
@@ -29,7 +29,7 @@ module Cinnabar::FnPipe
   #
   # Monkey Patching: Object#▷
   #
-  # = Example
+  # @example
   #
   #     include Cinnabar::FnPipe::Mixin
   #
@@ -40,14 +40,14 @@ module Cinnabar::FnPipe
   #     2.▷ :puts
   #         #=> 2
   module Mixin
-    def self.included(_host) = ::Object.include ObjectExt
+    def self.included(_host) = ::Object.include Ext
   end
 
   # Function Pipe
   #
   # Refinement: Object#▷
   #
-  # = Example
+  # @example
   #
   #     using Cinnabar::FnPipe::Refin
   #
@@ -63,7 +63,7 @@ module Cinnabar::FnPipe
   #
   module Refin
     refine ::Object do
-      import_methods ObjectExt
+      import_methods Ext
     end
   end
 end

data/lib/cinnabar/version.rb

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

data/lib/cinnabar.rb

@@ -6,5 +6,6 @@
 require_relative 'cinnabar/00_pre'
 require_relative 'cinnabar/cmd_runner'
 require_relative 'cinnabar/net'
+require_relative 'cinnabar/path'
 require_relative 'cinnabar/pipe'
 require_relative 'cinnabar/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cinnabar
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.2
 platform: ruby
 authors:
 - 2moe
@@ -29,13 +29,16 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".yardopts"
 - License
+- docs/ChangeLog.md
 - docs/Readme-zh.md
 - docs/Readme.md
 - lib/cinnabar.rb
 - lib/cinnabar/00_pre.rb
 - lib/cinnabar/cmd_runner.rb
 - lib/cinnabar/net.rb
+- lib/cinnabar/path.rb
 - lib/cinnabar/pipe.rb
 - lib/cinnabar/version.rb
 homepage: https://github.com/2moe/cinnabar
@@ -43,6 +46,7 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://github.com/2moe/cinnabar
+  documentation_uri: https://2moe.github.io/cinnabar
 rdoc_options: []
 require_paths:
 - lib
@@ -57,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: CI Utils
 test_files: []