agent-context 0.0.2 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52c1839c403ab5a9b54f0ea7604d792fd284eb19c789a5f9d2afe356e6c7d992
-  data.tar.gz: 1f20c9f320200d4f2e70b838ba1a478ff69831924df81ce891115e3abfc6896f
+  metadata.gz: 5772240bc3bd7661f586cea5f942b21be8c6700dd01df4e287ccf88be7360885
+  data.tar.gz: 6e467af1cb56e030210770065eb566bdbcc0b4c17fcc171555096d69482fb081
 SHA512:
-  metadata.gz: d942db85db0f5a98a0feaf136cd43ca270f3ce29db40f1f63a4df899c9394194fba691b588caf6191d2b653b064cc16d18362abbf66786d9e6f3b42f6f30503f
-  data.tar.gz: feb0ba1a782cb034dcabfb8fe50767f4ff490b7ede56fada3b34a7124a659b8ce76aa6e14efca0a2ebf6ec456ebaa8fd2fb2b64ad2d73fe65b5c115a3c95507f
+  metadata.gz: ebd792d272ddb3619194bf3ddbd8858a13e81446e32a96c0fbd8a6314609e647ca0ffc7d73423abcd0b151d688b5284df36084b49e2d404763ba5e95bbe40a6e
+  data.tar.gz: 8025c2fa9fa4e25d7b6c87c520e34234f0b1ee2114ecb244d1ede213adfc406b49b4e084a4ac32e3f721b72498a890fb5355662684da2265dd30f8e6b78a3ddc

data/agent.md

