mudis-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5fb70c45a76d4ba85610a896b51c40a51953f1026370eb8108115b14f5469eff
+  data.tar.gz: ca7ebbf3dad48c107231e544f9ce3cc593f1ebcfacd068d05b36f4dbe8467b5a
+SHA512:
+  metadata.gz: cca5bbb33145be264050db3838445a04c9e00093b124f1fb7d865ea5a478e7c910ef4c519e41314ca2a1c04fe35f394ab5ac62aadd8ee5d9ac0c45fc1300e960
+  data.tar.gz: d19759346f44ee4141141c9e57ccc0fe34cf35fe21410dc212a714d656af723a1f90df235d4ceef95925a7e2a167e655e958914631fd4e951531ffbd5b9356c7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+# Mudis CLI
+
+CLI utilities for Mudis development and runtime debugging. The CLI loads your application environment, attaches to the `Mudis` entry point, and provides a small set of commands for inspection and mutation.
+
+## Install
+
+```bash
+bundle add mudis-cli
+```
+
+## Usage
+
+Load a Rails app and list keys:
+
+```bash
+mudis -r ./config/environment.rb keys
+```
+
+Read a key:
+
+```bash
+mudis -r ./config/environment.rb get user:42
+```
+
+Write a key with TTL:
+
+```bash
+mudis -r ./config/environment.rb set --ttl 60 user:42 '{"name":"Ada"}' --json
+```
+
+Run a Mudis-QL expression:
+
+```bash
+mudis -r ./config/environment.rb ql "from('users').where(id: 42).first"
+```
+
+Start a REPL with helpers:
+
+```bash
+mudis -r ./config/environment.rb repl
+```
+
+## Commands
+
+- `keys [--namespace NS]`
+- `get [--namespace NS] [--raw] KEY`
+- `set [--namespace NS] [--ttl SECONDS] [--json] KEY VALUE`
+- `del [--namespace NS] KEY`
+- `clear-namespace NAMESPACE`
+- `metrics`
+- `reset`
+- `reset-metrics`
+- `least-touched`
+- `ql 'EXPR'`
+- `repl`
+
+## Global Options
+
+- `-r, --require PATH` Require a file before running (repeatable).
+- `-e, --env NAME` Set `RACK_ENV` / `RAILS_ENV` before requiring files.
+- `--const NAME` Constant name for Mudis entry point (default: `Mudis`).
+- `--format FORMAT` Output format: `text` or `json`.
+- `--[no-]color` Enable/disable colored output (default: auto). Respects `NO_COLOR`.
+- `--verbose` Show stacktraces on errors.
+
+## Notes
+
+- The CLI defaults to the `Mudis` constant. Use `--const` if your app exposes a different entry point.
+- `ql` and `repl` depend on `mudis-ql` and will fail if it is not installed.
+- `ql` evaluates the expression with `mudis` and `ql` variables in scope (`ql` points to `MudisQL`).
+
+## Development
+
+```bash
+bundle exec ruby -I lib bin/mudis --help
+```

data/bin/mudis

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "mudis/cli"
+
+exit(Mudis::CLI.run)

