rubycli 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14562bc06b2479369c2951a54cac6f8f502e5ff81ae453b25bdb225b2017f671
-  data.tar.gz: 731a6704bac4ca7d9471b4ff00d7476745e81c442666e99ca3b710d70c9e4622
+  metadata.gz: a71a438637363ea54e22377b645dc99a26a0c91692571bf57a68368403e32308
+  data.tar.gz: 367b354b2ffde5ee80e7ee3ee5b2858f15cbf8097cc8346fd812b780f41443e2
 SHA512:
-  metadata.gz: 2ef973534a268ac8475f21f9d26ef16202ab5f4a89a69c3ea94a0700f1d89a5b17e533d5e821f8c6833855c91f72a5d5d6fcbfb75716c9a3648bf52e9c26600b
-  data.tar.gz: c2cc78a8dbc2ec9185c6fcb598ea5be2160ea336021932e2ab7ffb58b5b2be5f8fad078ed379a26a33c66241ed69a17c1edd9bd852663299747a630edd9da235
+  metadata.gz: 5eb055a5cbaa3daf0d311b67922a0c9bb7dbb8a75c2844524dc21f5faed232f560c8f1aaea6caf96737fea0b979625813b1ea5cc6c589ecee405b994b07ee16f
+  data.tar.gz: f64107c28083a96674970f8414090e47b77a749f8d3c9393ff9ca972a747ebe36a5da128d1c75a313ca570631436509392985477d1eefe271722eb4b046c69a8

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.1.4] - 2025-11-08
+
+### Changed
+- Re-cut the release that was briefly published as 0.1.3 (and yanked) so RubyGems now hosts the complete set of changes listed below.
+
+> _Note:_ 0.1.3 was yanked before general availability; consumers should upgrade directly to 0.1.4.
+
+## [0.1.3] - 2025-11-08
+
+### Added
+- TracePoint-backed constant capture so Rubycli can detect CLI classes/modules even when they are defined indirectly; bundled example and tests illustrate the behavior.
+- Strict/auto constant selection modes with the new `--auto-target` / `-a` flag so single callable constants are picked automatically when requested.
+- `--eval-lax` / `-E` argument mode that evaluates Ruby inputs but gracefully falls back to raw strings on parse failures.
+
+### Changed
+- Argument parsing internals were modularized so JSON/eval coercion now flows through a dedicated controller, simplifying future extensions.
+- `rubycli` now returns explicit status codes for success and failure, improving scriptability.
+- CLI constant selection errors provide clearer guidance, document the `--new` behavior, and consistently refer to the `--auto-target` flag.
+
+### Documentation
+- Clarified the authoritative source for documentation comments, reorganized helper logic in the showcase example, and expanded guidance around constant modes.
+
+### Fixed
+- CLI no longer dumps a Ruby backtrace when `Rubycli::Runner` reports user-facing errors; only the curated guidance is shown.
+
 ## [0.1.2] - 2025-11-06
 
 ### Added

data/README.ja.md

@@ -2,7 +2,7 @@
 
 ![Rubycli ロゴ](assets/rubycli-logo.png)
 
-Rubycli は Ruby のクラス／モジュールに書いたコメントから CLI を自動生成する小さなフレームワークです。Python Fire にインスパイアされていますが、互換や公式ポートを目指すものではありません。Ruby のコメント記法と型アノテーションに合わせて設計しています。
+Rubycli は Ruby のクラス／モジュールにある公開メソッドの定義と、そのメソッドに付けたドキュメントコメントから CLI を自動生成する小さなフレームワークです。Python Fire にインスパイアされていますが、互換や公式ポートを目指すものではありません。Ruby のコメント記法と型アノテーションに合わせて設計しており、コメントに書いた型ヒントや繰り返し指定が CLI の引数解釈もコントロールします。
 
 > English guide is available in [README.md](README.md).
 
@@ -147,11 +147,24 @@ end
 
 `ruby hello_app.rb ...` の形で呼び出したい場合だけ `require "rubycli"` を追加し、`Rubycli.run` に制御を渡します（後述のクイックスタート参照）。
 
