agents_homedir 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 70b9327c32fb87519bf706ebff96bcf9ad9e9958a1f07343d243c7b9b0fd2f48
+  data.tar.gz: d9aa3e2a90f74614da2ac65d5509e450c55d18c8c7f98a7e176098aa49205a50
+SHA512:
+  metadata.gz: fc955ace89303a11c2c837f03055a850a2b5f079a6aafac1a22d3f3f4cc6e6ee50615d62c311417d083b73909561eca6defb431e1cfb94399f60db3dcc2bef1f
+  data.tar.gz: 80208dde85e0c12bbb7b9283dcea419ba3af54f6d02a33165209bfee1f1e722f0207dbbff52f18ab62fa71d25d4dc0bfaab0f3e0a216bae1f2a509dbdd92368f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Lucian Ghinda
+
+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,142 @@
+# AgentsHomedir
+
+Find the home folder an AI coding agent uses, without reading contents.
+
+## Installation
+
+Use Ruby 3.2 or newer. The gem ships with one runtime dependency: Zeitwerk 2.8.
+
+Add this line to your application's **Gemfile**:
+
+```ruby
+gem "agents_homedir"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Or install it directly:
+
+```sh
+gem install agents_homedir
+```
+
+## Quick Start
+
+Get a home path:
+
+```ruby
+require "agents_homedir"
+
+AgentsHomedir.home(:claude_code)
+```
+
+Check installation:
+
+```ruby
+require "agents_homedir"
+
+AgentsHomedir.installed?(:codex)
+```
+
+Expect a `Pathname` and a boolean.
+
+The module facade is snapshotted on first access.
+That snapshots `ENV` and `HOME` for the rest of the process.
+If you need a different snapshot, instantiate `AgentsHomedir::Resolver` directly.
+
+## Usage
+
+Fetch an agent:
+
+```ruby
+require "agents_homedir"
+
+agent = AgentsHomedir[:codex]
+
+agent.name
+agent.label
+agent.home
+```
+
+Discover the catalog:
+
+```ruby
+require "agents_homedir"
+
+AgentsHomedir.names
+AgentsHomedir.agents
+AgentsHomedir.installed
+```
+
+Expect ordered, frozen arrays.
+
+Inspect agent facts:
+
+```ruby
+require "agents_homedir"
+
+agent = AgentsHomedir[:claude_code]
+
+agent.env_override
+agent.verified_on
+agent.candidates
+```
+
+Resolution order:
+
+- Use a nonblank native override.
+- Use the first existing directory candidate.
+- Use the first candidate otherwise.
+
+Agent facts:
+
+- `name` is a `Symbol`.
+- `label` is a `String`.
+- `home` returns a `Pathname`.
+- `installed?` returns a boolean.
+- `candidates` returns an ordered, frozen array of `Pathname` objects.
+- `env_override` is a `String` or `nil`.
+- `verified_on` is a `Date` or `nil`.
+
+Errors:
+
+- Catch `AgentsHomedir::UnknownAgent` to list valid names.
+- Catch `AgentsHomedir::HomeNotResolvable` for missing, blank, or nonabsolute `HOME`.
+
+## Testing
+
+Pass `env`, `home`, and `os` explicitly.
+Instantiate a fresh resolver when you need a different environment snapshot.
+Do not stub global `ENV`.
+
+```ruby
+require "agents_homedir"
+
+resolver = AgentsHomedir::Resolver.new(
+  env: { "CODEX_HOME" => "custom/codex" },
+  home: "/Users/me",
+  os: :linux
+)
+
+resolver.home(:codex)
+# => #<Pathname:/Users/me/custom/codex>
+```
+
+## Contributing
+
+Activate Ruby 3.2 or newer.
+
+Run the tests before sending a change.
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/agents_homedir/agent.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "date"
+
+module AgentsHomedir
+  class Agent < Data.define(:name, :label, :env_override, :verified_on)
+    # Equality and hash intentionally cover only public facts.
+    # Resolver-specific caches should key by resolver and agent name.
+    def initialize(name:, label:, env_override:, verified_on:, resolver:)
+      validate_name!(name)
+      validate_label!(label)
+      validate_env_override!(env_override)
+      validate_verified_on!(verified_on)
+
+      @resolver = resolver
+
+      super(
+        name: name,
+        label: snapshot_string(label),
+        env_override: snapshot_string(env_override),
+        verified_on:
+      )
+    end
+
+    def home = @resolver.home(name)
+
+    def installed? = @resolver.installed?(name)
+
+    def candidates = @resolver.candidates(name)
+
+    def with(**changes)
+      return self if changes.empty?
+
+      unknown_members = changes.keys - self.class.members
+      fail ArgumentError, "Unknown member(s) for #{self.class}: #{unknown_members.map(&:inspect).join(', ')}" if unknown_members.any?
+      reject_resolver_bound_changes!(changes)
+
+      updated = to_h.merge(changes)
+      return self if updated == to_h
+
+      self.class.new(**updated, resolver: @resolver)
+    end
+
+    private
+
+    def reject_resolver_bound_changes!(changes)
+      [:name, :env_override].each do |field|
+        next unless changes.key?(field)
+        next if changes[field] == public_send(field)
+
+        fail ArgumentError, "#{field} is resolver-bound and cannot be changed via #with"
+      end
+    end
+
+    def validate_name!(value)
+      fail ArgumentError, "name must be a Symbol" unless value.is_a?(Symbol)
+    end
+
+    def validate_label!(value)
+      fail ArgumentError, "label must be a String" unless value.is_a?(String)
+    end
+
+    def validate_env_override!(value)
+      return if value.nil? || value.is_a?(String)
+
+      fail ArgumentError, "env_override must be a String or nil"
+    end
+
+    def validate_verified_on!(value)
+      return if value.nil? || value.is_a?(Date)
+
+      fail ArgumentError, "verified_on must be a Date or nil"
+    end
+
+    def snapshot_string(value)
+      return if value.nil?
+
+      value.dup.freeze
+    end
+  end
+end

data/lib/agents_homedir/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentsHomedir
+  class Error < StandardError; end
+end

data/lib/agents_homedir/home_not_resolvable.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentsHomedir
+  class HomeNotResolvable < Error; end
+end

data/lib/agents_homedir/registry.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module AgentsHomedir
+  module Registry
+    class << self
+      def entries
+        @entries ||= deep_freeze(
+          {
+            claude_code: agent("Claude Code", env: "CLAUDE_CONFIG_DIR", paths: "~/.claude", verified_on: "2026-08-05"),
+            codex: agent("Codex CLI", env: "CODEX_HOME", paths: "~/.codex", verified_on: "2026-07-21"),
+            gemini: agent("Gemini CLI", paths: "~/.gemini"),
+            antigravity_cli: agent("Antigravity CLI", paths: "~/.gemini/antigravity-cli"),
+            antigravity_ide: agent("Antigravity IDE", paths: "~/.gemini/antigravity-ide"),
+            antigravity_app: agent("Antigravity App", paths: "~/.gemini/antigravity"),
+            qwen: agent("Qwen Code", paths: "~/.qwen"),
+            pi: agent("Pi", env: "PI_CODING_AGENT_DIR", paths: "~/.pi/agent", verified_on: "2026-07-21"),
+            amp: agent("Amp", paths: [xdg_data("amp")], verified_on: "2026-07-21"),
+            opencode: agent(
+              "OpenCode",
+              env: "OPENCODE_DATA_DIR",
+              paths: {
+                macos: [xdg_data("opencode"), "~/Library/Application Support/opencode"],
+                linux: [xdg_data("opencode")],
+                windows: [
+                  windows_env("XDG_DATA_HOME", "opencode", optional: true),
+                  windows_env("APPDATA", "opencode"),
+                  windows_env("LOCALAPPDATA", "opencode"),
+                  "~/.local/share/opencode"
+                ]
+              },
+              verified_on: "2026-07-21"
+            ),
+            cursor: agent("Cursor", paths: "~/.cursor", verified_on: "2026-07-21"),
+            cursor_ide: agent(
+              "Cursor IDE",
+              paths: {
+                macos: "~/Library/Application Support/Cursor",
+                linux: xdg_config("Cursor"),
+                windows: windows_env("APPDATA", "Cursor")
+              }
+            ),
+            github_copilot_cli: agent("GitHub Copilot CLI", paths: "~/.copilot"),
+            vscode_copilot_chat: agent(
+              "VS Code Copilot Chat",
+              paths: {
+                macos: "~/Library/Application Support/Code/User",
+                linux: xdg_config("Code/User"),
+                windows: windows_env("APPDATA", "Code/User")
+              }
+            ),
+            cline: agent("Cline", paths: "~/.cline"),
+            cline_vscode: agent(
+              "Cline for VS Code",
+              paths: {
+                macos: "~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev",
+                linux: xdg_config("Code/User/globalStorage/saoudrizwan.claude-dev"),
+                windows: windows_env("APPDATA", "Code/User/globalStorage/saoudrizwan.claude-dev")
+              }
+            ),
+            grok_build: agent("Grok Build", paths: "~/.grok"),
+            vibe: agent("Vibe", paths: "~/.vibe"),
+            muse: agent("Muse Code", paths: [xdg_data("muse")]),
+            prime_agent: agent("Prime Agent", paths: "~/.prime/agent"),
+            deepseek_harness: agent("DeepSeek Harness", env: "DSH_HOME", paths: "~/.dsh"),
+            hermes: agent("Hermes Agent", env: "HERMES_HOME", paths: "~/.hermes"),
+            factory_droid: agent("Factory Droid", paths: "~/.factory"),
+            devin_cli: agent("Devin CLI", paths: "~/.config/devin"),
+            devin_desktop: agent("Devin Desktop", paths: "~/.codeium/windsurf")
+          }
+        )
+      end
+
+      private
+
+      def agent(label, env: nil, paths:, verified_on: nil)
+        {
+          label:,
+          env:,
+          paths:,
+          verified_on:
+        }
+      end
+
+      def xdg_config(path)
+        {xdg: :config, path:}
+      end
+
+      def xdg_data(path)
+        {xdg: :data, path:}
+      end
+
+      def windows_env(env_key, path, optional: false)
+        spec = {windows_env: env_key, path:}
+        optional ? spec.merge(optional: true) : spec
+      end
+
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), copy|
+            copy[deep_freeze(key)] = deep_freeze(nested)
+          end.freeze
+        when Array
+          value.map { deep_freeze(_1) }.freeze
+        when String
+          value.dup.freeze
+        else
+          value
+        end
+      end
+    end
+  end
+
+  private_constant :Registry
+end

data/lib/agents_homedir/resolver.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+require "agents_homedir"
+require "date"
+require "monitor"
+require "pathname"
+require "rbconfig"
+
+module AgentsHomedir
+  class Resolver
+    VALID_OSES = %i[macos linux windows].freeze
+    WINDOWS_DRIVE_PATH = /\A[A-Za-z]:[\/\\]/.freeze
+    WINDOWS_UNC_PATH = /\A[\/\\]{2}[^\/\\]+[\/\\]+[^\/\\]+/.freeze
+
+    class << self
+      def default_os
+        @default_os ||= detect_os(RbConfig::CONFIG["host_os"])
+      end
+
+      private
+
+      def detect_os(host_os)
+        case host_os
+        when /darwin/i
+          :macos
+        when /linux/i
+          :linux
+        when /mswin|mingw/i
+          :windows
+        else
+          fail ArgumentError, "Unsupported host OS: #{host_os.inspect}"
+        end
+      end
+    end
+
+    def initialize(env: ENV.to_h, home: ENV["HOME"], os: self.class.default_os, entries: Registry.entries)
+      fail ArgumentError, "Invalid OS #{os.inspect}; expected one of #{VALID_OSES.inspect}" unless VALID_OSES.include?(os)
+
+      @env = snapshot_value(env)
+      @home = snapshot_value(home)
+      @os = os
+      @entries = snapshot_value(entries)
+      @memoization_monitor = Monitor.new
+    end
+
+    def home(name)
+      ensure_home_root!
+
+      override = env_override_for(name)
+      return override if override
+
+      available_candidates = candidates(name)
+      find_directory_candidate(available_candidates) || available_candidates.first
+    end
+
+    def installed?(name)
+      ensure_home_root!
+
+      override = env_override_for(name)
+      return true if directory_path?(override)
+
+      candidates(name).any? { directory_path?(_1) }
+    end
+
+    def candidates(name)
+      home_root = ensure_home_root!
+      specs = path_specs_for(name)
+      expanded = expand_specs(specs, home_root)
+      fail ArgumentError, no_paths_message(name, "current os paths are empty") if expanded.empty?
+
+      expanded.freeze
+    end
+
+    def [](name)
+      key = name.to_sym
+      entry = entry_for(key)
+
+      Agent.new(
+        name: key,
+        label: entry.fetch(:label),
+        env_override: entry[:env],
+        verified_on: parse_verified_on(key, entry[:verified_on]),
+        resolver: self
+      )
+    end
+
+    def names
+      return @names if @names
+
+      @memoization_monitor.synchronize do
+        @names ||= @entries.keys.freeze
+      end
+    end
+
+    def agents
+      return @agents if @agents
+
+      @memoization_monitor.synchronize do
+        @agents ||= names.map { self[_1] }.freeze
+      end
+    end
+
+    def installed
+      agents.select(&:installed?).freeze
+    end
+
+    private
+
+    def entry_for(name)
+      key = name.to_sym
+      entry = @entries[key]
+      return entry if entry
+
+      valid = @entries.keys.map(&:inspect).sort.join(", ")
+      fail UnknownAgent, "Unknown agent #{name.inspect}. Valid agents: #{valid}"
+    end
+
+    def path_specs_for(name)
+      specs = entry_for(name).fetch(:paths)
+      fail ArgumentError, no_paths_message(name, "paths are nil") if specs.nil?
+      fail ArgumentError, no_paths_message(name, "paths are empty") if specs.respond_to?(:empty?) && specs.empty?
+
+      specs
+    end
+
+    def env_override_for(name)
+      entry = entry_for(name)
+      env_key = entry[:env]
+      return unless env_key
+
+      raw = @env[env_key]
+      return if blank?(raw)
+
+      Pathname(resolve_path(raw, ensure_home_root!, allow_relative: true))
+    end
+
+    def ensure_home_root!
+      raw_home = @home.to_s
+      fail HomeNotResolvable, "HOME is not resolvable" if blank?(raw_home)
+
+      normalized = normalize_separators(raw_home)
+      fail HomeNotResolvable, "HOME is not resolvable" unless absolute_path?(normalized)
+
+      normalized
+    end
+
+    def expand_specs(specs, home_root)
+      return specs.flat_map { expand_spec(_1, home_root) } if specs.is_a?(Array)
+
+      expand_spec(specs, home_root)
+    end
+
+    def expand_spec(spec, home_root)
+      case spec
+      when Array
+        expand_specs(spec, home_root)
+      when String
+        [Pathname(resolve_registry_path(spec, home_root))]
+      when Hash
+        if os_selector?(spec)
+          selected = spec[@os]
+          selected ? expand_spec(selected, home_root) : []
+        elsif spec.key?(:xdg)
+          [Pathname(resolve_xdg_path(spec, home_root))]
+        elsif spec.key?(:windows_env)
+          resolved = resolve_windows_env_path(spec)
+          resolved ? [Pathname(resolved)] : []
+        else
+          fail ArgumentError, "Unsupported path spec #{spec.inspect}"
+        end
+      else
+        fail ArgumentError, "Unsupported path spec #{spec.inspect}"
+      end
+    end
+
+    def os_selector?(spec)
+      !(spec.keys & VALID_OSES).empty?
+    end
+
+    def resolve_registry_path(spec, home_root)
+      if spec == "~" || spec.start_with?("~/", "~\\")
+        expand_tilde(spec, home_root)
+      else
+        normalized = normalize_separators(spec)
+        ensure_absolute!(normalized)
+      end
+    end
+
+    def resolve_xdg_path(spec, home_root)
+      base =
+        case spec.fetch(:xdg)
+        when :config
+          resolve_xdg_base("XDG_CONFIG_HOME", join_path(home_root, ".config"))
+        when :data
+          resolve_xdg_base("XDG_DATA_HOME", join_path(home_root, ".local/share"))
+        else
+          fail ArgumentError, "Unsupported XDG base #{spec[:xdg].inspect}"
+        end
+
+      join_child_path(base, spec.fetch(:path), "XDG")
+    end
+
+    def resolve_xdg_base(env_key, fallback)
+      value = @env[env_key]
+      return fallback if blank?(value)
+
+      normalized = normalize_separators(value.to_s)
+      return fallback unless absolute_path?(normalized)
+
+      normalized
+    end
+
+    def resolve_windows_env_path(spec)
+      env_key = spec.fetch(:windows_env)
+      base_value = @env[env_key]
+
+      if blank?(base_value)
+        fallback_suffix = windows_home_fallback_suffix(env_key)
+        base_value = join_child_path(ensure_home_root!, fallback_suffix, env_key) if fallback_suffix
+      end
+
+      return if blank?(base_value) && spec.fetch(:optional, false)
+      fail ArgumentError, "Missing windows_env #{env_key} for #{spec.inspect}" if blank?(base_value)
+
+      if optional_windows_xdg_env?(env_key, spec)
+        normalized = normalize_separators(base_value.to_s)
+        return unless absolute_path?(normalized)
+
+        base_value = normalized
+      end
+
+      base = resolve_path(base_value, ensure_home_root!, allow_relative: false)
+      join_child_path(base, spec.fetch(:path), env_key)
+    end
+
+    def resolve_path(raw_path, home_root, allow_relative:)
+      normalized = normalize_separators(raw_path.to_s)
+      return expand_tilde(normalized, home_root) if normalized == "~" || normalized.start_with?("~/", "~\\")
+      return normalized if absolute_path?(normalized)
+      fail ArgumentError, "Resolved path must be an ordinary relative path: #{raw_path.inspect}" if invalid_relative_join_path?(normalized)
+
+      if allow_relative
+        join_relative(home_root, normalized)
+      else
+        fail ArgumentError, "Resolved path must be absolute: #{raw_path.inspect}"
+      end
+    end
+
+    def expand_tilde(path, home_root)
+      suffix = path == "~" ? "" : path[2..]
+      suffix.empty? ? home_root : join_relative(home_root, suffix)
+    end
+
+    def join_child_path(base, child, source_name)
+      child_path = normalize_separators(child.to_s)
+      fail ArgumentError, "#{source_name} child path must be relative: #{child.inspect}" if blank?(child_path)
+      fail ArgumentError, "#{source_name} child path must be relative: #{child.inspect}" if absolute_path?(child_path)
+      fail ArgumentError, "#{source_name} child path must be relative: #{child.inspect}" if invalid_relative_join_path?(child_path)
+
+      join_relative(base, child_path)
+    end
+
+    def join_relative(base, relative)
+      relative_path = normalize_separators(relative.to_s)
+      return ensure_absolute!(relative_path) if absolute_path?(relative_path)
+      fail ArgumentError, "Resolved path must not stay relative: #{relative.inspect}" if relative_path.empty?
+
+      joined = join_path(base, relative_path)
+      ensure_absolute!(joined)
+    end
+
+    def join_path(base, suffix)
+      cleaned_base = normalize_separators(base)
+      cleaned_suffix = normalize_separators(suffix).sub(%r{\A/+}, "")
+      return "/" if posix_root_path?(cleaned_base) && cleaned_suffix.empty?
+      return "/#{cleaned_suffix}" if posix_root_path?(cleaned_base)
+
+      cleaned_base = cleaned_base.sub(%r{/+\z}, "")
+
+      [cleaned_base, cleaned_suffix].reject(&:empty?).join("/")
+    end
+
+    def ensure_absolute!(path)
+      normalized = normalize_separators(path)
+      fail ArgumentError, "Resolved path must be absolute: #{path.inspect}" unless absolute_path?(normalized)
+
+      normalized
+    end
+
+    def absolute_path?(path)
+      return windows_absolute_path?(path) if @os == :windows
+
+      Pathname(path).absolute?
+    end
+
+    def windows_absolute_path?(path)
+      normalized = normalize_separators(path)
+      normalized.match?(WINDOWS_DRIVE_PATH) || normalized.match?(WINDOWS_UNC_PATH)
+    end
+
+    def invalid_relative_join_path?(path)
+      return false unless @os == :windows
+      return false if absolute_path?(path)
+
+      path.start_with?("/") || drive_relative_path?(path)
+    end
+
+    def drive_relative_path?(path)
+      path.match?(/\A[A-Za-z]:(?!\/)/)
+    end
+
+    def find_directory_candidate(candidates)
+      candidates.find { directory_path?(_1) }
+    end
+
+    def windows_home_fallback_suffix(env_key)
+      {
+        "APPDATA" => "AppData/Roaming",
+        "LOCALAPPDATA" => "AppData/Local"
+      }[env_key]
+    end
+
+    def optional_windows_xdg_env?(env_key, spec)
+      spec.fetch(:optional, false) && env_key.start_with?("XDG_")
+    end
+
+    def directory_path?(path)
+      path&.directory? || false
+    end
+
+    def normalize_separators(path)
+      return path.tr("\\", "/") if @os == :windows
+
+      path
+    end
+
+    def posix_root_path?(path)
+      @os != :windows && path.match?(%r{\A/+\z})
+    end
+
+    def no_paths_message(name, detail)
+      "No paths configured for #{name.inspect} on #{@os.inspect}: #{detail}"
+    end
+
+    def parse_verified_on(name, value)
+      return if value.nil?
+      fail ArgumentError, "Invalid verified_on for #{name.inspect}: #{value.inspect}" unless value.is_a?(String)
+
+      Date.iso8601(value)
+    rescue Date::Error
+      fail ArgumentError, "Invalid verified_on for #{name.inspect}: #{value.inspect}"
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def snapshot_value(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, nested), copy|
+          copy[snapshot_value(key)] = snapshot_value(nested)
+        end.freeze
+      when Array
+        value.map { snapshot_value(_1) }.freeze
+      when String
+        value.dup.freeze
+      else
+        value
+      end
+    end
+  end
+end

data/lib/agents_homedir/unknown_agent.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentsHomedir
+  class UnknownAgent < Error; end
+end

data/lib/agents_homedir/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentsHomedir
+  VERSION = "0.1.0"
+end

data/lib/agents_homedir.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "zeitwerk"
+
+module AgentsHomedir
+end
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+AgentsHomedir.const_set(:LOADER, loader)
+
+module AgentsHomedir
+  DEFAULT_RESOLVER_MONITOR = Monitor.new
+  private_constant :DEFAULT_RESOLVER_MONITOR, :LOADER
+
+  class << self
+    # Returns the memoized default resolver built from the current environment.
+    # ENV and HOME are snapshotted on first access and reused for process lifetime.
+    #
+    # @return [AgentsHomedir::Resolver]
+    # @raise [ArgumentError] if the current host OS is unsupported
+    def default_resolver
+      return @default_resolver if @default_resolver
+
+      DEFAULT_RESOLVER_MONITOR.synchronize do
+        @default_resolver ||= Resolver.new
+      end
+    end
+
+    # Returns the configured home directory for the named agent.
+    #
+    # @param name [String, Symbol]
+    # @return [Pathname]
+    # @raise [AgentsHomedir::UnknownAgent] if the name is not registered
+    # @raise [AgentsHomedir::HomeNotResolvable] if HOME is missing, blank, or not absolute
+    def home(name)
+      default_resolver.home(name)
+    end
+
+    # Returns whether the named agent is currently installed.
+    #
+    # @param name [String, Symbol]
+    # @return [Boolean]
+    # @raise [AgentsHomedir::UnknownAgent] if the name is not registered
+    # @raise [AgentsHomedir::HomeNotResolvable] if HOME is missing, blank, or not absolute
+    def installed?(name)
+      default_resolver.installed?(name)
+    end
+
+    # Returns the named agent from the default registry.
+    #
+    # @param name [String, Symbol]
+    # @return [AgentsHomedir::Agent]
+    # @raise [AgentsHomedir::UnknownAgent] if the name is not registered
+    def [](name)
+      default_resolver[name]
+    end
+
+    # Returns all known agents in registry order.
+    #
+    # @return [Array<AgentsHomedir::Agent>]
+    def agents
+      default_resolver.agents
+    end
+
+    # Returns currently installed agents in registry order.
+    #
+    # @return [Array<AgentsHomedir::Agent>]
+    # @raise [AgentsHomedir::HomeNotResolvable] if HOME is missing, blank, or not absolute
+    def installed
+      default_resolver.installed
+    end
+
+    # Returns all known agent names in registry order.
+    #
+    # @return [Array<Symbol>]
+    def names
+      default_resolver.names
+    end
+
+    private
+
+    def loader
+      LOADER
+    end
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: agents_homedir
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lucian Ghinda
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Helpers for resolving and normalizing home directories used by AI coding
+  agents.
+email:
+- lucianghinda@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/agents_homedir.rb
+- lib/agents_homedir/agent.rb
+- lib/agents_homedir/error.rb
+- lib/agents_homedir/home_not_resolvable.rb
+- lib/agents_homedir/registry.rb
+- lib/agents_homedir/resolver.rb
+- lib/agents_homedir/unknown_agent.rb
+- lib/agents_homedir/version.rb
+homepage: https://github.com/lucianghinda/agents_homedir
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/lucianghinda/agents_homedir
+  bug_tracker_uri: https://github.com/lucianghinda/agents_homedir/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Resolve home directories for AI coding agents.
+test_files: []