ruby-ai-gem-context 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0dc306be58bfc24b0b508a23cd444aba6682c041ca60ef46b8db016aafed892
+  data.tar.gz: 5ff91acacb8dcb6d4b4d137800b0fd04ec7da93a1600e8ac5d55c517b8cc9b8b
+SHA512:
+  metadata.gz: 3fd5f1c0470fdd08b11f5a944d63b544e7234b3d80645d329263862794d77b24b4c464df59ddaedfcca93c1d014ae5551685125c2fb0b3cedd3e3a84da338a51
+  data.tar.gz: c4e22122c4e218ee4735309c57543a8bc75861992abe4a43f4eea7b148df38aae72414771a553aecc32237b7ee5f2137a5d4b5d28e19467087b2e76bfac71471

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,81 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-02-27
+
+### Added
+
+- **Multi-platform support**: Generate context files for Claude, Cursor, Windsurf, Codex, and llm.txt
+- **Interactive rake tasks** with colored terminal UI using `tty-prompt`:
+  - `rake ai_context:setup` - Scaffolds boilerplate context files for chosen platforms
+  - `rake ai_context:generate` - Fills context files with AI-generated content
+  - `rake ai_context:generate_for_gem[name]` - Generate context for third-party gems
+  - `rake ai_context:list` - List generated context files
+  - `rake ai_context:clear` - Remove generated files
+- **RubyLLM integration** for AI generation with support for multiple providers (Anthropic, OpenAI, etc.)
+- **Platform system** with dedicated classes for each AI tool:
+  - `Platforms::Claude` - CLAUDE.md
+  - `Platforms::Cursor` - .cursorrules
+  - `Platforms::Windsurf` - .windsurfrules
+  - `Platforms::Codex` - AGENTS.md
+  - `Platforms::LlmTxt` - llm.txt
+- **ConfigFile** tracks generated files in `.ai_context/config.yml`
+- **FileCollector** scans project files with configurable include/exclude patterns
+- **Collision handling** - Backup, skip, or overwrite existing files
+- **Model documentation** with guidance on choosing models for quality vs. cost
+- **Review reminder** emphasizing the importance of manually reviewing AI output
+
+### Changed
+
+- Complete architecture redesign focused on interactive rake tasks
+- Replaced custom AI providers with RubyLLM gem
+- Files now placed at native locations (project root) instead of managed subfolder
+- Simplified configuration to focus on model selection and file patterns
+
+### Removed
+
+- CLI binary (`exe/ruby_ai_gem_context`) - replaced by rake tasks
+- Custom provider classes (Anthropic, OpenAI) - now uses RubyLLM
+- Extractors (README, Code, Test) - simplified to FileCollector
+- Cache system - regenerate as needed
+- Scanner and Aggregator - no longer needed for new architecture
+- AuthorContext and SkillBuilder - simplified approach
+
+## [0.3.0] - 2026-02-13
+
+### Added
+
+- CLI binary with commands: `generate`, `init`, `list`, `clear`, `help`
+- AI-powered generation using Anthropic or OpenAI providers
+- AuthorContext detection from gems
+- Generator with extractors
+- SkillBuilder for installing to ~/.claude/skills/
+- Cache system
+
+### Changed
+
+- Architecture overhaul to full generation pipeline
+
+## [0.2.0] - 2026-02-12
+
+### Added
+
+- Agent Skills Standard Support
+
+### Changed
+
+- Default output path to `.claude/skills/`
+
+## [0.1.0] - 2026-02-03
+
+### Added
+
+- Initial release with Scanner and Aggregator
+- Rails integration via Railtie
+- Basic rake tasks

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alvaro Delgado
+
+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,236 @@
+# 🤖 ruby-ai-gem-context
+
+**Make AI coding assistants actually understand your Ruby project.**
+
+Stop explaining your codebase over and over. This gem generates context files that AI assistants read *before* they help you — so they already know your architecture, conventions, and patterns.
+
+[![Gem Version](https://badge.fury.io/rb/ruby-ai-gem-context.svg)](https://rubygems.org/gems/ruby-ai-gem-context)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+---
+
+## The Problem
+
+Every time you start a conversation with an AI coding assistant, you waste time explaining:
+- "We use service objects, not fat models"
+- "Authentication is handled by Devise with custom strategies"
+- "Don't suggest RSpec — we use Minitest"
+
+**The solution**: Context files that AI assistants read automatically.
+
+## Supported Platforms
+
+| Platform | File | Description |
+|----------|------|-------------|
+| Claude Code | `CLAUDE.md` | Project context for Claude AI |
+| Cursor | `.cursorrules` | Rules and context for Cursor IDE |
+| Windsurf | `.windsurfrules` | Rules for Windsurf IDE |
+| OpenAI Codex/ChatGPT | `AGENTS.md` | Documentation for AI agents |
+| llm.txt | `llm.txt` | Universal LLM context (like robots.txt for AI) |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'ruby-ai-gem-context'
+```
+
+Or install directly:
+
+```bash
+gem install ruby-ai-gem-context
+```
+
+## ⚡ Quick Start
+
+```bash
+# 1. Setup: Create boilerplate files for your chosen platforms
+rake ai_context:setup
+
+# 2. Generate: Fill files with AI-generated content from your code
+rake ai_context:generate
+
+# 3. Review and edit the generated files!
+```
+
+That's it. Your AI assistant now understands your project *before* you ask your first question.
+
+## 🛠️ Rake Tasks
+
+### `rake ai_context:setup`
+
+Interactive wizard to create boilerplate context files:
+
+```
+$ rake ai_context:setup
+
+══════════════════════════════════════════════════
+ AI Context Setup
+══════════════════════════════════════════════════
+
+Which platforms do you want to generate context files for?
+  ◉ Claude Code (CLAUDE.md)
+  ◯ Cursor (.cursorrules)
+  ◉ Windsurf (.windsurfrules)
+  ◯ OpenAI Codex / ChatGPT (AGENTS.md)
+  ◯ llm.txt (llm.txt)
+
+✓ Created CLAUDE.md
+✓ Created .windsurfrules
+```
+
+If a file already exists, you'll be asked whether to skip, backup, or overwrite it.
+
+### `rake ai_context:generate`
+
+Fill your context files with AI-generated content:
+
+```
+$ rake ai_context:generate
+
+Where should we read source files from?
+› Project root (scan everything)
+  Specific folders (you'll provide a list)
+
+Will scan 47 files (23.5 KB)
+File types: .rb: 35, .rake: 5, .md: 7
+
+Using model: claude-sonnet-4-20250514
+
+⠋ Generating Claude Code context...
+✓ Generated CLAUDE.md
+
+⚠ IMPORTANT: Review the generated files carefully!
+  AI-generated context is a first draft. The quality of your future
+  AI interactions depends on the accuracy of these files.
+```
+
+### `rake ai_context:generate_for_gem[gem_name]`
+
+Generate context for a third-party gem:
+
+```bash
+rake ai_context:generate_for_gem[devise]
+```
+
+This reads the installed gem's source and generates context files saved to `.ai_context/gems/devise/`.
+
+### Other Tasks
+
+```bash
+rake ai_context:list   # List generated context files
+rake ai_context:clear  # Remove generated files
+```
+
+## ⚙️ Configuration
+
+Configure via Ruby:
+
+```ruby
+RubyAiGemContext.configure do |config|
+  # AI model to use (see "Choosing a Model" below)
+  config.model = "claude-sonnet-4-20250514"
+
+  # Generation parameters
+  config.temperature = 0.3
+  config.max_tokens = 4000
+
+  # File patterns to scan
+  config.include_patterns = %w[**/*.rb README* CHANGELOG*]
+  config.exclude_patterns = %w[vendor/** spec/** test/**]
+end
+```
+
+Or in Rails (`config/application.rb`):
+
+```ruby
+config.ruby_ai_gem_context.model = "gpt-4o"
+```
+
+## 🧠 Choosing a Model
+
+The model you choose directly affects the quality of generated context:
+
+| Model | Quality | Speed | Cost | Best For |
+|-------|---------|-------|------|----------|
+| `claude-sonnet-4-20250514` | High | Fast | Medium | **Recommended** - good balance |
+| `claude-opus-4-20250514` | Highest | Slow | High | Complex codebases |
+| `claude-haiku-4-20250514` | Good | Fastest | Low | Quick iterations |
+| `gpt-4o` | High | Fast | Medium | OpenAI preference |
+| `gpt-4o-mini` | Good | Fastest | Low | Budget-conscious |
+
+**Important**: Quality matters! The context files help AI understand your codebase. Poor context leads to poor AI assistance. Consider using a higher-quality model and reviewing the output carefully.
+
+### Setting Your API Key
+
+The gem uses [RubyLLM](https://github.com/crmne/ruby_llm) which auto-detects your API key from environment variables:
+
+```bash
+# For Anthropic Claude models
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# For OpenAI models
+export OPENAI_API_KEY=sk-...
+```
+
+## ⚠️ Review Your Generated Files
+
+**This is important**: AI-generated context is a first draft, not a finished product.
+
+The quality of your future AI interactions depends on accurate context files. Take time to:
+
+1. **Read through each generated file** — Does it accurately describe your project?
+2. **Fix inaccuracies** — Remove wrong assumptions, correct misunderstandings
+3. **Add project-specific details** — Coding conventions, architecture decisions, gotchas
+4. **Remove generic content** — Replace boilerplate with specifics
+5. **Keep it updated** — Regenerate or manually update as your project evolves
+
+> 💡 **Think of it as an investment**: 30 minutes reviewing context now saves hours of correcting AI mistakes later.
+
+## 🏗️ Architecture
+
+```
+lib/ruby_ai_gem_context/
+├── configuration.rb     # Global settings
+├── platform.rb          # Base class for platforms
+├── platforms/
+│   ├── claude.rb        # CLAUDE.md
+│   ├── cursor.rb        # .cursorrules
+│   ├── windsurf.rb      # .windsurfrules
+│   ├── codex.rb         # AGENTS.md
+│   └── llm_txt.rb       # llm.txt
+├── config_file.rb       # Track generated files in .ai_context/config.yml
+├── file_collector.rb    # Scan and read project files
+├── generator.rb         # AI generation via RubyLLM
+├── interactive.rb       # Terminal UI with tty-prompt
+├── railtie.rb           # Rails integration
+└── tasks/
+    └── ruby_ai_gem_context.rake
+```
+
+## 📋 Requirements
+
+- Ruby 3.0+
+- Rails 7.0+ (optional, for Railtie integration)
+
+## 🧑‍💻 Development
+
+```bash
+git clone https://github.com/AAlvAAro/ruby-ai-gem-context
+cd ruby-ai-gem-context
+bundle install
+rake spec
+```
+
+## 🤝 Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a Pull Request
+
+## 📄 License
+
+This gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+# Load gem tasks for non-Rails usage
+namespace :ruby_ai_gem_context do
+  require_relative "lib/ruby_ai_gem_context"
+
+  desc "Aggregate mcp_context/ from all gems into .ai_context/"
+  task :aggregate do
+    puts "Scanning gems for mcp_context/ folders..."
+
+    result = RubyAiGemContext::Aggregator.aggregate
+    gems = result["gems"]
+
+    if gems.empty?
+      puts "No gems with mcp_context/ folders found."
+    else
+      puts "\nAggregated context from #{gems.size} gem(s):"
+      gems.each do |name, info|
+        puts "  - #{name} (#{info['version']}): #{info['files'].size} file(s)"
+      end
+      puts "\nContext written to: #{RubyAiGemContext.configuration.output_path}/"
+    end
+  end
+
+  desc "Remove the .ai_context/ folder"
+  task :clear do
+    output_path = RubyAiGemContext.configuration.output_path
+    if File.exist?(output_path)
+      RubyAiGemContext::Aggregator.clear
+      puts "Removed #{output_path}/"
+    else
+      puts "#{output_path}/ does not exist."
+    end
+  end
+
+  desc "List all gems that have mcp_context/ folders"
+  task :list do
+    puts "Scanning gems for mcp_context/ folders..."
+
+    gems = RubyAiGemContext::Scanner.list_gems_with_context
+
+    if gems.empty?
+      puts "No gems with mcp_context/ folders found."
+    else
+      puts "\nFound #{gems.size} gem(s) with mcp_context/:"
+      gems.each do |gem_info|
+        puts "  - #{gem_info[:name]} (#{gem_info[:version]})"
+        puts "    Path: #{gem_info[:path]}"
+      end
+    end
+  end
+end

data/lib/ruby_ai_gem_context/config_file.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module RubyAiGemContext
+  # Tracks generated context files in .ai_context/config.yml
+  #
+  # This helps us know:
+  # - Which files we generated vs user-created
+  # - When they were generated
+  # - Which model was used
+  class ConfigFile
+    CONFIG_FILENAME = "config.yml"
+
+    attr_reader :project_root
+
+    def initialize(project_root = Dir.pwd)
+      @project_root = project_root
+    end
+
+    def config_dir
+      File.join(project_root, RubyAiGemContext.configuration.config_dir)
+    end
+
+    def config_path
+      File.join(config_dir, CONFIG_FILENAME)
+    end
+
+    # Load existing config or return empty structure
+    def load
+      return default_config unless File.exist?(config_path)
+
+      YAML.safe_load(File.read(config_path), permitted_classes: [Time, Symbol]) || default_config
+    rescue StandardError
+      default_config
+    end
+
+    # Save config to file
+    def save(config)
+      FileUtils.mkdir_p(config_dir)
+      File.write(config_path, YAML.dump(config))
+    end
+
+    # Record that a file was generated
+    def record_generated(platform_key, model: nil)
+      config = load
+      config["generated"] ||= {}
+      config["generated"][platform_key.to_s] = {
+        "created_at" => Time.now.utc.iso8601,
+        "model" => model || RubyAiGemContext.configuration.model,
+        "path" => RubyAiGemContext.platform(platform_key).path
+      }
+      save(config)
+    end
+
+    # Check if we generated a specific platform's file
+    def generated?(platform_key)
+      config = load
+      config.dig("generated", platform_key.to_s).is_a?(Hash)
+    end
+
+    # Get info about a generated file
+    def generated_info(platform_key)
+      config = load
+      config.dig("generated", platform_key.to_s)
+    end
+
+    # List all platforms we've generated files for
+    def generated_platforms
+      config = load
+      (config["generated"] || {}).keys.map(&:to_sym)
+    end
+
+    # Record source folders used for generation
+    def record_source_folders(folders)
+      config = load
+      config["source_folders"] = folders
+      config["last_generated_at"] = Time.now.utc.iso8601
+      save(config)
+    end
+
+    # Get previously used source folders
+    def source_folders
+      config = load
+      config["source_folders"]
+    end
+
+    private
+
+    def default_config
+      {
+        "version" => RubyAiGemContext::VERSION,
+        "generated" => {},
+        "source_folders" => nil,
+        "last_generated_at" => nil
+      }
+    end
+  end
+end

data/lib/ruby_ai_gem_context/configuration.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RubyAiGemContext
+  class Configuration
+    # RubyLLM model configuration
+    attr_accessor :model, :temperature, :max_tokens
+
+    # File patterns to include/exclude when scanning
+    attr_accessor :include_patterns, :exclude_patterns
+
+    # Config directory for tracking generated files
+    attr_accessor :config_dir
+
+    def initialize
+      # Default to Claude Sonnet - good balance of quality and cost
+      @model = "claude-sonnet-4-20250514"
+      @temperature = 0.3
+      @max_tokens = 4000
+
+      # Default file patterns
+      @include_patterns = %w[
+        **/*.rb
+        **/*.rake
+        **/*.gemspec
+        **/Gemfile
+        **/Rakefile
+        README*
+        CHANGELOG*
+        LICENSE*
+      ]
+
+      @exclude_patterns = %w[
+        vendor/**/*
+        node_modules/**/*
+        tmp/**/*
+        log/**/*
+        .git/**/*
+        coverage/**/*
+        spec/**/*
+        test/**/*
+      ]
+
+      @config_dir = ".ai_context"
+    end
+
+    # Supported models with descriptions for documentation
+    def self.supported_models
+      {
+        # Anthropic Claude models
+        "claude-sonnet-4-20250514" => "Claude Sonnet 4 - Recommended balance of quality and cost",
+        "claude-opus-4-20250514" => "Claude Opus 4 - Highest quality, higher cost",
+        "claude-haiku-4-20250514" => "Claude Haiku 4 - Fast and cheap, lower quality",
+
+        # OpenAI models
+        "gpt-4o" => "GPT-4o - OpenAI's flagship model",
+        "gpt-4o-mini" => "GPT-4o Mini - Faster and cheaper",
+        "gpt-4-turbo" => "GPT-4 Turbo - Previous generation"
+      }
+    end
+  end
+end

data/lib/ruby_ai_gem_context/file_collector.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RubyAiGemContext
+  # Collects and reads files from the project for context generation
+  class FileCollector
+    attr_reader :root_path, :folders
+
+    # @param root_path [String] Project root directory
+    # @param folders [Array<String>, String, nil] Specific folders to scan, or nil for whole project
+    def initialize(root_path = Dir.pwd, folders: nil)
+      @root_path = root_path
+      @folders = normalize_folders(folders)
+    end
+
+    # Collect all relevant files based on configuration
+    # @return [Hash] Hash with file paths as keys and contents as values
+    def collect
+      files = {}
+
+      scan_paths.each do |scan_path|
+        collect_from_path(scan_path, files)
+      end
+
+      files
+    end
+
+    # Get a summary of what will be collected
+    # @return [Hash] Stats about files to be collected
+    def summary
+      files = collect
+      {
+        total_files: files.size,
+        total_size: files.values.sum(&:bytesize),
+        by_extension: count_by_extension(files)
+      }
+    end
+
+    private
+
+    def normalize_folders(folders)
+      case folders
+      when nil then nil
+      when String then [folders]
+      when Array then folders
+      else raise ArgumentError, "folders must be nil, String, or Array"
+      end
+    end
+
+    def scan_paths
+      if folders.nil?
+        [root_path]
+      else
+        folders.map { |f| File.join(root_path, f) }.select { |p| File.directory?(p) }
+      end
+    end
+
+    def collect_from_path(path, files)
+      include_patterns.each do |pattern|
+        Dir.glob(File.join(path, pattern)).each do |file_path|
+          next unless File.file?(file_path)
+          next if excluded?(file_path)
+          next if binary?(file_path)
+          next if too_large?(file_path)
+
+          relative_path = file_path.sub("#{root_path}/", "")
+          files[relative_path] = safe_read(file_path)
+        end
+      end
+    end
+
+    def include_patterns
+      RubyAiGemContext.configuration.include_patterns
+    end
+
+    def exclude_patterns
+      RubyAiGemContext.configuration.exclude_patterns
+    end
+
+    def excluded?(file_path)
+      relative = file_path.sub("#{root_path}/", "")
+      exclude_patterns.any? do |pattern|
+        File.fnmatch?(pattern, relative, File::FNM_PATHNAME)
+      end
+    end
+
+    def binary?(file_path)
+      # Simple binary check: look for null bytes in first 8KB
+      chunk = File.read(file_path, 8192) || ""
+      chunk.include?("\x00")
+    rescue StandardError
+      true
+    end
+
+    def too_large?(file_path, max_size: 100_000)
+      File.size(file_path) > max_size
+    rescue StandardError
+      true
+    end
+
+    def safe_read(file_path)
+      File.read(file_path, encoding: "UTF-8", invalid: :replace, undef: :replace)
+    rescue StandardError => e
+      "# Error reading file: #{e.message}"
+    end
+
+    def count_by_extension(files)
+      files.keys.group_by { |f| File.extname(f) }.transform_values(&:count)
+    end
+  end
+end