+## 定数解決モード
+
+Rubycli は「ファイル名を CamelCase にした定数」を公開対象だと想定しています。ファイル名とクラス／モジュール名が一致しない場合は、次のモードで挙動を切り替えられます。
+
+| モード | 有効化方法 | 挙動 |
+| --- | --- | --- |
+| `strict`（デフォルト） | 何もしない / `RUBYCLI_AUTO_TARGET=strict` | CamelCase が一致しないとエラーになります。検出した定数一覧と再実行コマンド例を表示します。 |
+| `auto` | `--auto-target`（短縮 `-a`） または `RUBYCLI_AUTO_TARGET=auto` | ファイル内で CLI として実行できる定数が 1 つだけなら自動選択します。複数あれば従来通りエラーで案内します。 |
+
+大規模なコードベースでも安全側を保ちながら、どうしても自動選択したいときだけ 1 フラグで切り替えられます。
+
+> **インスタンスメソッド専用のクラスについて** – 公開メソッドがインスタンス側（`attr_reader` や `def greet`）にしか無い場合は、`--new` を付けて事前にインスタンス化しないと CLI から呼び出せません。クラスメソッドを 1 つ用意するか、`--new` を明示して実行してください。
+
 ## 開発方針
 
 - **便利さが最優先** – 既存の Ruby スクリプトを最小の手間で CLI 化できることを目的にしており、Python Fire の完全移植は目指していません。
 - **インスパイアであってポートではない** – アイデアの出自は Fire ですが、同等機能を揃える予定は基本的にありません。Fire 由来の未実装機能は仕様です。
-- **コードが一次情報、コメントは補助** – メソッド定義こそが真実であり、コメントはヘルプを豊かにする付加情報です。コメントと実装のズレを観測したいときだけ `RUBYCLI_STRICT=ON` で厳格モードを有効化し、警告を受け取ります。
+- **メソッド定義が土台、コメントが挙動を補強** – 公開メソッドのシグネチャが CLI に露出する範囲と必須／任意を決めますが、コメントに `TAG...` や `[Integer]` を書くと同じ引数でも配列化や型変換が行われます。コメントと実装のズレを観測したいときだけ `RUBYCLI_STRICT=ON` で厳格モードを有効化し、警告を受け取ります。
 - **軽量メンテナンス** – 実装の多くは AI 支援で作られており、深い Ruby メタプログラミングを伴う大規模拡張は想定外です。Fire 互換を求める PR は事前相談をお願いします。
 
 ## 特徴
@@ -172,7 +185,7 @@ end
 | 機能 | Python Fire | Rubycli |
 | ---- | ----------- | -------- |
 | 属性の辿り方 | オブジェクトを辿ってプロパティ/属性を自動公開 | 対象オブジェクトの公開メソッドをそのまま公開（暗黙の辿りは無し） |
-| クラス初期化 | `__init__` 引数を CLI で自動受け取りインスタンス化 | `--new` を指定した明示的な初期化のみ。引数はコメントで宣言 |
+| クラス初期化 | `__init__` 引数を CLI で自動受け取りインスタンス化 | `--new` 指定時だけ引数なしで明示的に初期化（初期化引数の CLI 受け渡しは未対応なので、必要なら pre-script や自前ファクトリで注入） |
 | インタラクティブシェル | コマンド未指定時に Fire REPL を提供 | インタラクティブモード無し。コマンド実行専用 |
 | 情報源 | 反射で引数・プロパティを解析 | ライブなメソッド定義を基点にしつつコメントをヘルプへ反映 |
 | 辞書/配列 | dict/list を自動でサブコマンド化 | クラス/モジュールのメソッドに特化（辞書自動展開なし） |
