agent_settings 0.1.0

data/lib/agent_settings/adapters/codex.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module AgentSettings
+  module Adapters
+    # Adapter for Codex agent configuration.
+    #
+    # Codex stores configuration in TOML files:
+    #
+    # - Global: ~/.codex/config.toml (user-level config)
+    # - Project: .codex/config.toml (project-level config, trusted only)
+    # - System: /etc/codex/config.toml (system-level config)
+    #
+    # Codex has a unique "trust" model - project config is only used
+    # for trusted projects. Untrusted projects will have a warning
+    # and no project layer.
+    #
+    # Environment variable CODEX_HOME can override the home directory
+    # where the global config is located.
+    #
+    # @example Trusted project
+    #   adapter = Codex.new
+    #   layers = adapter.layers(dir: "/work/my_app", env: ENV, trusted: true)
+    #   layers.count  #=> includes project layer
+    #
+    # @example Untrusted project
+    #   layers = adapter.layers(dir: "/untrusted", env: ENV, trusted: false)
+    #   adapter.warnings(...)  #=> ["Project config ignored for untrusted project"]
+    class Codex
+      # Get all config layers for Codex.
+      #
+      # Returns an array of Location objects for global, system (if exists),
+      # and project (if trusted) configs. Project config is excluded for
+      # untrusted projects.
+      #
+      # @param dir [String] project directory path
+      # @param env [Hash] environment variables hash (CODEX_HOME is used)
+      # @param trusted [Boolean] whether the project is trusted
+      # @return [Array<Location>] config layers in precedence order
+      def layers(dir:, env:, trusted:)
+        build_layers(dir, env, trusted)
+      end
+
+      # Get environment variable overrides for Codex.
+      #
+      # Checks for CODEX_HOME environment variable. When set, it changes
+      # the base directory for the global config (from ~ to the specified path).
+      #
+      # @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 Codex configuration.
+      #
+      # Returns a warning if the project is untrusted but has a config file.
+      # This helps users understand why their project config is being ignored.
+      #
+      # @param dir [String] project directory path
+      # @param env [Hash] environment variables hash (unused)
+      # @param trusted [Boolean] whether the project is trusted
+      # @return [Array<String>] warning messages
+      def warnings(dir:, env:, trusted:) # rubocop:disable Lint/UnusedMethodArgument
+        warnings = []
+        if !trusted && File.exist?(File.join(dir, ".codex", "config.toml"))
+          warnings << "Project config ignored for untrusted project"
+        end
+        warnings
+      end
+
+      private
+
+      # Build the list of config layers.
+      #
+      # Creates Location objects for global, system (if exists), and
+      # project (if trusted) configs. CODEX_HOME can override the
+      # home directory for global config location.
+      #
+      # @param dir [String] project directory path
+      # @param env [Hash] environment variables hash
+      # @param trusted [Boolean] whether the project is trusted
+      # @return [Array<Location>] config layers with active flag set
+      def build_layers(dir, env, trusted)
+        home = env["CODEX_HOME"] || Dir.home
+        global_path = File.join(home, ".codex", "config.toml")
+        system_path = "/etc/codex/config.toml"
+        project_path = File.join(dir, ".codex", "config.toml")
+
+        layers = []
+        layers << build_layer(:global, "user", global_path)
+        layers << build_layer(:system, "system", system_path) if File.exist?(system_path)
+
+        layers << build_layer(:project, "file", project_path) if trusted
+
+        mark_active(layers)
+      end
+
+      # Build environment variable overrides.
+      #
+      # Checks if CODEX_HOME is set and creates an EnvOverride for it.
+      # The override's path is the config.toml file within the specified
+      # home directory's .codex subdirectory.
+      #
+      # @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 = []
+
+        if (value = env["CODEX_HOME"])
+          path = File.join(value, ".codex", "config.toml")
+          overrides << EnvOverride.new(
+            agent: :codex,
+            name: "CODEX_HOME",
+            value: value,
+            path: path,
+            exists: File.exist?(path),
+            active: File.exist?(path),
+            note: "Home directory override"
+          )
+        end
+
+        overrides
+      end
+
+      # Build a Location object for a config layer.
+      #
+      # @param scope [Symbol] the scope (:global, :project, :system)
+      # @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: :codex,
+          scope: scope,
+          source: source,
+          path: path,
+          exists: File.exist?(path),
+          active: false,
+          note: nil
+        )
+      end
+
+      # Mark the first existing layer as active.
+      #
+      # @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

