exercism-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e3f086e7d56d3ef1314ac284fd277f39a34b6fba990e3979a20bb1a0a956673
+  data.tar.gz: 7258ab70a894221f104f6acb044fdae965d6dcd73af1070e45e829e48e780931
+SHA512:
+  metadata.gz: 5ea881fb4335c63357ca7cbe2741c3ecda1d1c12a81363bb2d1354f35db9d6b7cea49fc098da57ccfbb659b164774b52214cbef972b97e80704baa8bb90df0ee
+  data.tar.gz: 3537495bab0755c3521642d6014edd7a2f2ae633f8366f700f852bfc89d631495aaf56e3a0f12e874324db0de110c634be4020a86aca3c4dac5f72531d07109b

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.1.0 - 2026-05-06
+
+### Added
+
+- `xrb` CLI for downloading, selecting, opening, testing, inspecting, and submitting Exercism Ruby exercises.
+- Source installer for users who want to install directly from the repository.
+- RubyGems release preparation with CI, packaged gem smoke tests, and Trusted Publishing workflow.
+- Colorized CLI output with explicit `XRB_COLOR`, `NO_COLOR`, and `CLICOLOR_FORCE` controls.
+- Project documentation for development, security, contribution, and release practices.
+
+### Changed
+
+- Installation documentation now treats RubyGems as the primary distribution channel.
+
+### Fixed
+
+- State saves now use `Process.pid` for temporary files, avoiding Ruby warnings from an uninitialized global variable.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hvpaiva
+
+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,212 @@
+# exercism-rb
+
+`xrb` is a small CLI that removes friction from the Exercism Ruby workflow.
+
+It remembers the current exercise, runs commands from the right exercise directory, opens your editor, starts IRB with the solution file loaded, runs tests, and submits the solution file without requiring manual `cd` work.
+
+This is an independent helper for the Exercism Ruby track, not an official Exercism project.
+
+## Install
+
+Install from RubyGems:
+
+```bash
+gem install exercism-rb
+```
+
+Make sure your RubyGems executable directory is in your `PATH`, then verify the CLI:
+
+```bash
+xrb version
+```
+
+To update:
+
+```bash
+gem update exercism-rb
+```
+
+## Requirements
+
+- Ruby 3.2+
+- Exercism CLI for `xrb new` and `xrb submit`
+- An editor available on `PATH`
+
+Configure the Exercism CLI separately:
+
+```bash
+exercism configure --token=<your-api-token>
+```
+
+## Main Flow
+
+```bash
+xrb new assembly-line
+xrb test
+xrb irb
+xrb edit
+xrb submit
+```
+
+## Commands
+
+```bash
+xrb new <exercise>       # download, save as current, and open the editor
+xrb edit [exercise]      # open the editor for an exercise
+xrb test [exercise]      # run the exercise test file with minitest/pride
+xrb irb [exercise]       # open irb -r ./<solution>.rb --simple-prompt
+xrb submit [exercise]    # submit the solution .rb file
+xrb use <exercise>       # save a downloaded exercise as current
+xrb current              # show the current exercise
+xrb path [exercise]      # print the exercise path
+xrb list                 # list downloaded exercises
+xrb clear                # clear saved state
+```
+
+Exercise resolution priority:
+
+1. Explicit slug, for example `xrb test assembly-line`
+2. Current working directory when inside `XRB_ROOT`
+3. Saved state from the previous `xrb new` or `xrb use`
+
+`xrb test` expects a single `*_test.rb` file in the exercise directory and reports an ambiguity if more than one is present.
+
+## Output And Color
+
+`xrb` uses color automatically when stdout is a terminal. It stays plain when output is redirected, piped, or captured by tests.
+
+Color controls:
+
+```bash
+XRB_COLOR=auto      # default
+XRB_COLOR=always    # force ANSI color
+XRB_COLOR=never     # disable ANSI color
+NO_COLOR=1          # disable color in auto mode
+CLICOLOR_FORCE=1    # force color in auto mode
+```
+
+`xrb path` intentionally prints only the resolved path so it can be used in scripts.
+
+## State
+
+The current exercise is stored as flat TOML:
+
+```text
+~/.local/state/exercism-rb/state.toml
+```
+
+Example:
+
+```toml
+track = "ruby"
+exercise = "assembly-line"
+path = "/home/hvpaiva/exercism/ruby/assembly-line"
+updated_at = "2026-05-05T12:00:00Z"
+```
+
+## Configuration
+
+```bash
+XRB_ROOT=~/exercism/ruby      # exercise directory
+XRB_TRACK=ruby                # Exercism track
+XRB_EDITOR=nvim               # editor used by xrb new/edit
+XRB_STATE=~/.local/state/exercism-rb/state.toml
+XRB_COLOR=auto                # auto, always, or never
+```
+
+`xrb new` uses `exercism download`, which downloads into the workspace configured in the Exercism CLI. If you customize `XRB_ROOT`, configure the Exercism workspace so its track directory matches it, for example `exercism configure --workspace ~/exercism` for `XRB_ROOT=~/exercism/ruby`.
+
+Editor commands are split with shell-like quoting, so this works:
+
+```bash
+XRB_EDITOR="code --wait" xrb edit
+```
+
+## Source Installer
+
+RubyGems is the recommended installation path. The repository also keeps a source installer for users who want to install directly from `main`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/hvpaiva/exercism-rb/main/install.rb | ruby
+```
+
+The installer clones or updates the repository at `~/.local/share/exercism-rb` and creates this symlink:
+
+```text
+~/.local/bin/xrb -> ~/.local/share/exercism-rb/bin/xrb
+```
+
+It also installs the Exercism CLI into `~/.local/bin/exercism` when `exercism` is not already available.
+
+To skip the Exercism CLI install:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/hvpaiva/exercism-rb/main/install.rb | ruby - --no-exercism
+```
+
+To force-install or update the Exercism CLI:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/hvpaiva/exercism-rb/main/install.rb | ruby - --with-exercism
+```
+
+If `~/.local/bin/xrb` is an existing symlink, the installer replaces the symlink without deleting the old target. If it is a real file or directory, the installer refuses to replace it unless you opt in:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/hvpaiva/exercism-rb/main/install.rb | XRB_INSTALL_OVERWRITE=1 ruby
+```
+
+## Development
+
+Install development dependencies:
+
+```bash
+bundle install
+```
+
+Run the default test suite:
+
+```bash
+bundle exec rake
+```
+
+Run the full verification suite:
+
+```bash
+bundle exec rake ci
+```
+
+The CI task checks syntax, runs tests, runs tests with Ruby warnings enabled, smoke-tests the checkout executable, builds the gem, installs it into an isolated `GEM_HOME`, and smoke-tests the installed `xrb` executable.
+
+Useful individual tasks:
+
+```bash
+bundle exec rake test
+bundle exec rake syntax
+bundle exec rake warnings
+bundle exec rake smoke:bin
+bundle exec rake smoke:gem
+```
+
+## Release
+
+Publishing is automated through RubyGems Trusted Publishing and GitHub Actions. No long-lived `RUBYGEMS_AUTH_TOKEN` is required for the recommended release path.
+
+Before the first release, configure a pending trusted publisher on RubyGems.org:
+
+```text
+Gem name: exercism-rb
+GitHub repository: hvpaiva/exercism-rb
+Workflow filename: release.yml
+Environment: release
+```
+
+Release checklist:
+
+1. Update `lib/exercism/rb/version.rb`
+2. Update `CHANGELOG.md`
+3. Run `bundle exec rake ci`
+4. Commit the release changes
+5. Create and push a tag that matches the version, for example `v0.1.0` for `VERSION = "0.1.0"`
+
+The `Release` workflow runs only for `v*` tags. It verifies the project and publishes the gem through `rubygems/release-gem@v1`.