@@ -374,7 +387,9 @@ YAML 固有の書き方は拒否され、無効な JSON であれば `JSON::Pars
 
 `--eval-args`（短縮形 `-e`）を使うと、後続の引数を Ruby コードとして評価した結果を CLI に渡せます。JSON や YAML では表現しづらいオブジェクトを扱いたいときに便利ですが、評価は `Object.new.instance_eval { binding }` 上で行われるため、信頼できる入力に限定してください。コード内では `Rubycli.with_eval_mode(true) { … }` で切り替えられます。
 
-`--eval-args`/`-e` と `--json-args`/`-j` は同時指定できません。どちらのモードも既定のリテラル解析を拡張する位置づけなので、用途に応じて厳格な JSON か Ruby eval のどちらかを選択してください。
+Ruby 評価を使いつつ、構文エラーが出たときは元の文字列にフォールバックさせたい場合は `--eval-lax`（短縮形 `-E`）を指定します。`--eval-args` と同じく eval モードを有効にしますが、Ruby として解釈できなかったトークン（例: 素の `https://example.com`）は警告を出した上でそのまま渡すため、`60*60*24*14` のような式と文字列を気軽に混在させられます。
+
+`--json-args`/`-j` は `--eval-args`/`-e` および `--eval-lax`/`-E` と同時指定できません。どのモードも既定のリテラル解析を拡張する位置づけなので、用途に応じて厳格な JSON か Ruby eval（通常／lax）のいずれかを選択してください。
 
 ## Pre-script ブートストラップ
 

data/README.md

@@ -2,7 +2,7 @@
 
 ![Rubycli logo](assets/rubycli-logo.png)
 