data/lib/agent_settings/adapters/opencode.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module AgentSettings
+  module Adapters
+    # Adapter for OpenCode agent configuration.
+    #
+    # OpenCode stores configuration in JSON files:
+    #
+    # - Global: ~/.config/opencode/opencode.json (user-level config)
+    # - Project: opencode.json (discovered by walking up from project directory)
+    #
+    # OpenCode supports multiple environment variable overrides:
+    # - OPENCODE_CONFIG: Direct path to config file
+    # - OPENCODE_CONFIG_DIR: Directory containing opencode.json
+    # - OPENCODE_CONFIG_CONTENT: Inline JSON config content
+    #
+    # The project config uses discovery - it walks up from the provided
+    # directory looking for opencode.json, similar to how git finds .git.
+    #
+    # @example
+    #   adapter = Opencode.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 Opencode
+      # Get all config layers for OpenCode.
+      #
+      # Returns an array of Location objects for global and project
+      # configs. Project config is discovered by walking up the directory
+      # tree from the provided dir.
+      #
+      # @param dir [String] project directory path (starting point for discovery)
+      # @param env [Hash] environment variables hash (unused for layers)
+      # @param trusted [Boolean] whether the project is trusted (unused)
+      # @return [Array<Location>] config layers in precedence order
+      def layers(dir:, env:, trusted:) # rubocop:disable Lint/UnusedMethodArgument
+        build_layers(dir)
+      end
+
+      # Get environment variable overrides for OpenCode.
+      #
+      # Checks for three environment variables:
+      # - OPENCODE_CONFIG: Path to config file (active if file exists)
+      # - OPENCODE_CONFIG_DIR: Directory containing opencode.json
+      # - OPENCODE_CONFIG_CONTENT: Inline JSON (always active if set)
+      #
+      # @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 OpenCode configuration.
+      #
+      # OpenCode doesn't produce any warnings currently.
+      #
+      # @return [Array<String>] empty array
+      def warnings(*) = []
+
+      private
+
+      # Build the list of config layers.
+      #
+      # Creates Location objects for global and project configs.
+      # Project config is discovered by walking up the directory tree.
+      #
+      # @param dir [String] project directory path
+      # @return [Array<Location>] config layers with active flag set
+      def build_layers(dir)
+        home = Dir.home
+        global_path = File.join(home, ".config", "opencode", "opencode.json")
+        project_path = discover_project_config(dir)
+
+        layers = []
+        layers << build_layer(:global, "user", global_path)
+        layers << build_layer(:project, "file", project_path) if project_path
+
+        mark_active(layers)
+      end
+
+      # Discover project config by walking up the directory tree.
+      #
+      # OpenCode project config is named opencode.json (no leading dot).
+      # This method walks up from the provided directory looking for it,
+      # similar to how git finds .git directories.
+      #
+      # @param dir [String] starting directory
+      # @return [String] path to opencode.json (existing or default)
+      def discover_project_config(dir)
+        current = File.expand_path(dir)
+        root = File.expand_path("/")
+
+        while current != root
+          path = File.join(current, "opencode.json")
+          return path if File.exist?(path)
+
+          current = File.dirname(current)
+        end
+
+        File.join(dir, "opencode.json")
+      end
+
+      # Build environment variable overrides.
+      #
+      # Checks all three OpenCode environment variables and creates
+      # EnvOverride objects for any that are set. OPENCODE_CONFIG_CONTENT
+      # is always active if set (it's inline content, not a file path).
+      #
+      # @param env [Hash] environment variables hash
+      # @return [Array<EnvOverride>] detected overrides
+      def build_env_overrides(env) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength -- handles three different env vars with full attribute construction
+        overrides = []
+
+        if (value = env["OPENCODE_CONFIG"])
+          overrides << EnvOverride.new(
+            agent: :opencode,
+            name: "OPENCODE_CONFIG",
+            value: value,
+            path: value,
+            exists: File.exist?(value),
+            active: File.exist?(value),
+            note: "Config file override"
+          )
+        end
+
+        if (value = env["OPENCODE_CONFIG_DIR"])
+          path = File.join(value, "opencode.json")
+          overrides << EnvOverride.new(
+            agent: :opencode,
+            name: "OPENCODE_CONFIG_DIR",
+            value: value,
+            path: path,
+            exists: File.exist?(path),
+            active: File.exist?(path),
+            note: "Config directory override"
+          )
+        end
+
+        if (value = env["OPENCODE_CONFIG_CONTENT"])
+          overrides << EnvOverride.new(
+            agent: :opencode,
+            name: "OPENCODE_CONFIG_CONTENT",
+            value: value[0, 50] + (value.length > 50 ? "..." : ""),
+            path: "(inline)",
+            exists: true,
+            active: true,
+            note: "Inline config content"
+          )
+        end
+
+        overrides
+      end
+
+      # Build a Location object for a config layer.
+      #
+      # @param scope [Symbol] the scope (:global, :project)
+      # @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: :opencode,
+          scope: scope,
+          source: source,
+          path: path,
+          exists: File.exist?(path),
+          active: false,
+          note: nil
+        )
+      end
+
+      # Mark the first existing layer as active.
+      #
+      # @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

