agent_settings 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15e2352fd94c8dbf7fe85836e0c9b48a0dd8cc09e631674949ef301a28083dbc
+  data.tar.gz: 8f618aba7e01370d35ec3d5a3cb66c4f7f637788487cb656dea2449c3334b96a
+SHA512:
+  metadata.gz: 14c65ca62831a314b49f92157cbe229c51da19d333274f16545a3b459450d7e789a4d21b7a9fd2a9a010d6029f8a27de08920a665bb16007d7b0aaad2641d645
+  data.tar.gz: a778b94ef5bcd36571c8e91e8cf7c18cfe2fe7272a4f9bd573624806a94c22d246cd2ced383304d3ca3d41f9657d8d2b724dc0ce539ec575c5c34d6cebd27cc6

data/AGENTS.md

@@ -0,0 +1,244 @@
+# Agent Settings - Ruby Gem
+
+Ruby gem that provides a clean interface to discover config locations for Claude Code, OpenCode, and Codex — including whether each path exists and which path is currently effective based on precedence and overrides.
+
+Read @doc/ruby.md before writing any Ruby code.
+
+## Build / Lint / Test Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake test
+
+# Run a single test file
+bundle exec ruby -Ilib:test test/agent_settings/resolver_test.rb
+
+# Run a single test by name
+bundle exec ruby -Ilib:test test/agent_settings/resolver_test.rb --name test_global_resolution
+
+# Run tests with verbose output
+bundle exec rake test TESTOPTS="--verbose"
+
+# Lint with RuboCop (if configured)
+bundle exec rubocop
+
+# Lint and auto-correct
+bundle exec rubocop -a
+
+# Build the gem
+bundle exec rake build
+
+# Install the gem locally
+bundle exec rake install
+
+# Run the console for experimentation
+bundle exec console
+```
+
+## Project Structure
+
+```
+lib/agent_settings.rb           # Entry point with Zeitwerk loader
+lib/agent_settings/version.rb   # Version constant
+lib/agent_settings/location.rb  # Location value object
+lib/agent_settings/env_override.rb  # EnvOverride value object
+lib/agent_settings/agent_config_path.rb # AgentConfigPath value object
+lib/agent_settings/location_discovery.rb  # Core discovery logic
+lib/agent_settings/registry.rb  # Agent-to-adapter mapping
+lib/agent_settings/adapters/    # Per-agent adapters
+  claude.rb
+  opencode.rb
+  codex.rb
+test/                           # Minitest tests
+```
+
+## Public API
+
+```ruby
+AgentSettings.global(agent, env: ENV, dir: Dir.pwd, trusted: true)
+AgentSettings.project(agent, dir:, env: ENV, trusted: true)
+AgentSettings.resolve(agent, dir:, env: ENV, trusted: true)
+AgentSettings.all(dir:, env: ENV, trusted: true)
+```
+
+Supported agents: `:claude`, `:opencode`, `:codex`
+
+## Code Style Guidelines
+
+### Ruby 3.x Features
+
+Use modern Ruby features throughout:
+
+```ruby
+# Data objects for immutable value objects
+Location = Data.define(:agent, :scope, :path, :exists, :active) do
+  def exists? = exists
+  def active? = active
+end
+
+# Pattern matching
+case agent
+in :claude then ClaudeAdapter.new
+in :opencode then OpencodeAdapter.new
+in :codex then CodexAdapter.new
+end
+
+# Endless methods for simple one-liners
+def global = layers.find { |l| l.scope == :global }
+def custom_config? = variables.any?(&:active?)
+
+# Keyword arguments throughout
+def resolve(agent, dir:, env: ENV, trusted: true)
+
+# Safe navigation operator
+path = env["CLAUDE_CONFIG_DIR"]&.then { |dir| File.join(dir, "settings.json") }
+```
+
+### Naming Conventions
+
+- **Boolean methods** end with `?`: `exists?`, `active?`, `custom_config?`
+- **Positive names**: use `active` not `not_deleted`
+- **Role-based naming**: name variables after their role, not type
+- **No pattern names in classes**: avoid `ResolverFactory`, `LocationDecorator`
+- **Domain language**: reflect the business domain in names
+
+### Method Design
+
+- **Composed methods**: each method does one thing at one abstraction level
+- **Intention-revealing selectors**: name after what, not how
+- **Keyword arguments**: always prefer over positional arguments
+- **Tiny public surface**: expose only what callers need
+
+### Class Design
+
+- **Single responsibility**: one sentence description, no "and/or"
+- **Cohesion**: everything in a class shares one idea
+- **Composition over inheritance**: prefer composition
+- **Law of Demeter**: only talk to immediate neighbors
+- **Tell, don't ask**: send messages, avoid train wrecks
+
+### Value Objects
+
+Use `Data.define` for immutable value objects:
+
+```ruby
+module AgentSettings
+  Location = Data.define(:agent, :scope, :source, :path, :exists, :active, :note) do
+    def exists? = exists
+    def active? = active
+  end
+
+  EnvOverride = Data.define(:agent, :name, :value, :path, :exists, :active, :note) do
+    def exists? = exists
+    def active? = active
+  end
+
+  AgentConfigPath = Data.define(:agent, :effective, :global, :project, :layers, :env_overrides, :warnings) do
+    def custom_config? = env_overrides.any?(&:active?)
+  end
+end
+```
+
+### Error Handling
+
+Use custom error classes for domain errors:
+
+```ruby
+module AgentSettings
+  class Error < StandardError; end
+  class UnknownAgentError < Error; end
+  class InvalidConfigError < Error; end
+end
+
+# Raise with clear messages
+raise UnknownAgentError, "Unknown agent: #{agent}. Supported: #{Registry::AGENTS.join(', ')}"
+```
+
+### Adapter Protocol
+
+Each adapter must implement:
+
+```ruby
+class SomeAdapter
+  # Returns array of Location objects, ordered by precedence (highest first)
+  def layers(dir:, env:, trusted:) = [...]
+
+  # Returns array of EnvOverride objects for env overrides
+  def env_overrides(dir:, env:, trusted:) = [...]
+
+  # Returns array of warning strings
+  def warnings(dir:, env:, trusted:) = []
+end
+```
+
+## Agent Config Rules
+
+### Claude Code
+- Global: `~/.claude/settings.json`
+- Project: `.claude/settings.json`
+- Local override: `.claude/settings.local.json`
+- Managed: `/Library/Application Support/ClaudeCode/managed-settings.json` (macOS)
+- Env override: `CLAUDE_CONFIG_DIR`
+- Precedence: managed > CLI > local project > project > user
+
+### OpenCode
+- Global: `~/.config/opencode/opencode.json`
+- Project: `opencode.json` (discovered upward from dir)
+- Env overrides: `OPENCODE_CONFIG`, `OPENCODE_CONFIG_DIR`, `OPENCODE_CONFIG_CONTENT`
+
+### Codex
+- User: `~/.codex/config.toml`
+- Project: `.codex/config.toml` (trusted projects only)
+- System: `/etc/codex/config.toml`
+- Env override: `CODEX_HOME`
+- Trust caveat: project config ignored for untrusted projects
+
+## Testing Strategy
+
+- **Test public interfaces only**: test what callers see
+- **Test private methods indirectly**: through public API
+- **Cover these scenarios**:
+  - Global/project resolution per agent
+  - Override variable detection and activation
+  - Effective path precedence
+  - `exists?` true/false for paths
+  - Trusted vs untrusted Codex behavior
+
+```ruby
+class LocationDiscoveryTest < Minitest::Test
+  def test_global_resolution_for_claude
+    result = AgentSettings.global(:claude)
+    assert_equal :global, result.scope
+    assert_predicate result, :exists?
+  end
+
+  def test_project_config_ignored_for_untrusted_codex
+    result = AgentSettings.resolve(:codex, dir: "/untrusted/repo", trusted: false)
+    assert_nil result.project
+  end
+end
+```
+
+## Dependencies
+
+- **Runtime**: `zeitwerk` (autoloading)
+- **Development**: `minitest`, `rake`, `rubocop` (optional)
+
+Use Zeitwerk at entry point:
+
+```ruby
+# lib/agent_settings.rb
+require "zeitwerk"
+Zeitwerk::Loader.for_gem.setup
+```
+
+## Design Principles
+
+1. **Messaging over objects**: focus on messages passing between objects
+2. **Behavior over data**: depend on what objects do, not what they are
+3. **Duck typing**: type is defined by behavior, not class
+4. **Dependency injection**: pass collaborators, don't hard-code class names
+5. **Late binding**: allow objects to hide internal state-process

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 - 2025-02-24
+
+Initial release.
+
+- Discover config locations for Claude Code, OpenCode, and Codex
+- Global and project config resolution
+- Environment variable override detection
+- Precedence-based active config determination
+- Trusted/untrusted project handling for Codex

data/CLAUDE.md

@@ -0,0 +1,95 @@
+# agent_settings
+
+Ruby gem that provides a clean interface to discover config locations for Claude Code, OpenCode, and Codex — including whether each path exists and which path is currently effective based on precedence and overrides.
+
+Read @doc/ruby.md before writing any Ruby code.
+
+## Public API
+
+```ruby
+AgentSettings.global(agent, env: ENV, dir: Dir.pwd, trusted: true)
+AgentSettings.project(agent, dir:, env: ENV, trusted: true)
+AgentSettings.resolve(agent, dir:, env: ENV, trusted: true)
+AgentSettings.all(dir:, env: ENV, trusted: true)
+```
+
+## File Layout
+
+```
+lib/agent_settings.rb
+lib/agent_settings/version.rb
+lib/agent_settings/location.rb
+lib/agent_settings/variable.rb
+lib/agent_settings/resolution.rb
+lib/agent_settings/resolver.rb
+lib/agent_settings/registry.rb
+lib/agent_settings/adapters/claude.rb
+lib/agent_settings/adapters/opencode.rb
+lib/agent_settings/adapters/codex.rb
+test/
+```
+
+## Core Value Objects
+
+- `Location` — fields: `agent, scope, source, path, exists, active, note`; methods: `exists?`, `active?`
+- `Variable` — fields: `agent, name, value, path, exists, active, note`; methods: `exists?`, `active?`
+- `Resolution` — fields: `agent, effective, global, project, layers, variables, warnings`; method: `custom_config?`
+
+## Core Classes
+
+- `Resolver` — builds final `Resolution`, picks effective location from precedence layers
+- `Registry` — maps agent symbols to adapters
+- `Adapters::Claude`, `Adapters::Opencode`, `Adapters::Codex` — each exposes `layers(dir:, env:, trusted:)`, `variables(dir:, env:, trusted:)`, `warnings(dir:, env:, trusted:)`
+
+## Agent Config Rules
+
+### Claude Code
+- Global: `~/.claude/settings.json`
+- Project: `.claude/settings.json`
+- Local project override: `.claude/settings.local.json`
+- Managed/system: `/Library/Application Support/ClaudeCode/managed-settings.json` (macOS), `/etc/claude-code/managed-settings.json` (Linux)
+- Env override: `CLAUDE_CONFIG_DIR`
+- Precedence (high→low): managed > CLI > local project > project > user
+
+### OpenCode
+- Global: `~/.config/opencode/opencode.json`
+- Project: `opencode.json` (discovered from dir toward project root)
+- Env overrides: `OPENCODE_CONFIG`, `OPENCODE_CONFIG_DIR`, `OPENCODE_CONFIG_CONTENT`
+
+### Codex
+- User: `~/.codex/config.toml`
+- Project: `.codex/config.toml` (trusted projects only)
+- System: `/etc/codex/config.toml`
+- Env base override: `CODEX_HOME`
+
+## Ruby Conventions
+
+Use Ruby 3.x features:
+- `Data` objects for immutable value objects (`Location`, `Variable`, `Resolution`)
+- Pattern matching (`case/in`, `=>`)
+- Endless methods for simple one-liners
+- Keyword arguments throughout
+- Safe navigation operator (`&.`)
+
+Design principles (Sandi Metz / OOD):
+- Tiny public surface — expose only what callers need
+- Intention-revealing names — reflect domain, not implementation
+- Single responsibility — one sentence description per class, no "and/or"
+- Tell, don't ask — send messages, avoid train wrecks
+- Depend on behavior (duck types), not class names
+- Composed methods — each method does one thing at one level of abstraction
+
+Naming rules:
+- Boolean methods end with `?` (e.g., `exists?`, `active?`, `custom_config?`)
+- Positive names (`active` not `not_deleted`)
+- Variables named for their role, not their type
+- No design pattern names in class names
+
+## Testing (Minitest)
+
+- Test public interfaces only; test private methods indirectly
+- Cover: global/project resolution per agent, override variable detection, effective path precedence, `exists?` true/false, trusted vs untrusted Codex behavior
+
+## Dependencies
+
+- `zeitwerk` runtime dependency; use `Zeitwerk::Loader.for_gem` in entrypoint

data/README.md

@@ -0,0 +1,177 @@
+# agent_settings
+
+Discover config locations for Claude Code, OpenCode, and Codex
+
+If you are an LLM/AI Agent read [./llm.md](llm.md) in this repository. 
+
+## Installation
+
+Add this line to your application's **Gemfile**:
+
+```ruby
+gem "agent_settings"
+```
+
+And run:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install agent_settings
+```
+
+## Quick Start
+
+Get the effective config for an agent:
+
+```ruby
+require "agent_settings"
+
+result = AgentSettings.resolve(:claude, dir: Dir.pwd)
+puts result.effective.path
+```
+
+## Usage
+
+### Get Global Config
+
+Retrieve the global config location for an agent:
+
+```ruby
+location = AgentSettings.global(:claude)
+location.path    # => "/Users/me/.claude/settings.json"
+location.exists? # => true
+```
+
+### Get Project Config
+
+Retrieve the project-level config location:
+
+```ruby
+location = AgentSettings.project(:codex, dir: "/work/my_app")
+location.path    # => "/work/my_app/.codex/config.toml"
+location.exists? # => false
+```
+
+### Resolve Effective Config
+
+Get the active config with full details:
+
+```ruby
+result = AgentSettings.resolve(:opencode, dir: "/work/my_app")
+
+result.effective.path   # the active config path
+result.global           # global location
+result.project          # project location
+result.layers           # all config layers by precedence
+result.env_overrides    # environment variable overrides
+result.warnings         # any warnings
+result.custom_config?   # true if env override is active
+```
+
+### Resolve All Agents
+
+Get config paths for all supported agents:
+
+```ruby
+results = AgentSettings.all(dir: "/work/my_app")
+
+results.each do |agent, config_path|
+  puts "#{agent}: #{config_path.effective.path}"
+end
+```
+
+### Detect Environment Overrides
+
+Check if environment variables override config paths:
+
+```ruby
+result = AgentSettings.resolve(:opencode, dir: Dir.pwd, env: ENV)
+
+result.env_overrides.each do |override|
+  puts "#{override.name}=#{override.value}"
+  puts "  active: #{override.active?}"
+end
+```
+
+### Handle Untrusted Projects
+
+Codex ignores project config for untrusted projects:
+
+```ruby
+# trusted (default) - includes project config
+result = AgentSettings.resolve(:codex, dir: dir, trusted: true)
+
+# untrusted - excludes project config
+result = AgentSettings.resolve(:codex, dir: dir, trusted: false)
+result.warnings # => ["Project config ignored for untrusted project"]
+```
+
+## Supported Agents
+
+| Agent | Global Config | Project Config |
+|-------|---------------|----------------|
+| Claude | `~/.claude/settings.json` | `.claude/settings.json` |
+| OpenCode | `~/.config/opencode/opencode.json` | `opencode.json` |
+| Codex | `~/.codex/config.toml` | `.codex/config.toml` |
+
+## Options
+
+All methods accept these keyword arguments:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `agent` | Symbol | required | `:claude`, `:opencode`, or `:codex` |
+| `dir` | String | `Dir.pwd` | Project directory path |
+| `env` | Hash | `ENV` | Environment variables hash |
+| `trusted` | Boolean | `true` | Trust project for Codex |
+
+## Value Objects
+
+### Location
+
+Represents a config file location:
+
+```ruby
+location.agent    # => :claude
+location.scope    # => :global or :project
+location.path     # => "/Users/me/.claude/settings.json"
+location.exists?  # => true
+location.active?  # => true
+```
+
+### EnvOverride
+
+Represents an environment variable override:
+
+```ruby
+override.name     # => "CLAUDE_CONFIG_DIR"
+override.value    # => "/custom/path"
+override.path     # => "/custom/path/settings.json"
+override.active?  # => true
+```
+
+### AgentConfigPath
+
+The result of resolving an agent's config:
+
+```ruby
+config.effective      # => Location (highest precedence)
+config.global         # => Location or nil
+config.project        # => Location or nil
+config.layers         # => Array of Location
+config.env_overrides  # => Array of EnvOverride
+config.warnings       # => Array of String
+config.custom_config? # => true if env override active
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+The gem is available as open source under the terms of the Apache 2.0 License.

data/lib/agent_settings/adapters/claude.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module AgentSettings
+  module Adapters
+    # Adapter for Claude Code agent configuration.
+    #
+    # Claude Code stores configuration in JSON files at various locations:
+    #
+    # - Global: ~/.claude/settings.json (user-level config)
+    # - Project: .claude/settings.json (project-level config)
+    # - Local: .claude/settings.local.json (local overrides, not committed)
+    # - Managed: /Library/Application Support/ClaudeCode/managed-settings.json (macOS system-level)
+    #
+    # Precedence (highest to lowest): managed > local > project > global
+    #
+    # Environment variable CLAUDE_CONFIG_DIR can override the global config location.
+    #
+    # @example
+    #   adapter = Claude.new
+    #   layers = adapter.layers(dir: "/work/my_app", env: ENV, trusted: true)
+    #   env_overrides = adapter.env_overrides(dir: "/work/my_app", env: ENV, trusted: true)
+    class Claude
+      # Get all config layers for Claude Code.
+      #
+      # Returns an array of Location objects representing all possible
+      # config file locations, ordered by precedence (highest first).
+      # Only one layer will be marked as active (the first existing one).
+      #
+      # @param dir [String] project directory path
+      # @param env [Hash] environment variables hash
+      # @param trusted [Boolean] whether the project is trusted (unused for Claude)
+      # @return [Array<Location>] config layers in precedence order
+      def layers(dir:, env:, trusted:) # rubocop:disable Lint/UnusedMethodArgument
+        build_layers(dir, env)
+      end
+
+      # Get environment variable overrides for Claude Code.
+      #
+      # Checks for CLAUDE_CONFIG_DIR environment variable and returns
+      # an EnvOverride if it's set. The override is active if the
+      # resulting settings.json file exists.
+      #
+      # @param dir [String] project directory path (unused)
+      # @param env [Hash] environment variables hash
+      # @param trusted [Boolean] whether the project is trusted (unused)
+      # @return [Array<EnvOverride>] detected environment overrides
+      def env_overrides(dir:, env:, trusted:) # rubocop:disable Lint/UnusedMethodArgument
+        build_env_overrides(env)
+      end
+
+      # Get warnings for Claude Code configuration.
+      #
+      # Claude Code doesn't produce any warnings currently.
+      #
+      # @return [Array<String>] empty array
+      def warnings(*) = []
+
+      private
+
+      # Build the list of config layers.
+      #
+      # Creates Location objects for each possible config location,
+      # ordered by precedence. The managed config (system-level) has
+      # highest precedence, followed by local project overrides,
+      # then project config, then user global config.
+      #
+      # @param dir [String] project directory path
+      # @param env [Hash] environment variables hash
+      # @return [Array<Location>] config layers with active flag set
+      def build_layers(dir, env) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength -- builds all layer types in one coherent method
+        home = Dir.home
+        config_dir = env["CLAUDE_CONFIG_DIR"]
+
+        managed_path = managed_config_path
+        global_path = config_dir ? File.join(config_dir, "settings.json") : File.join(home, ".claude", "settings.json")
+        project_path = File.join(dir, ".claude", "settings.json")
+        local_path = File.join(dir, ".claude", "settings.local.json")
+
+        layers = []
+
+        layers << build_layer(:managed, "system", managed_path) if managed_path
+        layers << build_layer(:global, "user", global_path)
+        layers << build_layer(:project, "local", local_path)
+        layers << build_layer(:project, "file", project_path)
+
+        mark_active(layers)
+      end
+
+      # Build environment variable overrides.
+      #
+      # Checks if CLAUDE_CONFIG_DIR is set and creates an EnvOverride
+      # for it. The override's path is the settings.json file within
+      # the specified directory.
+      #
+      # @param env [Hash] environment variables hash
+      # @return [Array<EnvOverride>] detected overrides
+      def build_env_overrides(env) # rubocop:disable Metrics/MethodLength -- constructs EnvOverride with all required attributes
+        overrides = []
+        value = env["CLAUDE_CONFIG_DIR"]
+
+        if value
+          path = File.join(value, "settings.json")
+          overrides << EnvOverride.new(
+            agent: :claude,
+            name: "CLAUDE_CONFIG_DIR",
+            value: value,
+            path: path,
+            exists: File.exist?(path),
+            active: File.exist?(path),
+            note: "Config directory override"
+          )
+        end
+
+        overrides
+      end
+
+      # Get the managed (system-level) config path.
+      #
+      # Managed config is typically set by system administrators and
+      # has the highest precedence. Location varies by OS:
+      # - macOS: /Library/Application Support/ClaudeCode/managed-settings.json
+      # - Linux: /etc/claude-code/managed-settings.json
+      #
+      # @return [String, nil] the managed config path if it exists, nil otherwise
+      def managed_config_path
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/
+          path = "/Library/Application Support/ClaudeCode/managed-settings.json"
+          File.exist?(path) ? path : nil
+        when /linux/
+          path = "/etc/claude-code/managed-settings.json"
+          File.exist?(path) ? path : nil
+        end
+      end
+
+      # Build a Location object for a config layer.
+      #
+      # @param scope [Symbol] the scope (:global, :project, :managed)
+      # @param source [String] where this config comes from
+      # @param path [String] the file path
+      # @return [Location] a Location object (not yet marked active)
+      def build_layer(scope, source, path)
+        Location.new(
+          agent: :claude,
+          scope: scope,
+          source: source,
+          path: path,
+          exists: File.exist?(path),
+          active: false,
+          note: nil
+        )
+      end
+
+      # Mark the first existing layer as active.
+      #
+      # Iterates through layers and marks the first one that exists
+      # as active. This implements the precedence rule where the
+      # first existing config file wins.
+      #
+      # @param layers [Array<Location>] config layers
+      # @return [Array<Location>] layers with active flag set
+      def mark_active(layers)
+        found = layers.find(&:exists?)
+        layers.map do |layer|
+          layer.with(active: layer == found)
+        end
+      end
+    end
+  end
+end