-Rubycli turns existing Ruby classes and modules into CLIs by reading their documentation comments. It is inspired by [Python Fire](https://github.com/google/python-fire) but is not a drop-in port or an official project; the focus here is Ruby’s documentation conventions and type annotations.
+Rubycli turns existing Ruby classes and modules into CLIs by inspecting their public method definitions and the doc comments attached to those methods. It is inspired by [Python Fire](https://github.com/google/python-fire) but is not a drop-in port or an official project; the focus here is Ruby’s documentation conventions and type annotations, and those annotations can actively change how a CLI argument is coerced (for example, `TAG... [String[]]` forces array parsing).
 
 > 🇯🇵 Japanese documentation is available in [README.ja.md](README.ja.md).
 
@@ -154,11 +154,24 @@ ruby examples/hello_app_with_require.rb greet Hanako --shout
 #=> HELLO, HANAKO!
 ```
 
+## Constant resolution modes
+
+Rubycli assumes that the file name (CamelCased) matches the class or module you want to expose. When that is not the case you can choose how eagerly Rubycli should pick a constant:
+
+| Mode | How to enable | Behaviour |
+| --- | --- | --- |
+| `strict` (default) | do nothing / `RUBYCLI_AUTO_TARGET=strict` | Fails unless the CamelCase name matches. The error lists the detected constants and gives explicit rerun instructions. |
+| `auto` | `--auto-target`, `-a`, or `RUBYCLI_AUTO_TARGET=auto` | If exactly one constant in that file defines CLI-callable methods, Rubycli auto-selects it; otherwise you still get the friendly error message. |
+
+This keeps large projects safe by default but still provides a one-flag escape hatch when you prefer the fully automatic behaviour.
+
+> **Instance-only classes** – If a class only defines public *instance* methods (for example, it exposes functionality via `attr_reader` or `def greet` on the instance), you must run Rubycli with `--new` so the class is instantiated before commands are resolved. Otherwise Rubycli cannot see any CLI-callable methods. Add at least one public class method when you do not want to rely on `--new`.
+
 ## Project Philosophy
 
 - **Convenience first** – The goal is to wrap existing Ruby scripts in a CLI with almost no manual plumbing. Fidelity with Python Fire is not a requirement.
 - **Inspired, not a port** – We borrow ideas from Python Fire, but we do not aim for feature parity. Missing Fire features are generally “by design.”
-- **Comments enrich, code decides** – Method signatures remain the source of truth; optional documentation comments add richer help output and can surface warnings when you opt into strict mode (`RUBYCLI_STRICT=ON`).
+- **Method definitions first, comments augment behavior** – Public method signatures determine what gets exposed (and which arguments are required), while doc comments like `TAG...` or `[Integer]` can turn the very same CLI value into arrays, integers, booleans, etc. Enable strict mode (`RUBYCLI_STRICT=ON`) when you want warnings about mismatches.
 - **Lightweight maintenance** – Much of the implementation was generated with AI assistance; contributions that diverge into deep Ruby metaprogramming are out of scope. Please discuss expectations before opening parity PRs.
 
 ## Features
@@ -179,7 +192,7 @@ ruby examples/hello_app_with_require.rb greet Hanako --shout
 | Capability | Python Fire | Rubycli |
 | ---------- | ----------- | -------- |
 | Attribute traversal | Recursively exposes attributes/properties on demand | Exposes public methods defined on the target; no implicit traversal |
-| Constructor handling | Automatically prompts for `__init__` args when instantiating classes | Requires explicit `--new` plus comment docs; no automatic prompting |
+| Constructor handling | Automatically prompts for `__init__` args when instantiating classes | `--new` simply instantiates without passing CLI args (use pre-scripts or your own factories if you need injected dependencies) |
 | Interactive shell | Offers Fire-specific REPL when invoked without command | No interactive shell mode; strictly command execution |
 | Input discovery | Pure reflection, no doc comments required | Doc comments drive option names, placeholders, and validation |
 | Data structures | Dictionaries / lists become subcommands by default | Focused on class or module methods; no automatic dict/list expansion |
@@ -382,7 +395,9 @@ rubycli -e scripts/data_cli.rb DataCLI run '(1..10).to_a'
 
 Under the hood Rubycli evaluates each argument inside an isolated binding (`Object.new.instance_eval { binding }`). Treat this as unsafe input: do not enable it for untrusted callers. The mode can also be toggled programmatically via `Rubycli.with_eval_mode(true) { … }`.
 
-`--eval-args`/`-e` and `--json-args`/`-j` are mutually exclusive; Rubycli will raise an error if both are present. Both modes augment the default literal parsing, so you can pick either strict JSON or full Ruby evaluation when the defaults are not enough.
+Need Ruby evaluation plus a safety net? Pass `--eval-lax` (or `-E`). It flips on eval mode just like `--eval-args`, but if Ruby fails to parse a token (for example, a bare `https://example.com`), Rubycli emits a warning and forwards the original string unchanged. This lets you mix inline math (`60*60*24*14`) with literal values without constantly juggling quotes.
+
+`--json-args`/`-j` cannot be combined with either `--eval-args`/`-e` or `--eval-lax`/`-E`; Rubycli will raise an error if both are present. Both modes augment the default literal parsing, so you can pick either strict JSON or one of the Ruby eval variants when the defaults are not enough.
 
 ## Pre-script bootstrap
 

data/lib/rubycli/argument_mode_controller.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Rubycli
+  # Coordinates json/eval argument modes and enforces mutual exclusion.
+  class ArgumentModeController
+    def initialize(json_coercer:, eval_coercer:)
+      @json_coercer = json_coercer
+      @eval_coercer = eval_coercer
+    end
+
+    def json_mode?
+      @json_coercer.json_mode?
+    end
+
+    def eval_mode?
+      @eval_coercer.eval_mode?
+    end
+
+    def with_json_mode(enabled = true, &block)
+      enforce_mutual_exclusion!(:json, enabled)
+      @json_coercer.with_json_mode(enabled, &block)
+    end
+
+    def with_eval_mode(enabled = true, **options, &block)
+      enforce_mutual_exclusion!(:eval, enabled)
+      @eval_coercer.with_eval_mode(enabled, **options, &block)
+    end
+
+    def apply_argument_coercions(positional_args, keyword_args)
+      ensure_modes_compatible!
+
+      if json_mode?
+        coerce_values!(positional_args, keyword_args) { |value| @json_coercer.coerce_json_value(value) }
+      end
+
+      if eval_mode?
+        coerce_values!(positional_args, keyword_args) { |value| @eval_coercer.coerce_eval_value(value) }
+      end
+    rescue ::ArgumentError => e
+      raise Rubycli::ArgumentError, e.message
+    end
+
+    private
+
+    def enforce_mutual_exclusion!(mode, enabled)
+      return unless enabled
+
+      case mode
+      when :json
+        raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax' if eval_mode?
+      when :eval
+        raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax' if json_mode?
+      end
+    end
+
+    def ensure_modes_compatible!
+      if json_mode? && eval_mode?
+        raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax'
+      end
+    end
+
+    def coerce_values!(positional_args, keyword_args)
+      positional_args.map! { |value| yield(value) }
+      keyword_args.keys.each do |key|
+        keyword_args[key] = yield(keyword_args[key])
+      end
+    end
+  end
+end

data/lib/rubycli/argument_parser.rb

@@ -1,5 +1,6 @@
-require 'psych'
 require_relative 'type_utils'
+require_relative 'arguments/token_stream'
+require_relative 'arguments/value_converter'
 
 module Rubycli
   class ArgumentParser
@@ -10,6 +11,7 @@ module Rubycli
       @documentation_registry = documentation_registry
       @json_coercer = json_coercer
       @debug_logger = debug_logger
+      @value_converter = Arguments::ValueConverter.new
     end
 
     def parse(args, method = nil)
@@ -25,21 +27,21 @@ module Rubycli
       option_lookup = build_option_lookup(option_defs)
       type_converters = build_type_converter_map(option_defs)
 
-      i = 0
-      while i < args.size
-        token = args[i]
+      stream = Arguments::TokenStream.new(args)
+
+      until stream.finished?
+        token = stream.current
 
         if token == '--'
-          rest_tokens = (args[(i + 1)..-1] || []).map { |value| convert_arg(value) }
+          stream.advance
+          rest_tokens = stream.consume_remaining.map { |value| convert_arg(value) }
           pos_args.concat(rest_tokens)
           break
-        end
-
-        if option_token?(token)
-          i = process_option_token(
+        elsif option_token?(token)
+          stream.advance
+          process_option_token(
             token,
-            args,
-            i,
+            stream,
             kw_param_names,
             kw_args,
             cli_aliases,
@@ -47,12 +49,12 @@ module Rubycli
             type_converters
           )
         elsif assignment_token?(token)
+          stream.advance
           process_assignment_token(token, kw_args)
         else
           pos_args << convert_arg(token)
+          stream.advance
         end
-
-        i += 1
       end
 
       debug_log "Final parsed - pos_args: #{pos_args.inspect}, kw_args: #{kw_args.inspect}"
@@ -85,8 +87,7 @@ module Rubycli
 
     def process_option_token(
       token,
-      args,
-      current_index,
+      stream,
       kw_param_names,
       kw_args,
       cli_aliases,
@@ -108,21 +109,19 @@ module Rubycli
       requires_value = option_meta ? option_meta[:requires_value] : nil
       option_label = option_meta&.long || "--#{final_key.tr('_', '-')}"
 
-      value_capture, current_index = if embedded_value
-                                       [embedded_value, current_index]
-                                     elsif option_meta
-                                       capture_option_value(
-                                         option_meta,
-                                         args,
-                                         current_index,
-                                         requires_value
-                                       )
-                                     elsif current_index + 1 < args.size && !looks_like_option?(args[current_index + 1])
-                                       current_index += 1
-                                       [args[current_index], current_index]
-                                     else
-                                       ['true', current_index]
-                                     end
+      value_capture = if embedded_value
+                        embedded_value
+                      elsif option_meta
+                        capture_option_value(
+                          option_meta,
+                          stream,
+                          requires_value
+                        )
+                      elsif (next_token = stream.current) && !looks_like_option?(next_token)
+                        stream.consume
+                      else
+                        'true'
+                      end
 
       if requires_value && (value_capture.nil? || value_capture == 'true')
         raise ArgumentError, "Option '#{option_label}' requires a value"
@@ -136,40 +135,30 @@ module Rubycli
       )
 
       kw_args[final_key_sym] = converted_value
-      current_index
     end
-
-    def capture_option_value(option_meta, args, current_index, requires_value)
-      new_index = current_index
-      value = if option_meta[:boolean_flag]
-                if new_index + 1 < args.size && TypeUtils.boolean_string?(args[new_index + 1])
-                  new_index += 1
-                  args[new_index]
-                else
-                  'true'
-                end
-              elsif option_meta[:optional_value]
-                if new_index + 1 < args.size && !looks_like_option?(args[new_index + 1])
-                  new_index += 1
-                  args[new_index]
-                else
-                  true
-                end
-              elsif requires_value == false
-                'true'
-              elsif requires_value
-                if new_index + 1 >= args.size
-                  raise ArgumentError, "Option '#{option_meta.long}' requires a value"
-                end
-                new_index += 1
-                args[new_index]
-              elsif new_index + 1 < args.size && !looks_like_option?(args[new_index + 1])
-                new_index += 1
-                args[new_index]
-              else
-                'true'
-              end
-      [value, new_index]
+    def capture_option_value(option_meta, stream, requires_value)
+      if option_meta[:boolean_flag]
+        if (next_token = stream.current) && TypeUtils.boolean_string?(next_token)
+          return stream.consume
+        end
+        return 'true'
+      elsif option_meta[:optional_value]
+        if (next_token = stream.current) && !looks_like_option?(next_token)
+          return stream.consume
+        end
+        return true
+      elsif requires_value == false
+        return 'true'
+      elsif requires_value
+        next_token = stream.current
+        raise ArgumentError, "Option '#{option_meta.long}' requires a value" unless next_token
+
+        return stream.consume
+      elsif (next_token = stream.current) && !looks_like_option?(next_token)
+        return stream.consume
+      else
+        return 'true'
+      end
     end
 
     def process_assignment_token(token, kw_args)
@@ -204,65 +193,7 @@ module Rubycli
     end
 
     def convert_arg(arg)
-      return arg if Rubycli.eval_mode? || Rubycli.json_mode?
-      return arg unless arg.is_a?(String)
-
-      trimmed = arg.strip
-      return arg if trimmed.empty?
-
-      if literal_like?(trimmed)
-        literal = try_literal_parse(arg)
-        return literal unless literal.equal?(LITERAL_PARSE_FAILURE)
-      end
-
-      return nil if null_literal?(trimmed)
-
-      lower = trimmed.downcase
-      return true if lower == 'true'
-      return false if lower == 'false'
-      return arg.to_i if integer_string?(trimmed)
-      return arg.to_f if float_string?(trimmed)
-
-      arg
-    end
-
-    def integer_string?(str)
-      str =~ /\A-?\d+\z/
-    end
-
-    def float_string?(str)
-      str =~ /\A-?\d+\.\d+\z/
-    end
-
-    LITERAL_PARSE_FAILURE = Object.new
-
-    def try_literal_parse(value)
-      return LITERAL_PARSE_FAILURE unless value.is_a?(String)
-
-      trimmed = value.strip
-      return value if trimmed.empty?
-
-      literal = Psych.safe_load(trimmed, aliases: false)
-      return literal unless literal.nil? && !null_literal?(trimmed)
-
-      LITERAL_PARSE_FAILURE
-    rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::Exception
-      LITERAL_PARSE_FAILURE
-    end
-
-    def null_literal?(value)
-      return false unless value
-
-      %w[null ~].include?(value.downcase)
-    end
-
-    def literal_like?(value)
-      return false unless value
-      return true if value.start_with?('[', '{', '"', "'")
-      return true if value.start_with?('---')
-      return true if value.match?(/\A(?:true|false|null|nil)\z/i)
-
-      false
+      @value_converter.convert(arg)
     end
 
 

data/lib/rubycli/arguments/token_stream.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Rubycli
+  module Arguments
+    # Lightweight mutable cursor over CLI tokens.
+    class TokenStream
+      def initialize(tokens)
+        @tokens = Array(tokens).dup
+        @index = 0
+      end
+
+      def current
+        @tokens[@index]
+      end
+
+      def peek(offset = 1)
+        @tokens[@index + offset]
+      end
+
+      def advance(count = 1)
+        @index += count
+      end
+
+      def consume
+        value = current
+        advance
+        value
+      end
+
+      def consume_remaining
+        remaining = @tokens[@index..] || []
+        @index = @tokens.length
+        remaining
+      end
+
+      def finished?
+        @index >= @tokens.length
+      end
+    end
+  end
+end

data/lib/rubycli/arguments/value_converter.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'psych'
+
+module Rubycli
+  module Arguments
+    # Converts raw CLI tokens into Ruby primitives when safe to do so.
+    class ValueConverter
+      LITERAL_PARSE_FAILURE = Object.new
+
+      def convert(value)
+        return value if Rubycli.eval_mode? || Rubycli.json_mode?
+        return value unless value.is_a?(String)
+
+        trimmed = value.strip
+        return value if trimmed.empty?
+
+        if literal_like?(trimmed)
+          literal = try_literal_parse(value)
+          return literal unless literal.equal?(LITERAL_PARSE_FAILURE)
+        end
+
+        return nil if null_literal?(trimmed)
+
+        lower = trimmed.downcase
+        return true if lower == 'true'
+        return false if lower == 'false'
+        return value.to_i if integer_string?(trimmed)
+        return value.to_f if float_string?(trimmed)
+
+        value
+      end
+
+      private
+
+      def integer_string?(str)
+        str =~ /\A-?\d+\z/
+      end
+
+      def float_string?(str)
+        str =~ /\A-?\d+\.\d+\z/
+      end
+
+      def try_literal_parse(value)
+        return LITERAL_PARSE_FAILURE unless value.is_a?(String)
+
+        trimmed = value.strip
+        return value if trimmed.empty?
+
+        literal = Psych.safe_load(trimmed, aliases: false)
+        return literal unless literal.nil? && !null_literal?(trimmed)
+
+        LITERAL_PARSE_FAILURE
+      rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::Exception
+        LITERAL_PARSE_FAILURE
+      end
+
+      def null_literal?(value)
+        return false unless value
+
+        %w[null ~].include?(value.downcase)
+      end
+
+      def literal_like?(value)
+        return false unless value
+        return true if value.start_with?('[', '{', '"', "'")
+        return true if value.start_with?('---')
+        return true if value.match?(/\A(?:true|false|null|nil)\z/i)
+
+        false
+      end
+    end
+  end
+end

data/lib/rubycli/cli.rb

@@ -37,7 +37,7 @@ module Rubycli
 
       if should_show_help?(args)
         @help_renderer.print_help(target, catalog)
-        exit(0)
+        return 0
       end
 
       command = args.shift
@@ -105,7 +105,7 @@ module Rubycli
         error_msg = "Command '#{command}' is not available."
         puts error_msg
         @help_renderer.print_help(target, catalog)
-        exit(1)
+        1
       end
     end
 
@@ -116,6 +116,7 @@ module Rubycli
       begin
         result = Rubycli.call_target(target, pos_args, kw_args)
         @result_emitter.emit(result)
+        0
       rescue StandardError => e
         handle_execution_error(e, command, method, pos_args, kw_args, cli_mode)
       end
@@ -132,15 +133,16 @@ module Rubycli
     def execute_parameterless_method(method_obj, command, args, cli_mode)
       if help_requested_for_parameterless?(args)
         puts usage_for_method(command, method_obj)
-        exit(0)
+        return 0
       end
 
       begin
         result = method_obj.call
         debug_log "Parameterless method returned: #{result.inspect}"
         if result
-          run(result, args, false)
+          return run(result, args, false)
         end
+        0
       rescue StandardError => e
         handle_execution_error(e, command, method_obj, [], {}, cli_mode)
       end
@@ -152,12 +154,13 @@ module Rubycli
 
       if should_show_method_help?(pos_args, kw_args)
         puts usage_for_method(command, method_obj)
-        exit(0)
+        return 0
       end
 
       begin
         result = Rubycli.call_target(method_obj, pos_args, kw_args)
         @result_emitter.emit(result)
+        0
       rescue StandardError => e
         handle_execution_error(e, command, method_obj, pos_args, kw_args, cli_mode)
       end
@@ -181,7 +184,7 @@ module Rubycli
       if cli_mode && !arguments_match?(method_obj, pos_args, kw_args) && usage_error?(error)
         puts "Error: #{error.message}"
         puts usage_for_method(command, method_obj)
-        exit(1)
+        1
       else
         raise error
       end