data/lib/agent_settings/agent_config_path.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module AgentSettings
+  # The complete result of resolving an agent's config location.
+  #
+  # AgentConfigPath is the primary return value from {AgentSettings.resolve}
+  # and contains all information about where an agent's configuration is
+  # located, including:
+  #
+  # - The effective (active) config location
+  # - Global and project-specific locations
+  # - All config layers organized by precedence
+  # - Environment variable overrides detected
+  # - Any warnings (e.g., untrusted project)
+  #
+  # The effective location is determined by checking in order:
+  # 1. Active environment variable overrides (highest precedence)
+  # 2. First existing layer in precedence order
+  # 3. First layer if none exist
+  #
+  # @example
+  #   result = AgentSettings.resolve(:claude, dir: Dir.pwd)
+  #   result.effective.path     #=> "/Users/me/.claude/settings.json"
+  #   result.effective.exists?  #=> true
+  #   result.global             #=> Location for global config
+  #   result.project            #=> Location for project config
+  #   result.custom_config?     #=> false (no env override active)
+  #
+  # @attr agent [Symbol] the agent this config path is for
+  # @attr effective [Location, nil] the currently active config location
+  # @attr global [Location, nil] the global (user) config location
+  # @attr project [Location, nil] the project-level config location
+  # @attr layers [Array<Location>] all config locations in precedence order
+  # @attr env_overrides [Array<EnvOverride>] detected environment variable overrides
+  # @attr warnings [Array<String>] any warnings about the configuration
+  AgentConfigPath = Data.define(:agent, :effective, :global, :project, :layers, :env_overrides, :warnings) do
+    # Check if a custom config is being used via environment variable.
+    #
+    # Returns true if any environment variable override is active,
+    # meaning the agent is using a config location different from
+    # the default file-based locations.
+    #
+    # @return [Boolean] true if an environment override is active
+    #
+    # @example
+    #   env = { "OPENCODE_CONFIG" => "/custom/config.json" }
+    #   result = AgentSettings.resolve(:opencode, dir: Dir.pwd, env: env)
+    #   result.custom_config?  #=> true (if /custom/config.json exists)
+    def custom_config? = env_overrides.any?(&:active?)
+  end
+end

data/lib/agent_settings/env_override.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module AgentSettings
+  # Represents an environment variable that overrides config location.
+  #
+  # Agents can use environment variables to override their default config
+  # locations. EnvOverride captures information about these variables,
+  # including their name, value, the resulting config path, and whether
+  # the override is active (i.e., the target file exists).
+  #
+  # Supported environment variables by agent:
+  # - Claude: CLAUDE_CONFIG_DIR
+  # - OpenCode: OPENCODE_CONFIG, OPENCODE_CONFIG_DIR, OPENCODE_CONFIG_CONTENT
+  # - Codex: CODEX_HOME
+  #
+  # @example
+  #   override = EnvOverride.new(
+  #     agent: :claude,
+  #     name: 'CLAUDE_CONFIG_DIR',
+  #     value: '/custom/config',
+  #     path: '/custom/config/settings.json',
+  #     exists: true,
+  #     active: true,
+  #     note: 'Config directory override'
+  #   )
+  #   override.active?  #=> true
+  #
+  # @attr agent [Symbol] the agent this override applies to
+  # @attr name [String] the environment variable name (e.g., 'CLAUDE_CONFIG_DIR')
+  # @attr value [String] the value of the environment variable
+  # @attr path [String] the resulting config file path
+  # @attr exists [Boolean] whether the config file exists at this path
+  # @attr active [Boolean] whether this override is in effect (file exists)
+  # @attr note [String] description of what this override does
+  EnvOverride = Data.define(:agent, :name, :value, :path, :exists, :active, :note) do
+    # @return [Boolean] whether the config file exists at this path
+    def exists? = exists
+
+    # @return [Boolean] whether this override is in effect
+    def active? = active
+
+    # Convert this override to a Location object.
+    #
+    # When an environment override is active, it becomes the effective
+    # config location. This method converts the override to a Location
+    # with scope :env.
+    #
+    # @return [Location] a Location representing this override
+    def to_location
+      Location.new(
+        agent: agent,
+        scope: :env,
+        source: name,
+        path: path,
+        exists: exists,
+        active: active,
+        note: note
+      )
+    end
+  end
+end