data/bin/xrb

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "exercism/rb"
+
+exit Exercism::Rb::CLI.start(ARGV)

data/lib/exercism/rb/cli.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Exercism
+  module Rb
+    class CLI
+      COMMANDS = %w[new edit test irb submit use current path list clear help version].freeze
+
+      def self.start(argv, out: $stdout, err: $stderr)
+        new(argv, out: out, err: err).start
+      end
+
+      def initialize(argv, out: $stdout, err: $stderr)
+        @argv = argv.dup
+        @ui = UI.new(out: out, err: err)
+        @state = State.new
+        @runner = CommandRunner.new(ui: @ui)
+        @track = Config.track
+        @root = Config.root(@track)
+        @resolver = Resolver.new(state: @state, track: @track, root: @root)
+      end
+
+      def start
+        command = @argv.shift || "help"
+
+        case command
+        when "new" then new_command
+        when "edit" then edit_command
+        when "test" then test_command
+        when "irb" then irb_command
+        when "submit" then submit_command
+        when "use" then use_command
+        when "current" then current_command
+        when "path" then path_command
+        when "list" then list_command
+        when "clear" then clear_command
+        when "help", "-h", "--help" then help_command
+        when "version", "-v", "--version" then version_command
+        else
+          raise Error, "Unknown command: #{command}. Use `xrb help`."
+        end
+
+        0
+      rescue Error => e
+        @ui.error(e.message)
+        1
+      rescue Interrupt
+        @ui.error("Interrupted.")
+        130
+      end
+
+      private
+
+      def new_command
+        exercise = exercise_from_required_arg("new <exercise>", require_existing: false)
+
+        @ui.info("Downloading #{@ui.highlight(exercise.slug)}...")
+        @runner.run("exercism", "download", "--track=#{exercise.track}", "--exercise=#{exercise.slug}")
+        exercise.ensure_exists!
+        save_current(exercise)
+        @ui.key_value("Path", @ui.path(exercise.path))
+        edit_exercise(exercise)
+      end
+
+      def edit_command
+        edit_exercise(@resolver.resolve(optional_arg))
+      end
+
+      def test_command
+        exercise = @resolver.resolve(optional_arg)
+        test_file = exercise.test_file
+
+        @ui.info("Testing #{@ui.highlight(exercise.slug)}...")
+        @runner.run("ruby", "-r", "minitest/pride", test_file, chdir: exercise.path)
+      end
+
+      def irb_command
+        exercise = @resolver.resolve(optional_arg)
+        solution_file = exercise.solution_file
+
+        @ui.info("Opening IRB for #{@ui.highlight(exercise.slug)}...")
+        @runner.run("irb", "-r", "./#{solution_file}", "--simple-prompt", chdir: exercise.path)
+      end
+
+      def submit_command
+        exercise = @resolver.resolve(optional_arg)
+        solution_file = exercise.solution_file
+
+        @ui.info("Submitting #{@ui.highlight(exercise.slug)}...")
+        @runner.run("exercism", "submit", solution_file, chdir: exercise.path)
+      end
+
+      def use_command
+        exercise = exercise_from_required_arg("use <exercise>")
+        save_current(exercise)
+        @ui.success("Current exercise: #{@ui.highlight(exercise.slug)}")
+        @ui.command(@ui.path(exercise.path))
+      end
+
+      def current_command
+        data = @state.load
+        raise Error, "No current exercise saved." if data.empty? || blank?(data["exercise"])
+
+        path = data["path"]
+        @ui.title("Current exercise")
+        @ui.key_value("Exercise", @ui.highlight(data.fetch("exercise")))
+        @ui.key_value("Track", data.fetch("track", @track))
+        @ui.key_value("Path", @ui.path(path))
+        @ui.key_value("State", @ui.path(@state.path))
+        @ui.warn("The saved directory no longer exists.") if path && !Dir.exist?(path)
+      end
+
+      def path_command
+        exercise = @resolver.resolve(optional_arg)
+        @ui.say(exercise.path)
+      end
+
+      def list_command
+        raise Error, "Exercise directory not found: #{@root}" unless Dir.exist?(@root)
+
+        current = @state.load["exercise"]
+        exercises = Dir.children(@root)
+                       .select { |name| File.directory?(File.join(@root, name)) && !name.start_with?(".") }
+                       .sort
+
+        if exercises.empty?
+          @ui.warn("No exercises downloaded in #{@root}.")
+          return
+        end
+
+        @ui.section("Downloaded exercises")
+        exercises.each do |slug|
+          marker = slug == current ? "*" : " "
+          label = slug == current ? @ui.highlight(slug) : slug
+          suffix = slug == current ? " #{@ui.muted('current')}" : ""
+          @ui.say("#{marker} #{label}#{suffix}")
+        end
+      end
+
+      def clear_command
+        @state.clear
+        @ui.success("State cleared: #{@state.path}")
+      end
+
+      def help_command
+        @ui.say(<<~HELP)
+          #{@ui.bold('xrb')} - Exercism Ruby helper
+
+          Usage:
+            xrb new <exercise>       download, save as current, and open the editor
+            xrb edit [exercise]      open the editor for an exercise
+            xrb test [exercise]      run the exercise test file with minitest/pride
+            xrb irb [exercise]       open irb -r ./<solution>.rb --simple-prompt
+            xrb submit [exercise]    submit the solution .rb file
+            xrb use <exercise>       save a downloaded exercise as current
+            xrb current              show the current exercise
+            xrb path [exercise]      print the exercise path
+            xrb list                 list downloaded exercises
+            xrb clear                clear saved state
+
+          State:
+            #{@state.path}
+
+          Environment:
+            XRB_ROOT     exercise directory (current: #{@root})
+            XRB_TRACK    Exercism track (current: #{@track})
+            XRB_EDITOR   editor used by xrb edit/new (default: nvim)
+            XRB_STATE    TOML state file
+            XRB_COLOR    color output: auto, always, or never
+        HELP
+      end
+
+      def version_command
+        @ui.say("xrb #{VERSION}")
+      end
+
+      def edit_exercise(exercise)
+        target = editable_target(exercise)
+        editor_args = editor_args_from_config
+        raise Error, "Invalid editor in XRB_EDITOR/VISUAL/EDITOR." if editor_args.empty?
+        ensure_editor_available!(editor_args.first, chdir: exercise.path)
+
+        @ui.info("Opening #{@ui.highlight(exercise.slug)}...")
+        @runner.run(*editor_args, target, chdir: exercise.path)
+      end
+
+      def editor_args_from_config
+        Shellwords.split(Config.editor)
+      rescue ArgumentError => e
+        raise Error, "Invalid editor in XRB_EDITOR/VISUAL/EDITOR: #{e.message}"
+      end
+
+      def ensure_editor_available!(command, chdir:)
+        return if editor_command_available?(command, chdir: chdir)
+
+        raise Error, "Editor not found: #{command}. Set XRB_EDITOR, VISUAL, or EDITOR to an installed executable."
+      end
+
+      def editor_command_available?(command, chdir:)
+        if command_path?(command)
+          return executable_file?(File.absolute_path(command, chdir))
+        end
+
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+          candidate_dir = dir.empty? ? "." : dir
+          executable_file?(File.absolute_path(File.join(candidate_dir, command), chdir))
+        end
+      end
+
+      def command_path?(command)
+        command.include?(File::SEPARATOR) || (File::ALT_SEPARATOR && command.include?(File::ALT_SEPARATOR))
+      end
+
+      def executable_file?(path)
+        File.file?(path) && File.executable?(path)
+      end
+
+      def editable_target(exercise)
+        exercise.solution_file
+      rescue Error
+        "."
+      end
+
+      def save_current(exercise)
+        @state.save(track: exercise.track, exercise: exercise.slug, path: exercise.path)
+      end
+
+      def exercise_from_required_arg(usage, require_existing: true)
+        slug = @argv.shift
+        raise Error, "Usage: xrb #{usage}" if blank?(slug)
+        raise Error, "Too many arguments: #{@argv.join(' ')}" unless @argv.empty?
+
+        Exercise.new(slug: slug, track: @track, root: @root).tap do |exercise|
+          exercise.ensure_exists! if require_existing
+        end
+      end
+
+      def optional_arg
+        slug = @argv.shift
+        raise Error, "Too many arguments: #{@argv.join(' ')}" unless @argv.empty?
+
+        slug
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/exercism/rb/command_runner.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Exercism
+  module Rb
+    class CommandRunner
+      def initialize(ui: UI.new)
+        @ui = ui
+      end
+
+      def run(*args, chdir: nil)
+        printable = Shellwords.join(args)
+        printable = "cd #{Shellwords.escape(chdir)} && #{printable}" if chdir
+        @ui.command("$ #{printable}")
+
+        ok = if chdir
+               Dir.chdir(chdir) { system(*args) }
+             else
+               system(*args)
+             end
+
+        raise Error, "Command failed: #{Shellwords.join(args)}" unless ok
+
+        true
+      end
+    end
+  end
+end

data/lib/exercism/rb/config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Exercism
+  module Rb
+    module Config
+      module_function
+
+      def track
+        ENV.fetch("XRB_TRACK", "ruby")
+      end
+
+      def root(track_name = track)
+        File.expand_path(ENV.fetch("XRB_ROOT", File.join(Dir.home, "exercism", track_name)))
+      end
+
+      def state_path
+        File.expand_path(ENV.fetch("XRB_STATE", File.join(Dir.home, ".local", "state", "exercism-rb", "state.toml")))
+      end
+
+      def editor
+        ENV["XRB_EDITOR"] || ENV["VISUAL"] || ENV["EDITOR"] || "nvim"
+      end
+    end
+  end
+end

data/lib/exercism/rb/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Exercism
+  module Rb
+    class Error < StandardError; end
+  end
+end

data/lib/exercism/rb/exercise.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Exercism
+  module Rb
+    class Exercise
+      SLUG_PATTERN = /\A[a-z0-9][a-z0-9-]*\z/
+
+      attr_reader :slug, :track, :root, :path
+
+      def initialize(slug:, track: Config.track, root: Config.root(track), path: nil)
+        slug = slug.to_s.strip
+        raise Error, "Exercise is required." if slug.empty?
+        raise Error, "Invalid slug: #{slug.inspect}. Use something like assembly-line." unless slug.match?(SLUG_PATTERN)
+
+        @slug = slug
+        @track = track
+        @root = File.expand_path(root)
+        @path = File.expand_path(path || File.join(@root, @slug))
+      end
+
+      def exists?
+        Dir.exist?(@path)
+      end
+
+      def ensure_exists!
+        return self if exists?
+
+        raise Error, "Exercise not found: #{@path}"
+      end
+
+      def test_file
+        ensure_exists!
+        pick_one(files_matching { |name| name.end_with?("_test.rb") }, kind: "test file (*_test.rb)")
+      end
+
+      def solution_file
+        ensure_exists!
+        pick_one(files_matching { |name| name.end_with?(".rb") && !name.end_with?("_test.rb") }, kind: "solution file (.rb)")
+      end
+
+      private
+
+      def files_matching
+        Dir.children(@path)
+           .select { |name| File.file?(File.join(@path, name)) && yield(name) }
+           .sort
+      end
+
+      def pick_one(files, kind:)
+        case files.length
+        when 0
+          raise Error, "Could not find #{kind} in #{@path}"
+        when 1
+          files.first
+        else
+          raise Error, "Found more than one #{kind} in #{@path}: #{files.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/exercism/rb/resolver.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Exercism
+  module Rb
+    class Resolver
+      def initialize(state:, track: Config.track, root: Config.root(track))
+        @state = state
+        @track = track
+        @root = File.expand_path(root)
+      end
+
+      def resolve(slug = nil, require_existing: true)
+        exercise = if present?(slug)
+                     Exercise.new(slug: slug, track: @track, root: @root)
+                   else
+                     from_current_directory || from_state
+                   end
+
+        exercise.ensure_exists! if require_existing
+        exercise
+      end
+
+      private
+
+      def from_current_directory
+        cwd = File.expand_path(Dir.pwd)
+        root_with_separator = @root.end_with?(File::SEPARATOR) ? @root : "#{@root}#{File::SEPARATOR}"
+        return nil unless cwd.start_with?(root_with_separator)
+
+        relative = cwd.delete_prefix(root_with_separator)
+        slug = relative.split(File::SEPARATOR).first
+        return nil unless present?(slug)
+
+        Exercise.new(slug: slug, track: @track, root: @root)
+      end
+
+      def from_state
+        data = @state.load
+        slug = data["exercise"]
+        raise Error, "No current exercise. Use `xrb new <exercise>` or `xrb use <exercise>`." unless present?(slug)
+
+        Exercise.new(
+          slug: slug,
+          track: data["track"] || @track,
+          root: File.dirname(data["path"] || File.join(@root, slug)),
+          path: data["path"]
+        )
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/exercism/rb/state.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+
+module Exercism
+  module Rb
+    class State
+      KEYS = %w[track exercise path updated_at].freeze
+
+      attr_reader :path
+
+      def initialize(path: Config.state_path)
+        @path = File.expand_path(path)
+      end
+
+      def load
+        return {} unless File.file?(@path)
+
+        parse(File.read(@path))
+      end
+
+      def save(track:, exercise:, path:)
+        data = {
+          "track" => track,
+          "exercise" => exercise,
+          "path" => File.expand_path(path),
+          "updated_at" => Time.now.utc.iso8601
+        }
+
+        FileUtils.mkdir_p(File.dirname(@path))
+        tmp_path = "#{@path}.tmp.#{Process.pid}"
+        File.write(tmp_path, to_toml(data))
+        File.rename(tmp_path, @path)
+        data
+      end
+
+      def clear
+        File.delete(@path) if File.file?(@path)
+      end
+
+      private
+
+      def parse(content)
+        data = {}
+
+        content.each_line.with_index(1) do |line, number|
+          stripped = line.strip
+          next if stripped.empty? || stripped.start_with?("#")
+
+          match = stripped.match(/\A([A-Za-z0-9_-]+)\s*=\s*(.+)\z/)
+          raise Error, "Invalid state in #{@path}: line #{number}" unless match
+
+          key = match[1]
+          next unless KEYS.include?(key)
+
+          data[key] = parse_value(match[2].strip)
+        end
+
+        data
+      end
+
+      def parse_value(raw)
+        quoted_start = raw.start_with?("\"")
+        quoted_end = raw.end_with?("\"")
+        raise Error, "Invalid quoted value in #{@path}" if quoted_start != quoted_end
+
+        return unquote(raw) if raw.start_with?("\"") && raw.end_with?("\"")
+
+        raw
+      end
+
+      def unquote(raw)
+        value = raw[1...-1]
+        value.gsub(/\\(["\\nrt])/) do
+          case Regexp.last_match(1)
+          when '"' then '"'
+          when "\\" then "\\"
+          when "n" then "\n"
+          when "r" then "\r"
+          when "t" then "\t"
+          end
+        end
+      end
+
+      def to_toml(data)
+        KEYS.filter_map do |key|
+          next unless data.key?(key)
+
+          "#{key} = #{quote(data.fetch(key))}"
+        end.join("\n") + "\n"
+      end
+
+      def quote(value)
+        escaped = value.to_s
+                       .gsub("\\", "\\\\")
+                       .gsub('"', '\\"')
+                       .gsub("\n", "\\n")
+                       .gsub("\r", "\\r")
+                       .gsub("\t", "\\t")
+
+        %("#{escaped}")
+      end
+    end
+  end
+end

data/lib/exercism/rb/ui.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Exercism
+  module Rb
+    class UI
+      COLORS = {
+        blue: "\e[34m",
+        cyan: "\e[36m",
+        green: "\e[32m",
+        red: "\e[31m",
+        yellow: "\e[33m",
+        gray: "\e[90m",
+        bold: "\e[1m",
+        reset: "\e[0m"
+      }.freeze
+
+      def initialize(out: $stdout, err: $stderr, color: nil)
+        @out = out
+        @err = err
+        @color = color.nil? ? default_color? : color
+      end
+
+      def say(message = "")
+        @out.puts(message)
+      end
+
+      def title(message)
+        @out.puts(bold(message))
+      end
+
+      def section(message)
+        @out.puts(paint(message, :cyan))
+      end
+
+      def key_value(key, value, width: 8)
+        label = key.to_s.ljust(width)
+        @out.puts("#{paint(label, :gray)} #{value}")
+      end
+
+      def path(value)
+        paint(value, :blue)
+      end
+
+      def highlight(value)
+        paint(value, :bold)
+      end
+
+      def muted(value)
+        paint(value, :gray)
+      end
+
+      def info(message)
+        @out.puts("#{paint('info', :blue)} #{message}")
+      end
+
+      def success(message)
+        @out.puts("#{paint('done', :green)} #{message}")
+      end
+
+      def warn(message)
+        @err.puts("#{paint('warn', :yellow)} #{message}")
+      end
+
+      def error(message)
+        @err.puts("#{paint('error', :red)} #{message}")
+      end
+
+      def command(message)
+        @out.puts(paint(message, :gray))
+      end
+
+      def bold(message)
+        paint(message, :bold)
+      end
+
+      private
+
+      def default_color?
+        color_mode = ENV.fetch("XRB_COLOR", "").strip.downcase
+
+        return true if %w[always force true yes 1].include?(color_mode)
+        return false if %w[never none false no 0].include?(color_mode)
+        return false if ENV.key?("NO_COLOR")
+        return true if force_color?
+        return false if ENV.fetch("CLICOLOR", nil) == "0"
+
+        @out.tty?
+      end
+
+      def paint(message, color)
+        return message unless @color
+
+        "#{COLORS.fetch(color)}#{message}#{COLORS.fetch(:reset)}"
+      end
+
+      def force_color?
+        value = ENV.fetch("CLICOLOR_FORCE", nil)
+        !value.nil? && !value.empty? && value != "0"
+      end
+    end
+  end
+end

data/lib/exercism/rb/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Exercism
+  module Rb
+    VERSION = "0.1.0"
+  end
+end

data/lib/exercism/rb.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "rb/version"
+require_relative "rb/config"
+require_relative "rb/error"
+require_relative "rb/ui"
+require_relative "rb/state"
+require_relative "rb/exercise"
+require_relative "rb/resolver"
+require_relative "rb/command_runner"
+require_relative "rb/cli"

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: exercism-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- hvpaiva
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+description: A small command-line helper that keeps Exercism Ruby exercises easy to
+  open, test, inspect, and submit.
+email:
+- hvpaiva@users.noreply.github.com
+executables:
+- xrb
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/xrb
+- lib/exercism/rb.rb
+- lib/exercism/rb/cli.rb
+- lib/exercism/rb/command_runner.rb
+- lib/exercism/rb/config.rb
+- lib/exercism/rb/error.rb
+- lib/exercism/rb/exercise.rb
+- lib/exercism/rb/resolver.rb
+- lib/exercism/rb/state.rb
+- lib/exercism/rb/ui.rb
+- lib/exercism/rb/version.rb
+homepage: https://github.com/hvpaiva/exercism-rb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  bug_tracker_uri: https://github.com/hvpaiva/exercism-rb/issues
+  changelog_uri: https://github.com/hvpaiva/exercism-rb/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/hvpaiva/exercism-rb
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/hvpaiva/exercism-rb
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Exercism Ruby workflow helper CLI
+test_files: []