data/lib/mudis/cli/runner.rb

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+require "mudis/cli/version"
+
+class Mudis
+  module CLI
+    class Runner
+      DEFAULT_CONST = "Mudis"
+
+      def initialize(argv, out: $stdout, err: $stderr)
+        @argv = argv.dup
+        @out = out
+        @err = err
+        @requires = []
+        @env = nil
+        @const_name = DEFAULT_CONST
+        @format = "text"
+        @color = true
+      end
+
+      def call
+        parse_global_options!
+
+        if @show_version
+          @out.puts(VERSION)
+          return 0
+        end
+
+        command = @argv.shift
+        return help(0) if @show_help || command.nil? || command == "help"
+
+        load_environment!
+
+        case command
+        when "keys"
+          run_keys(@argv)
+        when "get"
+          run_get(@argv)
+        when "set"
+          run_set(@argv)
+        when "del", "delete"
+          run_delete(@argv)
+        when "clear-namespace"
+          run_clear_namespace(@argv)
+        when "metrics"
+          run_metrics(@argv)
+        when "reset"
+          run_reset(@argv)
+        when "reset-metrics"
+          run_reset_metrics(@argv)
+        when "least-touched"
+          run_least_touched(@argv)
+        when "ql"
+          run_ql(@argv)
+        when "repl"
+          run_repl(@argv)
+        else
+          @err.puts("Unknown command: #{command}")
+          help(1)
+        end
+      rescue OptionParser::ParseError => e
+        @err.puts(e.message)
+        help(1)
+      rescue LoadError => e
+        @err.puts("Load error: #{e.message}")
+        @err.puts("Tip: ensure required gems are installed and --require points at your app environment.")
+        1
+      rescue StandardError => e
+        @err.puts("Error: #{e.class}: #{e.message}")
+        @err.puts(e.backtrace.first(5).join("\n")) if @verbose
+        1
+      end
+
+      private
+
+      def parse_global_options!
+        OptionParser.new do |opts|
+          opts.banner = "Usage: mudis [global options] <command> [command options]"
+          opts.on("-r", "--require PATH", "Require file before running command (repeatable)") do |value|
+            @requires << value
+          end
+          opts.on("-e", "--env NAME", "Set RACK_ENV/RAILS_ENV before requiring files") do |value|
+            @env = value
+          end
+          opts.on("--const NAME", "Constant name for Mudis entry point (default: #{DEFAULT_CONST})") do |value|
+            @const_name = value
+          end
+          opts.on("--format FORMAT", "Output format: text|json (default: text)") do |value|
+            @format = value
+          end
+          opts.on("--[no-]color", "Enable/disable colored output (default: auto)") do |value|
+            @color = value
+          end
+          opts.on("--verbose", "Show stacktraces on errors") do
+            @verbose = true
+          end
+          opts.on("-h", "--help", "Show help") do
+            @show_help = true
+          end
+          opts.on("--version", "Show version") do
+            @show_version = true
+          end
+        end.order!(@argv)
+      end
+
+      def load_environment!
+        if @env
+          ENV["RACK_ENV"] = @env
+          ENV["RAILS_ENV"] = @env
+        end
+
+        require "mudis"
+        @requires.each { |path| require path }
+      end
+
+      def mudis_constant
+        Object.const_get(@const_name)
+      rescue NameError
+        raise NameError, "Could not resolve constant #{@const_name}. Use --const to specify the Mudis entry point."
+      end
+
+      def run_keys(argv)
+        namespace = nil
+        OptionParser.new do |opts|
+          opts.banner = "Usage: mudis keys [--namespace NS]"
+          opts.on("--namespace NS", "Namespace to filter") { |value| namespace = value }
+        end.parse!(argv)
+
+        mudis = mudis_constant
+        unless mudis.respond_to?(:keys)
+          error("Mudis does not expose .keys. Available methods: #{mudis.methods(false).sort.join(", ")}")
+          return 1
+        end
+
+        result = namespace ? mudis.keys(namespace: namespace) : mudis.keys
+        print_output(result)
+        0
+      end
+
+      def run_get(argv)
+        namespace = nil
+        raw = false
+        OptionParser.new do |opts|
+          opts.banner = "Usage: mudis get [--namespace NS] [--raw] KEY"
+          opts.on("--namespace NS", "Namespace to read from") { |value| namespace = value }
+          opts.on("--raw", "Print raw value without formatting") { raw = true }
+        end.parse!(argv)
+
+        key = argv.shift
+        return usage_error("Missing key", "mudis get [--namespace NS] [--raw] KEY") unless key
+
+        mudis = mudis_constant
+        reader = if mudis.respond_to?(:read)
+          :read
+        elsif mudis.respond_to?(:get)
+          :get
+        else
+          error("Mudis does not expose .read or .get")
+          return 1
+        end
+
+        value = if namespace
+          mudis.public_send(reader, key, namespace: namespace)
+        else
+          mudis.public_send(reader, key)
+        end
+
+        raw ? @out.puts(value) : print_output(value)
+        0
+      end
+
+      def run_set(argv)
+        namespace = nil
+        ttl = nil
+        parse_json = false
+        OptionParser.new do |opts|
+          opts.banner = "Usage: mudis set [--namespace NS] [--ttl SECONDS] [--json] KEY VALUE"
+          opts.on("--namespace NS", "Namespace to write to") { |value| namespace = value }
+          opts.on("--ttl SECONDS", Integer, "Expiration in seconds") { |value| ttl = value }
+          opts.on("--json", "Parse VALUE as JSON") { parse_json = true }
+        end.parse!(argv)
+
+        key = argv.shift
+        value = argv.shift
+        return usage_error("Missing key/value", "mudis set [--namespace NS] [--ttl SECONDS] [--json] KEY VALUE") unless key && value
+
+        if parse_json
+          begin
+            value = JSON.parse(value)
+          rescue JSON::ParserError => e
+            error("Invalid JSON: #{e.message}")
+            return 1
+          end
+        end
+
+        mudis = mudis_constant
+        writer = if mudis.respond_to?(:write)
+          :write
+        elsif mudis.respond_to?(:set)
+          :set
+        else
+          error("Mudis does not expose .write or .set")
+          return 1
+        end
+
+        args = [key, value]
+        kwargs = {}
+        kwargs[:namespace] = namespace if namespace
+        kwargs[:expires_in] = ttl if ttl
+
+        mudis.public_send(writer, *args, **kwargs)
+        success("OK")
+        0
+      end
+
+      def run_delete(argv)
+        namespace = nil
+        OptionParser.new do |opts|
+          opts.banner = "Usage: mudis del [--namespace NS] KEY"
+          opts.on("--namespace NS", "Namespace to delete from") { |value| namespace = value }
+        end.parse!(argv)
+
+        key = argv.shift
+        return usage_error("Missing key", "mudis del [--namespace NS] KEY") unless key
+
+        mudis = mudis_constant
+        deleter = if mudis.respond_to?(:delete)
+          :delete
+        elsif mudis.respond_to?(:del)
+          :del
+        else
+          error("Mudis does not expose .delete or .del")
+          return 1
+        end
+
+        result = namespace ? mudis.public_send(deleter, key, namespace: namespace) : mudis.public_send(deleter, key)
+        print_output(result)
+        0
+      end
+
+      def run_clear_namespace(argv)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: mudis clear-namespace NAMESPACE"
+        end.parse!(argv)
+
+        namespace = argv.shift
+        return usage_error("Missing namespace", "mudis clear-namespace NAMESPACE") unless namespace
+
+        mudis = mudis_constant
+        unless mudis.respond_to?(:clear_namespace)
+          error("Mudis does not expose .clear_namespace")
+          return 1
+        end
+
+        begin
+          result = mudis.clear_namespace(namespace: namespace)
+        rescue ArgumentError
+          result = mudis.clear_namespace(namespace)
+        end
+
+        print_output(result)
+        0
+      end
+
+      def run_metrics(_argv)
+        mudis = mudis_constant
+        unless mudis.respond_to?(:metrics)
+          error("Mudis does not expose .metrics")
+          return 1
+        end
+
+        result = mudis.metrics
+        print_output(result)
+        0
+      end
+
+      def run_reset(_argv)
+        mudis = mudis_constant
+        unless mudis.respond_to?(:reset!)
+          error("Mudis does not expose .reset!")
+          return 1
+        end
+
+        mudis.reset!
+        success("OK")
+        0
+      end
+
+      def run_reset_metrics(_argv)
+        mudis = mudis_constant
+        unless mudis.respond_to?(:reset_metrics!)
+          error("Mudis does not expose .reset_metrics!")
+          return 1
+        end
+
+        mudis.reset_metrics!
+        success("OK")
+        0
+      end
+
+      def run_least_touched(_argv)
+        mudis = mudis_constant
+        unless mudis.respond_to?(:least_touched)
+          error("Mudis does not expose .least_touched")
+          return 1
+        end
+
+        result = mudis.least_touched
+        print_output(result)
+        0
+      end
+
+      def run_ql(argv)
+        OptionParser.new do |opts|
+          opts.banner = "Usage: mudis ql 'EXPR'"
+        end.parse!(argv)
+
+        expr = argv.join(" ")
+        return usage_error("Missing expression", "mudis ql 'EXPR'") if expr.empty?
+
+        require "mudis_ql"
+
+        mudis = mudis_constant
+        ql = MudisQL
+        result = eval(expr, binding, __FILE__, __LINE__)
+        print_output(result)
+        0
+      rescue LoadError
+        error("mudis-ql is not available. Add it to your bundle or install the gem.")
+        1
+      end
+
+      def run_repl(_argv)
+        require "irb"
+        require "mudis_ql"
+
+        mudis = mudis_constant
+        @out.puts("Mudis CLI REPL. Helper vars: mudis, ql")
+        ql = MudisQL
+
+        IRB.setup(nil)
+        workspace = IRB::WorkSpace.new(binding)
+        irb = IRB::Irb.new(workspace)
+        IRB.conf[:MAIN_CONTEXT] = irb.context
+        catch(:IRB_EXIT) { irb.eval_input }
+        0
+      rescue LoadError
+        error("mudis-ql is not available. Add it to your bundle or install the gem.")
+        1
+      end
+
+      def print_output(value)
+        if @format == "json"
+          payload = if value.is_a?(Array) || value.is_a?(Hash)
+            value
+          elsif value.respond_to?(:as_json)
+            value.as_json
+          elsif value.respond_to?(:to_h)
+            value.to_h
+          else
+            value
+          end
+          begin
+            @out.puts(JSON.pretty_generate(payload))
+          rescue JSON::GeneratorError
+            @out.puts(JSON.pretty_generate(payload.to_s))
+          end
+        else
+          case value
+          when Array
+            value.each { |item| @out.puts(item) }
+          when Hash
+            value.each { |k, v| @out.puts("#{k}: #{v}") }
+          else
+            @out.puts(value.inspect)
+          end
+        end
+      end
+
+      def usage_error(message, usage)
+        error(message)
+        warn_line("Usage: #{usage}")
+        1
+      end
+
+      def help(code)
+        @out.puts <<~HELP
+          Mudis CLI
+
+          Usage:
+            mudis [global options] <command> [command options]
+
+          Global options:
+            -r, --require PATH    Require a file before running (repeatable)
+            -e, --env NAME        Set RACK_ENV/RAILS_ENV before requiring files
+                --const NAME      Mudis constant name (default: Mudis)
+                --format FORMAT   Output format: text|json
+                --[no-]color       Enable/disable colored output (default: auto)
+                --verbose         Show stacktraces on errors
+                --version         Show version
+            -h, --help            Show help
+
+          Commands:
+            keys [--namespace NS]
+            get [--namespace NS] [--raw] KEY
+            set [--namespace NS] [--ttl SECONDS] [--json] KEY VALUE
+            del [--namespace NS] KEY
+            clear-namespace NAMESPACE
+            metrics
+            reset
+            reset-metrics
+            least-touched
+            ql 'EXPR'
+            repl
+        HELP
+        code
+      end
+
+      def color_enabled?(io)
+        return false unless @color
+        return false if ENV["NO_COLOR"]
+        io.respond_to?(:tty?) && io.tty?
+      end
+
+      def colorize(io, text, code)
+        return text unless color_enabled?(io)
+        "\e[#{code}m#{text}\e[0m"
+      end
+
+      def info(message)
+        @out.puts(colorize(@out, message, 36))
+      end
+
+      def success(message)
+        @out.puts(colorize(@out, message, 32))
+      end
+
+      def debug(message)
+        @out.puts(colorize(@out, message, 90))
+      end
+
+      def warn_line(message)
+        @err.puts(colorize(@err, message, 33))
+      end
+
+      def error(message)
+        @err.puts(colorize(@err, message, 31))
+      end
+    end
+  end
+end

