genie_cli 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4582658de3ff1e9145b81a2975b973f7aebbc1762f8d7a21bb6237c211225558
+  data.tar.gz: 79b2870a69918c5c7eba6a72ca1a8d5e5284392304c39833cf61f74e19686eae
+SHA512:
+  metadata.gz: eaf263a55c387b7e021afbc3dd161d47e38307ccf09a6ec5bfd952237f739bb74720fe23efcfd5873030d7bcc1af11540198c760f99438254562aabb39002f3f
+  data.tar.gz: 5e1cac00335cc946e3bbcbe04f2b6017861033186810523ac33e40ab56f763d28ba73d6b1cedbdaca755a3737aeb0048140d789ab8e43fac34ec243cab8093dc

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jeff McFadden
+
+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,107 @@
+# Genie CLI
+
+Genie CLI is a command-line tool that brings Test Driven Development (TDD) 
+principles to life by integrating with a large language model (LLM) through 
+the `ruby_llm` library. It provides an interactive session where you can ask 
+the AI assistant to write tests, implement code, and manage your codebase—all 
+while enforcing a strict TDD workflow.
+
+## Features
+
+- Interactive REPL-style session powered by OpenAI (or any provider supported by `ruby_llm`).
+- Built-in tools for common file operations:
+  - `ListFiles`: List and filter files in your project directory.
+  - `ReadFile`: Read the contents of files.
+  - `WriteFile`: Create or overwrite files.
+  - `InsertIntoFile`: Insert content at a specific marker in a file.
+  - `AppendToFile`: Append content to existing files.
+  - `RunTests`: Run your test suite and capture results.
+  - `TakeANote`: Write notes without affecting your source files.
+  - `AskForHelp`: Request guidance or explanations from the AI.
+- Enforces Genie workflow: tests first, implementation second.
+- Restricts file operations to your project directory for safety.
+
+## Installation
+
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/jeffmcfadden/genie_cli.git
+   cd genie_cli
+   ```
+
+2. Install dependencies using Bundler:
+   ```bash
+   bundle install
+   ```
+
+3. Set your OpenAI API key (or other LLM provider keys) in your environment:
+   ```bash
+   export OPENAI_API_KEY="your_api_key_here"
+   ```
+
+4. Make the CLI executable:
+   ```bash
+   chmod +x bin/genie
+   ```
+
+## Usage
+
+Start a Genie session by running the `genie` command from the root of your project:
+
+```bash
+./bin/genie ["initial prompt or command"]
+```
+
+- If you provide an initial prompt, the assistant will immediately respond. Otherwise, you'll enter an interactive prompt where you can type your questions or commands.
+- To quit the session, type `q`, `quit`, `done`, or `exit`.
+
+Example session:
+
+```bash
+$ ./bin/genie
+Starting a new session with:
+ base_path: /Users/you/projects/genie_cli
+
+ > "Create a failing test for a Calculator#add method"
+
+# (AI writes a test file)
+
+ > "Implement Calculator#add to pass the test"
+
+# (AI writes the implementation)
+
+ > "Run the test suite"
+
+# (AI invokes `rake test` and reports results)
+
+ > "exit"
+Exiting...
+Total Conversation Tokens: 1234
+```
+
+## Logging
+
+The output of `genie` to the terminal includes "essential" output, but not 
+_all_ output. To aid in debugging, the full RubyLLM debug log is saved to 
+`ruby_llm.log`. This can be useful for auditing what's happened during a 
+session in great detail.
+
+## Configuration
+
+Configuration is available via a `genie.yml` file in the project root.
+
+## Testing
+
+This project includes a comprehensive test suite. Run all tests with:
+
+```bash
+bundle exec rake test
+```
+
+## Contributing
+
+Contributions are welcome! Please fork the repository and open pull requests for new features or bug fixes. Make sure to follow the Genie workflow and include tests for new functionality.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

data/Rakefile

@@ -0,0 +1,8 @@
+# Rakefile
+
+desc "Run tests with tldr"
+task :test do
+  sh "bundle exec tldr --no-warnings"
+end
+
+task default: :test

data/bin/genie

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/genie"
+
+config = Genie::SessionConfig.from_argv(ARGV)
+
+# Start the CLI with provided arguments
+Genie::Cli.new(config: config).run

data/lib/genie/cli.rb

@@ -0,0 +1,20 @@
+require 'optparse'
+
+module Genie
+
+  class Cli
+    def initialize(config:)
+      @config = config
+    end
+
+    def run
+      session = Session.new(config: @config)
+
+      # Trap CTRL+C to exit gracefully
+      Signal.trap("INT") { session.complete }
+
+      # Begin the session with the first CLI argument (or nil)
+      session.begin(@args&.last)
+    end
+  end
+end

data/lib/genie/sandboxed_file_tool.rb

@@ -0,0 +1,22 @@
+module Genie
+  module SandboxedFileTool
+
+
+    def initialize(base_path:)
+      @base_path = base_path
+      @base_path.freeze
+    end
+
+    def within_sandbox?(filepath)
+      filepath = File.expand_path(filepath)
+      filepath.start_with?(@base_path)
+    end
+
+    def enforce_sandbox!(filepath)
+      unless within_sandbox?(filepath)
+        raise ArgumentError, "File not allowed: #{filepath}. Must be within base path: #{@base_path}"
+      end
+    end
+
+  end
+end

data/lib/genie/session.rb

@@ -0,0 +1,83 @@
+module Genie
+  class Session
+    extend Forwardable
+
+    attr_reader :config
+
+    # Supported commands to exit the session
+    QUIT_COMMANDS = ["q", "quit", "done", "exit", "bye"].freeze
+
+    # Config holds these for us
+    def_delegators :@config, :model, :base_path, :run_tests_cmd, :instructions
+
+    # Initializes the session with a pre-loaded configuration
+    # config: instance of Genie::SessionConfig
+    def initialize(config:)
+      @config = config
+
+      Genie.output "Starting a new session with:\n base_path: #{base_path}\n model: #{model}\n", color: :green
+
+      # Initialize the LLM chat with the specified model
+      @chat = RubyLLM.chat(model: model)
+
+      # Use Genie-specific instructions from config
+      @chat.with_instructions instructions
+
+      # Provide file tools for the assistant, scoped to base_path
+      @chat.with_tools(
+        Genie::AppendToFile.new(base_path: base_path),
+        Genie::AskForHelp.new,
+        # Genie::InsertIntoFile.new(base_path: base_path),
+        Genie::ListFiles.new(base_path: base_path),
+        Genie::ReadFile.new(base_path: base_path),
+        Genie::RenameFile.new(base_path: base_path),
+        # Genie::ReplaceLinesInFile.new(base_path: base_path),
+        Genie::RunTests.new(base_path: base_path, cmd: run_tests_cmd),
+        Genie::TakeANote.new,
+        Genie::WriteFile.new(base_path: base_path),
+      )
+    end
+
+    def begin(q)
+      q = q.to_s
+
+      loop do
+        complete if QUIT_COMMANDS.include? q.downcase
+
+        begin
+          ask q unless q.strip == ""
+        rescue RubyLLM::RateLimitError => e
+          Genie.output "Rate limit exceeded: #{e.message}", color: :red
+        end
+
+        q = prompt
+      end
+    end
+
+    # Send a question to the LLM and output both prompt and response
+    def ask(question)
+      Genie.output "#{question}\n", color: :white
+
+      response = @chat.ask(question)
+
+      Genie.output "\n#{response.content}", color: :white
+
+      response
+    end
+
+    def prompt
+      print "\n > "
+      STDIN.gets.chomp
+    end
+
+    def complete
+      Genie.output "\nExiting...", color: :white
+
+      total_conversation_tokens = @chat.messages.sum { |msg| (msg.input_tokens || 0) + (msg.output_tokens || 0) }
+      Genie.output "Total Conversation Tokens: #{total_conversation_tokens}", color: :white
+
+      exit
+    end
+
+  end
+end

data/lib/genie/session_config.rb

@@ -0,0 +1,110 @@
+require 'yaml'
+
+module Genie
+  # Handles loading of session configuration such as run_tests_cmd
+  class SessionConfig
+    # Read-only attributes
+    attr_reader :base_path, :run_tests_cmd, :model, :first_question, :instructions
+
+    DEFAULT_INSTRUCTIONS = <<~INSTRUCTIONS
+      # Genie Instructions
+      You are a Genie coding assistant. You help me write code using Test Driven Development
+      (Genie) principles. You have some tools available to you, such as listing files, reading files, and writing files,
+      and you can write code in Ruby. You will always write tests first, and then implement
+      the code to pass those tests. You will not write any code that does not have a test.
+
+      # Rules
+      1. We do not have access to any files outside of the base_path.
+      2. We do not have access to the internet.
+      3. You will always write tests first, and then implement the code to pass those tests.
+    INSTRUCTIONS
+
+    DEFAULTS = {
+      base_path: ".",
+      run_tests_cmd: 'rake test',
+      model: 'gpt-4o-mini',
+      first_question: nil,
+      instructions: DEFAULT_INSTRUCTIONS
+    }
+
+    def self.from_argv(argv)
+      cli_options = {}
+      config_file = File.expand_path "./genie.yml"
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: genie [options]"
+
+        opts.on("-c", "--config FILE", "Path to config file") do |file|
+          config_file = File.expand_path(file)
+        end
+
+        opts.on("-b", "--base-path PATH", "Base path for the session") do |path|
+          cli_options[:base_path] = path
+        end
+
+        opts.on("-r", "--run-tests CMD", "Command to run tests") do |cmd|
+          cli_options[:run_tests_cmd] = cmd
+        end
+
+        opts.on("-m", "--model NAME", "Name of model to use") do |name|
+          cli_options[:model] = name
+        end
+
+        opts.on("-i", "--instructions TEXT", "Instructions for the session") do |text|
+          cli_options[:instructions] = text
+        end
+
+        opts.on("-v", "--[no-]verbose", "Enable verbose mode") do |v|
+          cli_options['verbose'] = v
+        end
+      end.parse!(argv)
+
+      # Last remaining argument is the first question
+      cli_options[:first_question] = argv.last if argv.any?
+
+      file_config = {}
+      if config_file && File.exist?(config_file)
+        file_config = YAML.load_file(config_file, symbolize_names: true)
+      end
+
+      # 3️⃣ Merge: DEFAULT < FILE < CLI
+      final_config = DEFAULTS.merge(file_config).merge(cli_options)
+
+      # We always preface the instructions with context
+      final_config[:instructions] = <<~PREFACE
+      # Context
+      Current Date and Time: #{Time.now.iso8601}
+      We are working in a codebase located at '#{final_config[:base_path]}'.
+
+      #{final_config[:instructions]}
+      PREFACE
+
+      new(
+        base_path: final_config[:base_path],
+        run_tests_cmd: final_config[:run_tests_cmd],
+        model: final_config[:model],
+        first_question: final_config[:first_question],
+        instructions: final_config[:instructions]
+      )
+    end
+
+    def self.default
+      new(
+        base_path: DEFAULTS[:base_path],
+        run_tests_cmd: DEFAULTS[:run_tests_cmd],
+        model: DEFAULTS[:model],
+        first_question: DEFAULTS[:first_question],
+        instructions: DEFAULTS[:instructions]
+      )
+    end
+
+    def initialize(base_path:, run_tests_cmd:, model:, first_question:, instructions:)    # Requires both base_path and run_tests_cmd
+      @base_path = File.expand_path(base_path)
+      @run_tests_cmd = run_tests_cmd
+      @model = model
+      @first_question = first_question
+      @instructions = instructions
+    end
+
+  end
+end

data/lib/genie/version.rb

@@ -0,0 +1,3 @@
+module Genie
+  VERSION = '0.1.1'
+end

data/lib/genie.rb

@@ -0,0 +1,69 @@
+require "ruby_llm"
+require "dotenv/load"
+require "tty-command"
+
+$LOAD_PATH.unshift (File.expand_path('../lib', __dir__))
+
+require "genie/sandboxed_file_tool"
+require "genie/version"
+require "genie/session_config"
+require "genie/session"
+require "tools/append_to_file"
+require "tools/list_files"
+require "tools/read_file"
+require "tools/write_file"
+require "tools/replace_lines_in_file"
+require "tools/rename_file"
+require "tools/run_tests"
+require "tools/take_a_note"
+require "tools/insert_into_file"
+require "tools/ask_for_help"
+require "genie/cli"
+
+RubyLLM.configure do |config|
+  # Set keys for the providers you need. Using environment variables is best practice.
+  config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
+  # Add other keys like config.anthropic_api_key if needed
+
+  config.gemini_api_key = ENV.fetch('GEMINI_API_KEY', nil)  # Set your Gemini API key
+
+  config.log_file = 'ruby_llm.log'  # Log file path
+  config.log_level = :debug  # Log level (:debug, :info, :warn)
+end
+
+module Genie
+  def self.output(s, color: :white)
+    return if quiet?
+
+    # This method is used to output messages in a consistent format.
+    # You can customize the color or format as needed.
+    puts "\e[32m#{s}\e[0m" if color == :green
+    puts "\e[31m#{s}\e[0m" if color == :red
+    puts "\e[33m#{s}\e[0m" if color == :yellow
+    puts "\e[34m#{s}\e[0m" if color == :blue
+    puts "\e[35m#{s}\e[0m" if color == :magenta
+    puts "\e[36m#{s}\e[0m" if color == :cyan
+
+    puts "\e[37m#{s}\e[0m" if color == :white
+  end
+
+  def self.quiet=(value)
+    # This method can be used to set a quiet mode for the output.
+    # If true, it suppresses the output.
+    @quiet = value
+  end
+
+  def self.quiet?
+    @quiet || false
+  end
+
+  def self.reset_quiet!
+    @quiet = false
+  end
+
+  def self.quiet!
+    # This method can be used to enable quiet mode.
+    @quiet = true
+  end
+
+end

data/lib/tools/append_to_file.rb

@@ -0,0 +1,33 @@
+require "fileutils"
+
+module Genie
+  class AppendToFile < RubyLLM::Tool
+    include SandboxedFileTool
+
+    description "Append a string to an existing file."
+    param :filepath, desc: "The path to the file to append to (e.g., '/home/user/documents/file.txt'). File must already exist."
+    param :content, desc: "The content to append to the file"
+
+    def execute(filepath:, content:)
+      filepath = File.expand_path(filepath)
+
+      Genie.output "Appending to file: #{filepath}", color: :blue
+
+      enforce_sandbox!(filepath)
+
+      indented = content.each_line.map { |line| "  #{line}" }.join
+      Genie.output indented, color: :green
+
+      raise "File not found. Cannot append to a non-existent file." unless File.exist?(filepath)
+
+      File.open(filepath, "a") do |file|
+        file.write(content)
+      end
+
+      { success: true }
+    rescue => e
+      Genie.output "Error: #{e.message}", color: :red
+      { error: e.message }
+    end
+  end
+end

data/lib/tools/ask_for_help.rb

@@ -0,0 +1,14 @@
+module Genie
+  class AskForHelp < RubyLLM::Tool
+    description "Ask for help. If you can't seem to get something to work, or you get repeated errors, use this tool to ask the user to intervene. Use only when absolutely necessary."
+    param :message, desc: "The message you want the user to see. Include any helpful details!"
+
+    def execute(message:)
+      Genie.output "Help! \n#{message}\n", color: :red
+
+      {
+        status: "User has been asked for help. We should wait until we get input from them.",
+      }
+    end
+  end
+end

data/lib/tools/insert_into_file.rb

@@ -0,0 +1,58 @@
+require "fileutils"
+
+module Genie
+  class InsertIntoFile < RubyLLM::Tool
+    include SandboxedFileTool
+
+    description "Insert a string into an existing file at a specified line number."
+    param :filepath, desc: "The path to the file to insert into (e.g., '/home/user/documents/file.txt'). File must already exist."
+    param :content, desc: "The content to insert into the file"
+    param :line_number, desc: "The 1-based line number at which to insert the content"
+
+    def execute(filepath:, content:, line_number:)
+      line_number = line_number.to_i
+
+      # Expand the filepath to an absolute path
+      filepath = File.expand_path(filepath)
+
+      Genie.output "Inserting into file: #{filepath}", color: :blue
+
+      enforce_sandbox!(filepath)
+
+      # Check file exists
+      unless File.exist?(filepath)
+        raise "File not found. Cannot insert into a non-existent file."
+      end
+
+      # Read existing lines
+      lines = File.readlines(filepath)
+
+      # Validate line_number
+      total_lines = lines.size
+      if !line_number.is_a?(Integer) || line_number < 1 || line_number > total_lines + 1
+        raise ArgumentError, "Invalid line number: #{line_number}. Must be between 1 and #{total_lines + 1}."
+      end
+
+      # Prepare content lines
+      content_lines = content.each_line.to_a
+
+      # Show the content to be inserted
+      indented = content.each_line.map { |line| "  #{line}" }.join
+      Genie.output indented, color: :green
+
+      # Perform insertion
+      index = line_number - 1
+      new_lines = lines[0...index] + content_lines + lines[index..-1]
+
+      # Write back
+      File.open(filepath, "w") do |file|
+        file.write(new_lines.join)
+      end
+
+      { success: true }
+    rescue => e
+      Genie.output "Error: #{e.message}", color: :red
+      { error: e.message }
+    end
+  end
+end

data/lib/tools/list_files.rb

@@ -0,0 +1,61 @@
+module Genie
+
+  class ListFiles < RubyLLM::Tool
+    include SandboxedFileTool
+
+    description "Lists the files in the given directory"
+    param :directory, desc: "Directory path to list files from (e.g., '/home/user/documents')"
+    param :recursive, desc: "Whether to list files recursively (default: false)"
+    param :filter, desc: "Filter string to include only paths that include this substring (Optional)"
+
+    def execute(directory:, recursive: false, filter: nil)
+      directory = File.expand_path(directory, @base_path)
+
+      Genie.output "Listing files in directory: #{directory} (recursive: #{recursive})", color: :blue
+
+      raise ArgumentError, "Directory not allowed: #{directory}. Must be within base path: #{@base_path}" unless directory.start_with?(@base_path)
+
+      listing = recursive ? list_recursive(directory) : list_non_recursive(directory)
+
+      # Apply filter if provided
+      if filter && !filter.empty?
+        listing = listing.select { |entry| entry[:name].include?(filter) }
+      end
+
+      Genie.output listing.map { |e| e[:name] }.join("\n") + "\n", color: :green
+
+      listing
+    rescue => e
+      Genie.output "Error: #{e.message}", color: :red
+      { error: e.message }
+    end
+
+    private
+
+    def list_recursive(directory)
+      Dir.glob(File.join(directory, '**', '*')).map do |file_path|
+        # next if File.basename(file_path).start_with?('.') # Skip hidden files
+
+        {
+          name: file_path,
+          type: File.file?(file_path) ? 'file' : 'directory',
+        }
+      end.compact
+    end
+
+    def list_non_recursive(directory)
+      Dir.each_child(directory).map do |filename|
+        next if filename.start_with?('.') # Skip hidden files
+
+        file_path = File.join(directory, filename)
+
+        {
+          name: filename,
+          type: File.file?(file_path) ? 'file' : 'directory',
+        }
+      end.compact # Remove any nil entries (e.g., hidden files or directories)
+    end
+
+  end
+
+end

data/lib/tools/read_file.rb

@@ -0,0 +1,34 @@
+module Genie
+  class ReadFile < RubyLLM::Tool
+    include SandboxedFileTool
+
+    description "Reads the contents of a file and returns its content"
+    param :filepath, desc: "The path to the file to read (e.g., '/home/user/documents/file.txt')"
+    param :include_line_numbers, desc: "Whether to include line numbers (default: false)"
+
+    def execute(filepath:, include_line_numbers: false)
+      filepath = File.expand_path(filepath)
+
+      Genie.output "Reading file: #{filepath}", color: :blue
+
+      enforce_sandbox!(filepath)
+
+      lines = File.readlines(filepath)
+      contents = if include_line_numbers
+        width = lines.size.to_s.length
+        lines.each_with_index.map do |line, index|
+          number = (index + 1).to_s.rjust(width)
+          "#{number}: #{line}"
+        end.join
+      else
+        lines.join
+      end
+
+      { contents: contents }
+    rescue => e
+      Genie.output "Error: #{e.message}", color: :red
+
+      { error: e.message }
+    end
+  end
+end