@@ -0,0 +1,37 @@
+# Agent
+
+## Context
+
+This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`.
+
+### decode
+
+Code analysis for documentation generation.
+
+#### [Getting Started with Decode](.context/decode/getting-started.md)
+
+The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, docume...
+
+#### [Documentation Coverage](.context/decode/coverage.md)
+
+This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
+
+#### [Ruby Documentation](.context/decode/ruby-documentation.md)
+
+This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate A...
+
+### sus
+
+A fast and scalable test runner.
+
+#### [Using Sus Testing Framework](.context/sus/usage.md)
+
+Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
+
+#### [Mocking](.context/sus/mocking.md)
+
+There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace m...
+
+#### [Shared Test Behaviors and Fixtures](.context/sus/shared.md)
+
+Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.

data/bake/agent/context.rb

@@ -4,34 +4,35 @@
 # Copyright, 2025, by Shopify Inc.
 # Copyright, 2025, by Samuel Williams.
 
-require_relative "../../lib/agent/context/helper"
+require_relative "../../lib/agent/context/installer"
+require_relative "../../lib/agent/context/index"
 
 include Agent::Context
 
 def initialize(context)
 	super(context)
 	
-	@helper = Helper.new(root: context.root)
+	@installer = Installer.new(root: context.root)
 end
 
-attr :helper
+attr :installer
 
 # List all gems that have context available.
 # @parameter gem [String] Optional specific gem name to list context files for.
 def list(gem: nil)
 	if gem
-		files = @helper.list_context_files(gem)
+		files = @installer.list_context_files(gem)
 		if files
 			puts "Context files for gem '#{gem}':"
 			files.each do |file|
-				relative_path = Pathname.new(file).relative_path_from(Pathname.new(@helper.find_gem_with_context(gem)[:path]))
+				relative_path = Pathname.new(file).relative_path_from(Pathname.new(@installer.find_gem_with_context(gem)[:path]))
 				puts "  #{relative_path}"
 			end
 		else
 			puts "No context found for gem '#{gem}'"
 		end
 	else
-		gems = @helper.find_gems_with_context
+		gems = @installer.find_gems_with_context
 		if gems.any?
 			puts "Gems with context available:"
 			gems.each do |gem_info|
@@ -47,7 +48,7 @@ end
 # @parameter gem [String] The gem name.
 # @parameter file [String] The context file name.
 def show(gem:, file:)
-	content = @helper.show_context_file(gem, file)
+	content = @installer.show_context_file(gem, file)
 	if content
 		puts content
 	else
@@ -59,18 +60,29 @@ end
 # @parameter gem [String] Optional specific gem name to install context from.
 def install(gem: nil)
 	if gem
-		if @helper.install_gem_context(gem)
+		if @installer.install_gem_context(gem)
 			puts "Installed context from gem '#{gem}'"
 		else
 			puts "No context found for gem '#{gem}'"
 		end
 	else
-		installed = @helper.install_all_context
+		installed = @installer.install_all_context
 		if installed.any?
 			puts "Installed context from #{installed.length} gems:"
-			installed.each { |gem_name| puts "  #{gem_name}" }
+			installed.each {|gem_name| puts "  #{gem_name}"}
 		else
 			puts "No gems with context found"
 		end
 	end
-end 
+	
+	# Update agent.md after installing context
+	index = Agent::Context::Index.new(@installer.context_path)
+	index.update_agent_md
+end
+
+# Update or create AGENT.md in the project root with context section
+# This follows the AGENT.md specification for agentic coding tools
+def agent_md(path = "agent.md")
+	index = Agent::Context::Index.new(@helper.context_path)
+	index.update_agent_md(path)
+end

data/context/usage.md

@@ -0,0 +1,173 @@
+# Usage Guide
+
+## What is agent-context?
+
+`agent-context` is a tool that helps you discover and install contextual information from Ruby gems for AI agents. Gems can provide additional documentation, examples, and guidance in a `context/` directory.
+
+## Quick Commands
+
+```bash
+# See what context is available
+bake agent:context:list
+
+# Install all available context
+bake agent:context:install
+
+# Install context from a specific gem
+bake agent:context:install --gem async
+
+# See what context files a gem provides
+bake agent:context:list --gem async
+
+# View a specific context file
+bake agent:context:show --gem async --file thread-safety
+```
+
+## Understanding context/ vs .context/
+
+**Important distinction:**
+- **`context/`** (no dot) = Directory in gems that contains context files to share.
+- **`.context/`** (with dot) = Directory in your project where context gets installed.
+
+### What happens when you install context?
+
+When you run `bake agent:context:install`, the tool:
+
+1. Scans all installed gems for `context/` directories (in the gem's root).
+2. Creates a `.context/` directory in your current project.
+3. Copies context files organized by gem name.
+
+For example:
+```
+your-project/
+├── .context/           # ← Installed context (with dot)
+│   ├── async/          # ← From the 'async' gem's context/ directory
+│   │   ├── thread-safety.md
+│   │   └── performance.md
+│   └── rack/           # ← From the 'rack' gem's context/ directory
+│       └── middleware.md
+├── lib/
+└── Gemfile
+```
+
+Meanwhile, in the gems themselves:
+```
+async-gem/
+├── context/            # ← Source context (no dot)
+│   ├── thread-safety.md
+│   └── performance.md
+├── lib/
+└── async.gemspec
+```
+
+## Using Context (For Gem Users)
+
+### Why use this?
+
+- **Discover hidden documentation** that gems provide.
+- **Get practical examples** and guidance.
+- **Understand best practices** from gem authors.
+- **Access migration guides** and troubleshooting tips.
+
+### Key Points for Users
+
+- Run `bake agent:context:install` to copy context to `.context/` (with dot).
+- The `.context/` directory is where installed context lives in your project.
+- Don't edit files in `.context/` - they get completely replaced when you reinstall.
+
+## Providing Context (For Gem Authors)
+
+### How to provide context in your gem
+
+#### 1. Create a `context/` directory
+
+In your gem's root directory, create a `context/` folder (no dot):
+
+```
+your-gem/
+├── context/            # ← Source context (no dot) - this is what you create
+│   ├── getting-started.md
+│   ├── configuration.md
+│   └── troubleshooting.md
+├── lib/
+└── your-gem.gemspec
+```
+
+**Important:** This is different from `.context/` (with dot) which is where context gets installed in user projects.
+
+#### 2. Add context files
+
+Create files with helpful information for users of your gem. Common types include:
+
+- **getting-started.md** - Quick start guide for using your gem.
+- **configuration.md** - Configuration options and examples.
+- **troubleshooting.md** - Common issues and solutions.
+- **migration.md** - Migration guides between versions.
+- **performance.md** - Performance tips and best practices.
+- **security.md** - Security considerations.
+
+**Focus on the agent experience:** These files should help AI agents understand how to use your gem effectively, not document your gem's internal APIs.
+
+#### 3. Document your context
+
+Add a section to your gem's README:
+
+```markdown
+## Context
+
+This gem provides additional context files that can be installed using `bake agent:context:install`.
+
+Available context files:
+- `getting-started.md` - Quick start guide.
+- `configuration.md` - Configuration options.
+- `troubleshooting.md` - Common issues and solutions.
+```
+
+#### 4. File format and content guidelines
+
+Context files can be in any format, but `.md` is commonly used for documentation. The content should be:
+
+- **Practical** - Include real examples and working code.
+- **Focused** - One topic per file.
+- **Clear** - Easy to understand and follow.
+- **Actionable** - Provide specific guidance and next steps.
+- **Agent-focused** - Help AI agents understand how to use your gem effectively.
+
+### Key Points for Gem Authors
+
+- Create a `context/` directory (no dot) in your gem's root.
+- Put helpful guides for users of your gem there.
+- Focus on practical usage, not API documentation.
+
+## Example Context Files
+
+For examples of well-structured context files, see the existing files in this directory:
+- `usage.md` - Shows how to use the tool (this file).
+- `examples.md` - Demonstrates practical usage scenarios.
+
+## Key Differences from API Documentation
+
+Context files are NOT the same as API documentation:
+
+- **Context files**: Help agents accomplish tasks ("How do I configure authentication?").
+- **API documentation**: Document methods and classes ("Method `authenticate` returns Boolean").
+
+Context files should answer questions like:
+- "How do I get started?".
+- "How do I configure this for production?".
+- "What do I do when X goes wrong?".
+- "How do I migrate from version Y to Z?".
+
+## Testing Your Context
+
+Before publishing, test your context files:
+
+1. Have an AI agent try to follow your getting-started guide.
+2. Check that all code examples actually work.
+3. Ensure the files are focused and don't try to cover too much.
+4. Verify that they complement rather than duplicate your main documentation.
+
+## Summary
+
+- **`context/`** = source (in gems).
+- **`.context/`** = destination (in your project).

data/lib/agent/context/index.rb

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025, by Shopify Inc.
+
+require_relative "version"
+require "fileutils"
+require "yaml"
+
+# @namespace
+module Agent
+	# @namespace
+	module Context
+		# Represents an index for managing and generating agent.md files from context files.
+		# 
+		# This class provides functionality to update or create AGENT.md files following
+		# the AGENT.md specification for agentic coding tools. It can parse existing
+		# agent.md files, update the context section, and generate new files when needed.
+		class Index
+			# Initialize a new index instance.
+			# @parameter context_path [String] The path to the context directory (default: ".context").
+			def initialize(context_path = ".context")
+				@context_path = context_path
+			end
+			
+			attr :context_path
+			
+			# Update or create an AGENT.md file in the project root with context section
+			# This follows the AGENT.md specification for agentic coding tools
+			def update_agent_md(agent_md_path = "agent.md")
+				context_content = generate_context_section
+				
+				if File.exist?(agent_md_path)
+					update_existing_agent_md(agent_md_path, context_content)
+				else
+					create_new_agent_md(agent_md_path, context_content)
+				end
+				
+				Console.debug("Updated agent.md: #{agent_md_path}")
+			end
+			
+			# Generate just the context section content (without top-level headers)
+			def generate_context_section
+				sections = []
+				
+				sections << "This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`."
+				sections << ""
+				
+				gem_contexts = collect_gem_contexts
+				
+				if gem_contexts.empty?
+					sections << "No context files found. Run `bake agent:context:install` to install context from gems."
+					sections << ""
+				else
+					gem_contexts.each do |gem_name, files|
+						sections << "### #{gem_name}"
+						sections << ""
+						
+						# Get gem directory and load index
+						gem_directory = File.join(@context_path, gem_name)
+						index = load_gem_index(gem_name, gem_directory)
+						
+						# Add gem description from index
+						if index["description"]
+							sections << index["description"]
+							sections << ""
+						end
+						
+						# Use files from index if available, otherwise fall back to parsing
+						if index["files"] && !index["files"].empty?
+							index["files"].each do |file_info|
+								sections << "#### [#{file_info['title']}](.context/#{gem_name}/#{file_info['path']})"
+								sections << ""
+								sections << file_info["description"] if file_info["description"] && !file_info["description"].empty?
+								sections << ""
+							end
+						else
+							# Fallback to parsing files directly
+							files.each do |file_path|
+								if File.exist?(file_path)
+									title, description = extract_content(file_path)
+									relative_path = file_path.sub("#{@context_path}/", "")
+									sections << "#### [#{title}](.context/#{relative_path})"
+									sections << ""
+									sections << description if description && !description.empty?
+									sections << ""
+								end
+							end
+						end
+					end
+				end
+				
+				sections.join("\n")
+			end
+			
+			private
+			
+			def update_existing_agent_md(agent_md_path, context_content)
+				content = File.read(agent_md_path)
+				
+				# Find the # Agent heading
+				agent_heading_line = find_agent_heading_line(content)
+				
+				if agent_heading_line
+					# Find or create the ## Context section
+					context_section = find_context_section_under_agent(content, agent_heading_line)
+					
+					if context_section
+						# Replace existing context section
+						updated_content = replace_context_section(content, context_section, context_content)
+					else
+						# Insert new context section after agent heading
+						updated_content = insert_context_section_after_agent(content, agent_heading_line, context_content)
+					end
+				else
+					# No # Agent heading found, prepend it with context
+					updated_content = prepend_agent_with_context(content, context_content)
+				end
+				
+				# Write the updated content back to file
+				File.write(agent_md_path, updated_content)
+			end
+			
+			def create_new_agent_md(agent_md_path, context_content)
+				content = [
+					"# Agent",
+					"",
+					"## Context",
+					"",
+					context_content,
+				].join("\n")
+				File.write(agent_md_path, content)
+			end
+			
+			def find_agent_heading_line(content)
+				lines = content.lines
+				lines.each_with_index do |line, index|
+					if line.strip.start_with?("# ") && line.strip.downcase == "# agent"
+						return index
+					end
+				end
+				nil
+			end
+			
+			def find_context_section_under_agent(content, agent_line_index)
+				lines = content.lines
+				
+				# Look for ## Context after the agent heading
+				(agent_line_index + 1).upto(lines.length - 1) do |index|
+					line = lines[index]
+					if line.strip == "## Context"
+						return index
+					elsif line.strip.start_with?("# ") && line.strip != "# Agent"
+						# We've hit another top-level heading, stop searching
+						break
+					end
+				end
+				
+				nil
+			end
+			
+			def replace_context_section(content, context_line_index, context_content)
+				lines = content.lines
+				
+				# Find the end of the context section
+				end_index = find_section_end(lines, context_line_index, 2)
+				
+				# Build the new content
+				new_lines = []
+				new_lines.concat(lines[0...context_line_index])
+				new_lines << "## Context\n"
+				new_lines << "\n"
+				new_lines.concat(context_content.lines)
+				new_lines.concat(lines[end_index..-1])
+				
+				new_lines.join
+			end
+			
+			def insert_context_section_after_agent(content, agent_line_index, context_content)
+				lines = content.lines
+				
+				# Build the new content
+				new_lines = []
+				new_lines.concat(lines[0..agent_line_index])
+				new_lines << "\n"
+				new_lines << "## Context\n"
+				new_lines << "\n"
+				new_lines.concat(context_content.lines)
+				new_lines.concat(lines[agent_line_index + 1..-1])
+				
+				new_lines.join
+			end
+			
+			def prepend_agent_with_context(content, context_content)
+				agent_context = [
+					"# Agent",
+					"",
+					"## Context",
+					"",
+					context_content,
+					""
+				].join("\n")
+				agent_context + content
+			end
+			
+			def find_section_end(lines, start_index, heading_level)
+				index = start_index + 1
+				
+				while index < lines.length
+					line = lines[index]
+					
+					if line.strip.start_with?("#")
+						level = line.strip.match(/^(#+)/)[1].length
+						if level <= heading_level
+							break
+						end
+					end
+					
+					index += 1
+				end
+				
+				index
+			end
+			
+			def collect_gem_contexts
+				gem_contexts = {}
+				
+				return gem_contexts unless Dir.exist?(@context_path)
+				
+				Dir.glob(File.join(@context_path, "*")).each do |gem_directory|
+					next unless File.directory?(gem_directory)
+					gem_name = File.basename(gem_directory)
+					
+					markdown_files = Dir.glob(File.join(gem_directory, "**", "*.md")).sort
+					gem_contexts[gem_name] = markdown_files if markdown_files.any?
+				end
+				
+				gem_contexts
+			end
+			
+			# Load a gem's index file
+			def load_gem_index(gem_name, gem_directory)
+				index_path = File.join(gem_directory, "index.yaml")
+				
+				if File.exist?(index_path)
+					YAML.load_file(index_path)
+				else
+					# Return a fallback index if no index.yaml exists
+					{
+						"description" => "Context files for #{gem_name}",
+						"files" => []
+					}
+				end
+			rescue => error
+				Console.debug("Error loading index for #{gem_name}: #{error.message}")
+				# Return a fallback index
+				{
+					"description" => "Context files for #{gem_name}",
+					"files" => []
+				}
+			end
+			
+			def extract_content(file_path)
+				content = File.read(file_path)
+				lines = content.lines.map(&:strip)
+				
+				title = extract_title(lines)
+				description = extract_description(lines)
+				
+				[title, description]
+			end
+			
+			def extract_title(lines)
+				# Look for the first markdown header
+				header_line = lines.find {|line| line.start_with?("#")}
+				if header_line
+					# Remove markdown header syntax and clean up
+					header_line.sub(/^#+\s*/, "").strip
+				else
+					# If no header found, use a default
+					"Documentation"
+				end
+			end
+			
+			def extract_description(lines)
+				# Skip empty lines and headers to find the first paragraph
+				content_start = false
+				description_lines = []
+				
+				lines.each do |line|
+					# Skip headers
+					next if line.start_with?("#")
+					
+					# Skip empty lines until we find content
+					if !content_start && line.empty?
+						next
+					end
+					
+					# Mark that we've found content
+					content_start = true
+					
+					# If we hit an empty line after finding content, we've reached the end of the first paragraph
+					if line.empty?
+						break
+					end
+					
+					description_lines << line
+				end
+				
+				# Join the lines and truncate if too long
+				description = description_lines.join(" ").strip
+				if description.length > 197
+					description = description[0..196] + "..."
+				end
+				
+				description
+			end
+		end
+	end
+end