data/lib/mudis/cli/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Mudis
+  module CLI
+    VERSION = "0.1.0"
+  end
+end

data/lib/mudis/cli.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "mudis/cli/runner"
+
+class Mudis
+  module CLI
+    def self.run(argv = ARGV, out: $stdout, err: $stderr)
+      Runner.new(argv, out: out, err: err).call
+    end
+  end
+end

data/sig/mudis/cli/runner.rbs

@@ -0,0 +1,40 @@
+# RBS for Mudis::CLI::Runner
+
+module Mudis
+  module CLI
+    class Runner
+      def initialize: (Array[String], out: IO, err: IO) -> void
+      def call: () -> Integer
+
+      private
+
+      def parse_global_options!: () -> void
+      def load_environment!: () -> void
+      def mudis_constant: () -> untyped
+
+      def run_keys: (Array[String]) -> Integer
+      def run_get: (Array[String]) -> Integer
+      def run_set: (Array[String]) -> Integer
+      def run_delete: (Array[String]) -> Integer
+      def run_clear_namespace: (Array[String]) -> Integer
+      def run_metrics: (Array[String]) -> Integer
+      def run_reset: (Array[String]) -> Integer
+      def run_reset_metrics: (Array[String]) -> Integer
+      def run_least_touched: (Array[String]) -> Integer
+      def run_ql: (Array[String]) -> Integer
+      def run_repl: (Array[String]) -> Integer
+
+      def print_output: (untyped) -> void
+      def usage_error: (String, String) -> Integer
+      def help: (Integer) -> Integer
+
+      def color_enabled?: (IO) -> bool
+      def colorize: (IO, String, String) -> String
+      def info: (String) -> void
+      def success: (String) -> void
+      def debug: (String) -> void
+      def warn_line: (String) -> void
+      def error: (String) -> void
+    end
+  end
+end

data/sig/mudis/cli.rbs

@@ -0,0 +1,9 @@
+# RBS for Mudis::CLI
+
+module Mudis
+  module CLI
+    VERSION: String
+
+    def self.run: (?Array[String], ?out: IO, ?err: IO) -> Integer
+  end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: mudis-cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kiebor81
+bindir: bin
+cert_chain: []
+date: 2026-02-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mudis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.4
+- !ruby/object:Gem::Dependency
+  name: mudis-ql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Command line utilities for inspecting and debugging Mudis caches, with
+  optional Mudis-QL support.
+email:
+- ''
+executables:
+- mudis
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- bin/mudis
+- lib/mudis/cli.rb
+- lib/mudis/cli/runner.rb
+- lib/mudis/cli/version.rb
+- sig/mudis/cli.rbs
+- sig/mudis/cli/runner.rbs
+homepage: https://github.com/kiebor81/mudis
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: CLI utilities for Mudis development and runtime debugging
+test_files: []