data/lib/agent_settings/location.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AgentSettings
+  # Represents a config file location for an agent.
+  #
+  # A Location describes where a configuration file is (or would be) stored,
+  # whether it exists, and whether it's the currently active configuration.
+  # Locations are organized by scope (global vs project) and source
+  # (user, system, file, etc.).
+  #
+  # @example
+  #   location = Location.new(
+  #     agent: :claude,
+  #     scope: :global,
+  #     source: 'user',
+  #     path: '/Users/me/.claude/settings.json',
+  #     exists: true,
+  #     active: true,
+  #     note: nil
+  #   )
+  #   location.exists?  #=> true
+  #   location.active?  #=> true
+  #
+  # @attr agent [Symbol] the agent this location belongs to (:claude, :opencode, :codex)
+  # @attr scope [Symbol] the scope of this location (:global, :project, :managed, :system, :env)
+  # @attr source [String] where this location comes from ('user', 'system', 'file', 'local')
+  # @attr path [String] the absolute file path to the config file
+  # @attr exists [Boolean] whether the config file exists at this path
+  # @attr active [Boolean] whether this is the currently effective config location
+  # @attr note [String, nil] optional note about this location
+  Location = Data.define(:agent, :scope, :source, :path, :exists, :active, :note) do
+    # @return [Boolean] whether the config file exists at this path
+    def exists? = exists
+
+    # @return [Boolean] whether this is the currently effective config location
+    def active? = active
+  end
+end

