Module: AgentSettings::LocationDiscovery Private

Defined in:
lib/agent_settings/location_discovery.rb

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

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.

Class Method Summary collapse

Class Method Details

.all(dir:, env:, trusted:) ⇒ Hash{Symbol => AgentConfigPath}

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Parameters:

  • dir (String) —

    project directory

  • env (Hash) —

    environment variables

  • trusted (Boolean) —

    whether project is trusted

Returns:



96
97
98
99
100
 
# File 'lib/agent_settings/location_discovery.rb', line 96

def all(dir:, env:, trusted:)
  Registry::AGENTS.to_h do |agent|
    [agent, resolve(agent, dir: dir, env: env, trusted: trusted)]
  end
end

.find_effective(layers, env_overrides) ⇒ Location?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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)

Parameters:

  • layers (Array<Location>) —

    config layers in precedence order

  • env_overrides (Array<EnvOverride>) —

    environment variable overrides

Returns:

  • (Location, nil) —

    the effective location



112
113
114
115
116
117
 
# File 'lib/agent_settings/location_discovery.rb', line 112

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

.global(agent, env:, dir:, trusted:) ⇒ Location?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Find the global config location for an agent.

Queries the appropriate adapter and extracts the global-scoped location from the layers.

Parameters:

  • agent (Symbol) —

    the agent identifier

  • env (Hash) —

    environment variables

  • dir (String) —

    project directory

  • trusted (Boolean) —

    whether project is trusted

Returns:

  • (Location, nil) —

    the global location, or nil



28
29
30
31
32
 
# File 'lib/agent_settings/location_discovery.rb', line 28

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

.project(agent, dir:, env:, trusted:) ⇒ Location?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Parameters:

  • agent (Symbol) —

    the agent identifier

  • dir (String) —

    project directory

  • env (Hash) —

    environment variables

  • trusted (Boolean) —

    whether project is trusted

Returns:

  • (Location, nil) —

    the project location, or nil



45
46
47
48
49
 
# File 'lib/agent_settings/location_discovery.rb', line 45

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(agent, dir:, env:, trusted:) ⇒ AgentConfigPath

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Parameters:

  • agent (Symbol) —

    the agent identifier

  • dir (String) —

    project directory

  • env (Hash) —

    environment variables

  • trusted (Boolean) —

    whether project is trusted

Returns:



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/agent_settings/location_discovery.rb', line 66

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