agent_homedir 0.3.0

data/lib/agent/homedir/entry.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Agent
+  module Homedir
+    class Entry < 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
+end

data/lib/agent/homedir/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Agent
+  module Homedir
+    class Error < StandardError; end
+  end
+end

data/lib/agent/homedir/home_not_resolvable.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Agent
+  module Homedir
+    class HomeNotResolvable < Error; end
+  end
+end

data/lib/agent/homedir/registry.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Agent
+  module Homedir
+    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
+end

data/lib/agent/homedir/resolver.rb

@@ -0,0 +1,375 @@
+# frozen_string_literal: true
+
+require "agent/homedir"
+require "date"
+require "monitor"
+require "pathname"
+require "rbconfig"
+
+module Agent
+  module Homedir
+    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)
+
+        Entry.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
+end

data/lib/agent/homedir/unknown_agent.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Agent
+  module Homedir
+    class UnknownAgent < Error; end
+  end
+end

data/lib/agent/homedir/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Agent
+  module Homedir
+    VERSION = "0.3.0"
+  end
+end

data/lib/agent/homedir.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "zeitwerk"
+
+module Agent
+  module Homedir
+  end
+end
+
+loader = Zeitwerk::Loader.for_gem_extension(Agent)
+loader.setup
+Agent::Homedir.const_set(:LOADER, loader)
+
+module Agent
+  module Homedir
+    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 [Agent::Homedir::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 [Agent::Homedir::UnknownAgent] if the name is not registered
+      # @raise [Agent::Homedir::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 [Agent::Homedir::UnknownAgent] if the name is not registered
+      # @raise [Agent::Homedir::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 [Agent::Homedir::Entry]
+      # @raise [Agent::Homedir::UnknownAgent] if the name is not registered
+      def [](name)
+        default_resolver[name]
+      end
+
+      # Returns all known agents in registry order.
+      #
+      # @return [Array<Agent::Homedir::Entry>]
+      def agents
+        default_resolver.agents
+      end
+
+      # Returns currently installed agents in registry order.
+      #
+      # @return [Array<Agent::Homedir::Entry>]
+      # @raise [Agent::Homedir::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
+end

data/lib/agent_homedir.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "agent/homedir"