data/lib/agent_settings/location_discovery.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module AgentSettings
+  # Internal module for discovering agent config locations.
+  #
+  # LocationDiscovery contains the core logic for finding and resolving
+  # where agent configuration files are located. It uses adapters (one per
+  # agent) to handle agent-specific rules, then applies common precedence
+  # logic to determine the effective configuration.
+  #
+  # This module is used internally by the {AgentSettings} public API methods.
+  # You typically don't need to call it directly.
+  #
+  # @api private
+  module LocationDiscovery
+    module_function
+
+    # Find the global config location for an agent.
+    #
+    # Queries the appropriate adapter and extracts the global-scoped
+    # location from the layers.
+    #
+    # @param agent [Symbol] the agent identifier
+    # @param env [Hash] environment variables
+    # @param dir [String] project directory
+    # @param trusted [Boolean] whether project is trusted
+    # @return [Location, nil] the global location, or nil
+    def global(agent, env:, dir:, trusted:)
+      adapter = Registry.adapter(agent)
+      layers = adapter.layers(dir: dir, env: env, trusted: trusted)
+      layers.find { |l| l.scope == :global }
+    end
+
+    # Find the project config location for an agent.
+    #
+    # Queries the appropriate adapter and extracts the project-scoped
+    # location from the layers. Note that some agents (like Codex) may
+    # not return a project location for untrusted projects.
+    #
+    # @param agent [Symbol] the agent identifier
+    # @param dir [String] project directory
+    # @param env [Hash] environment variables
+    # @param trusted [Boolean] whether project is trusted
+    # @return [Location, nil] the project location, or nil
+    def project(agent, dir:, env:, trusted:)
+      adapter = Registry.adapter(agent)
+      layers = adapter.layers(dir: dir, env: env, trusted: trusted)
+      layers.find { |l| l.scope == :project }
+    end
+
+    # Resolve complete config path information for an agent.
+    #
+    # This is the main discovery method. It:
+    # 1. Gets the appropriate adapter for the agent
+    # 2. Retrieves all config layers from the adapter
+    # 3. Retrieves any environment variable overrides
+    # 4. Retrieves any warnings
+    # 5. Determines the effective location based on precedence
+    # 6. Builds and returns an AgentConfigPath with all information
+    #
+    # @param agent [Symbol] the agent identifier
+    # @param dir [String] project directory
+    # @param env [Hash] environment variables
+    # @param trusted [Boolean] whether project is trusted
+    # @return [AgentConfigPath] complete config path information
+    def resolve(agent, dir:, env:, trusted:) # rubocop:disable Metrics/MethodLength -- orchestrates adapter calls and builds complete AgentConfigPath
+      adapter = Registry.adapter(agent)
+      layers = adapter.layers(dir: dir, env: env, trusted: trusted)
+      env_overrides = adapter.env_overrides(dir: dir, env: env, trusted: trusted)
+      warnings = adapter.warnings(dir: dir, env: env, trusted: trusted)
+
+      effective = find_effective(layers, env_overrides)
+      global = layers.find { |l| l.scope == :global }
+      project = layers.find { |l| l.scope == :project }
+
+      AgentConfigPath.new(
+        agent: agent,
+        effective: effective,
+        global: global,
+        project: project,
+        layers: layers,
+        env_overrides: env_overrides,
+        warnings: warnings
+      )
+    end
+
+    # Resolve config paths for all supported agents.
+    #
+    # Iterates through all known agents and resolves each one,
+    # returning a hash mapping agent symbols to AgentConfigPath objects.
+    #
+    # @param dir [String] project directory
+    # @param env [Hash] environment variables
+    # @param trusted [Boolean] whether project is trusted
+    # @return [Hash{Symbol => AgentConfigPath}] map of agent to config path
+    def all(dir:, env:, trusted:)
+      Registry::AGENTS.to_h do |agent|
+        [agent, resolve(agent, dir: dir, env: env, trusted: trusted)]
+      end
+    end
+
+    # Determine the effective config location.
+    #
+    # The effective location is determined by precedence:
+    # 1. If an environment override is active, convert it to a Location
+    # 2. Otherwise, use the first existing layer
+    # 3. If no layers exist, use the first layer (even though it doesn't exist)
+    #
+    # @param layers [Array<Location>] config layers in precedence order
+    # @param env_overrides [Array<EnvOverride>] environment variable overrides
+    # @return [Location, nil] the effective location
+    def find_effective(layers, env_overrides)
+      active_override = env_overrides.find(&:active?)
+      return active_override.to_location if active_override
+
+      layers.find(&:active?) || layers.first
+    end
+  end
+end

data/lib/agent_settings/registry.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AgentSettings
+  # Registry mapping agent symbols to their adapter classes.
+  #
+  # The Registry is responsible for knowing which adapters exist and
+  # providing the correct adapter instance for a given agent symbol.
+  # It also defines the list of supported agents.
+  #
+  # @api private
+  module Registry
+    # List of supported agent symbols.
+    AGENTS = %i[claude opencode codex].freeze
+
+    module_function
+
+    # Get the adapter instance for an agent.
+    #
+    # Returns a new instance of the appropriate adapter class for the
+    # given agent symbol. Uses pattern matching to select the adapter.
+    #
+    # @param agent [Symbol] the agent identifier (:claude, :opencode, :codex)
+    # @return [Object] an instance of the appropriate adapter class
+    # @raise [UnknownAgentError] if the agent symbol is not recognized
+    #
+    # @example
+    #   adapter = Registry.adapter(:claude)  #=> AgentSettings::Adapters::Claude instance
+    #   adapter.layers(dir: Dir.pwd, env: {}, trusted: true)
+    def adapter(agent)
+      case agent
+      in :claude then Adapters::Claude.new
+      in :opencode then Adapters::Opencode.new
+      in :codex then Adapters::Codex.new
+      else
+        raise UnknownAgentError, "Unknown agent: #{agent}. Supported: #{AGENTS.join(", ")}"
+      end
+    end
+  end
+end

data/lib/agent_settings/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AgentSettings
+  # Current gem version.
+  VERSION = "0.1.0"
+end