ace-support-fs 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2c4e0121b057bd9f4bc10f6ecfd197a0df1a6050e18f1a82a855e4364a85629c
+  data.tar.gz: 23b62d54c4026a400e90c2a72577b87c8e482219d9035f1a867713d76a511e40
+SHA512:
+  metadata.gz: 329d52c1e0c1fb79a4466732188680570b3003cd3333a29a87c1283bc235d0d4f38c53d34e6b118aa9fe53e78e0197527f867714e5e58ccaa3a9bec0d93a8321
+  data.tar.gz: 3abd750584076f9e59e94a39651db0cafbf58efac334282f083c9fffcb4e541f37d877155512e5ceed0b88f92a929271cbe8c95d772fa2fcbbef5686960a2da0

data/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-03-23
+
+### Technical
+- Removed phantom `handbook/**/*` glob from gemspec (no handbook directory exists).
+
+## [0.2.3] - 2026-03-22
+
+### Technical
+- Updated README dependency example to use the current `~> 0.2` version constraint.
+
+## [0.2.2] - 2026-03-22
+
+### Technical
+- Refreshed README structure with consistent tagline, overview, basic usage, and ACE project footer
+
+## [0.2.1] - 2026-03-08
+
+### Fixed
+- Ignore `PROJECT_ROOT_PATH` overrides when the configured root does not contain the active `start_path`, preventing unrelated workspace roots from leaking into traversal boundaries.
+
+### Technical
+- Added regression coverage for environment-root fallback behavior in `ProjectRootFinder`.
+- Stabilized directory traversal molecule tests by isolating no-project-root fixtures from ambient system-level config directories.
+
+## [0.2.0] - 2026-01-03
+
+### Changed
+- **BREAKING**: Minimum Ruby version raised to 3.3.0 (was 3.1.0)
+- Standardized gemspec file patterns with deterministic Dir.glob
+- Added MIT LICENSE file
+
+## [0.1.0] - 2025-12-28
+
+### Added
+
+- Initial release extracting filesystem utilities from ace-support-core and ace-config
+- **PathExpander** atom with:
+  - Instance-based API (`for_file`, `for_cli`) for context-aware path resolution
+  - Protocol URI support (wfi://, guide://, tmpl://, etc.) with pluggable resolver
+  - Environment variable expansion ($VAR and ${VAR} formats)
+  - Source-relative (./) and project-relative path resolution
+  - Thread-safe protocol resolver registration with Mutex
+  - Backward-compatible class methods (expand, join, dirname, basename, etc.)
+  - Testability helper (`class_get_env` for ENV stubbing in tests)
+- **ProjectRootFinder** molecule with:
+  - Project root detection by marker files (.git, Gemfile, package.json, etc.)
+  - Thread-safe caching with Mutex
+  - PROJECT_ROOT_PATH environment variable support
+  - Instance and class method APIs
+  - Testability helper (`env_project_root` for ENV stubbing)
+- **DirectoryTraverser** molecule with:
+  - Config directory discovery from current to project root
+  - Cascade priority building for nearest-wins resolution
+  - Home directory inclusion with lower priority
+  - Configurable config directory name (default: `.ace`)
+- **PathError** exception class for protocol resolution failures
+
+### Design Decisions
+
+- Exception-based error handling (raise PathError) following ace-config pattern
+- Thread-safety with instance variables + Mutex (not class variables)
+- DEFAULT_MARKERS constant for project root markers
+- `config_dir` parameter name (not `config_dir_name`)
+- `class_get_env` for testability without subprocess overhead
+- No Windows support (not tested or supported)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+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,29 @@
+<div align="center">
+  <h1> ACE - Support FS </h1>
+
+  File system primitives for ACE path resolution and project root discovery.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-support-fs"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-support-fs.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+`ace-support-fs` provides reusable filesystem helpers for path expansion, root detection, and directory traversal. It handles the platform and context differences so packages like [ace-support-config](../ace-support-config) and [ace-search](../ace-search) can resolve paths safely from any working directory.
+
+## Use Cases
+
+**Resolve paths safely across subdirectories** - use consistent path expansion for tools that move across project subdirectories, including protocol-aware path handling.
+
+**Detect workspace boundaries** - infer project root from marker files without shell-specific assumptions, so [ace-search](../ace-search) and [ace-support-config](../ace-support-config) scope correctly.
+
+**Build config scans** - discover and rank candidate configuration directories during resolution, supporting the cascade logic in [ace-support-config](../ace-support-config).
+
+---
+
+Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+# Add :spec alias for CI compatibility
+task spec: :test
+
+task default: :test

data/lib/ace/support/fs/atoms/path_expander.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Ace
+  module Support
+    module Fs
+      module Atoms
+        # Path expansion and resolution with automatic context inference
+        #
+        # Supports:
+        # - Instance-based API for context-aware resolution
+        # - Protocol URIs (wfi://, guide://, tmpl://, task://, prompt://)
+        # - Source-relative paths (./, ../)
+        # - Project-relative paths (no prefix)
+        # - Environment variables ($VAR, ${VAR})
+        # - Backward compatible class methods for utilities
+        class PathExpander
+          # Protocol pattern for URI detection
+          PROTOCOL_PATTERN = %r{^[a-z][a-z0-9+.-]*://}
+
+          # Instance attributes
+          attr_reader :source_dir, :project_root
+
+          # Thread-safe protocol resolver registry
+          @protocol_resolver = nil
+          @protocol_resolver_mutex = Mutex.new
+
+          class << self
+            private
+
+            attr_reader :protocol_resolver_mutex
+          end
+
+          # === Factory Methods ===
+
+          # Create expander for a source file (config, workflow, template, prompt)
+          # Automatically infers source_dir, uses provided or default project_root
+          #
+          # @param source_file [String] Path to source file
+          # @param project_root [String, nil] Optional explicit project root (recommended)
+          # @return [PathExpander] Instance with inferred context
+          def self.for_file(source_file, project_root: nil)
+            expanded_source = File.expand_path(source_file)
+            source_dir = File.dirname(expanded_source)
+
+            # Use provided project_root or fall back to current directory
+            # Note: For full project root detection, caller should use
+            # Ace::Support::Fs::Molecules::ProjectRootFinder and pass the result
+            resolved_root = project_root || Dir.pwd
+
+            new(source_dir: source_dir, project_root: resolved_root)
+          end
+
+          # Create expander for CLI context (no source file)
+          # Uses current directory as source_dir
+          #
+          # @param project_root [String, nil] Optional explicit project root
+          # @return [PathExpander] Instance with CLI context
+          def self.for_cli(project_root: nil)
+            resolved_root = project_root || Dir.pwd
+
+            new(
+              source_dir: Dir.pwd,
+              project_root: resolved_root
+            )
+          end
+
+          # === Instance Methods ===
+
+          # Initialize with explicit context
+          #
+          # @param source_dir [String] Source document directory (REQUIRED)
+          # @param project_root [String] Project root directory (REQUIRED)
+          # @raise [ArgumentError] if either parameter is nil
+          def initialize(source_dir:, project_root:)
+            if source_dir.nil? || project_root.nil?
+              raise ArgumentError, "PathExpander requires both 'source_dir' and 'project_root' " \
+                                   "(got source_dir: #{source_dir.inspect}, project_root: #{project_root.inspect})"
+            end
+
+            @source_dir = source_dir
+            @project_root = project_root
+          end
+
+          # Resolve path using instance context
+          # Handles: protocols, source-relative (./), project-relative, env vars, absolute
+          #
+          # @param path [String] Path to resolve
+          # @return [String] Resolved absolute path
+          # @raise [PathError] When protocol cannot be resolved
+          def resolve(path)
+            return nil if path.nil? || path.empty?
+
+            path_str = path.to_s
+
+            # Check for protocol URIs first
+            if self.class.protocol?(path_str)
+              return resolve_protocol(path_str)
+            end
+
+            # Expand environment variables
+            expanded = expand_env_vars(path_str)
+
+            # Handle absolute paths
+            return File.expand_path(expanded) if Pathname.new(expanded).absolute?
+
+            # Handle source-relative paths (./ or ../)
+            if expanded.start_with?("./", "../")
+              return File.expand_path(expanded, @source_dir)
+            end
+
+            # Default: project-relative paths
+            File.expand_path(expanded, @project_root)
+          end
+
+          # === Class Methods (Utilities and Backward Compatibility) ===
+
+          # Check if path is a protocol URI
+          #
+          # @param path [String] Path to check
+          # @return [Boolean] true if protocol format detected
+          def self.protocol?(path)
+            return false if path.nil? || path.empty?
+
+            !!(path.to_s =~ PROTOCOL_PATTERN)
+          end
+
+          # Register a protocol resolver (e.g., ace-nav)
+          # Thread-safe registration using mutex.
+          #
+          # @param resolver [Object] Resolver responding to #resolve(uri)
+          def self.register_protocol_resolver(resolver)
+            protocol_resolver_mutex.synchronize do
+              @protocol_resolver = resolver
+            end
+          end
+
+          # Get the current protocol resolver (thread-safe)
+          # @return [Object, nil] Current resolver or nil
+          def self.protocol_resolver
+            protocol_resolver_mutex.synchronize do
+              @protocol_resolver
+            end
+          end
+
+          # Reset protocol resolver (for testing)
+          # @api private
+          def self.reset_protocol_resolver!
+            protocol_resolver_mutex.synchronize do
+              @protocol_resolver = nil
+            end
+          end
+
+          # Expand path with tilde and environment variables
+          # Legacy stateless method for backward compatibility
+          #
+          # @param path [String] Path to expand
+          # @return [String] Expanded absolute path
+          def self.expand(path)
+            return nil if path.nil?
+
+            expanded = path.to_s.dup
+
+            # Expand environment variables (uses class_get_env for testability)
+            expanded.gsub!(/\$([A-Z_][A-Z0-9_]*)/i) do |match|
+              class_get_env(match[1..-1]) || match
+            end
+
+            # Expand tilde
+            File.expand_path(expanded)
+          end
+
+          # Access environment variable by name (class-level)
+          # Extracted to allow test stubbing without modifying global ENV
+          #
+          # @param var_name [String] Environment variable name
+          # @return [String, nil] Environment variable value or nil if not set
+          def self.class_get_env(var_name)
+            ENV[var_name]
+          end
+
+          # Join path components safely
+          #
+          # @param parts [Array<String>] Path parts to join
+          # @return [String] Joined path
+          def self.join(*parts)
+            parts = parts.flatten.compact.map(&:to_s)
+            return "" if parts.empty?
+
+            File.join(*parts)
+          end
+
+          # Get directory name from path
+          #
+          # @param path [String] File path
+          # @return [String] Directory path
+          def self.dirname(path)
+            return nil if path.nil?
+
+            File.dirname(path.to_s)
+          end
+
+          # Get base name from path
+          #
+          # @param path [String] File path
+          # @return [String] Base name
+          def self.basename(path, suffix = nil)
+            return nil if path.nil?
+
+            if suffix
+              File.basename(path.to_s, suffix)
+            else
+              File.basename(path.to_s)
+            end
+          end
+
+          # Check if path is absolute
+          #
+          # @param path [String] Path to check
+          # @return [Boolean] true if absolute path
+          def self.absolute?(path)
+            return false if path.nil?
+
+            path_str = path.to_s
+            Pathname.new(path_str).absolute?
+          end
+
+          # Make path relative to base
+          #
+          # @param path [String] Path to make relative
+          # @param base [String] Base path
+          # @return [String] Relative path
+          def self.relative(path, base)
+            return nil if path.nil? || base.nil?
+
+            path_obj = Pathname.new(expand(path))
+            base_obj = Pathname.new(expand(base))
+
+            path_obj.relative_path_from(base_obj).to_s
+          rescue ArgumentError
+            # Paths are on different drives or one is relative
+            path
+          end
+
+          # Normalize path (remove .., ., duplicates slashes)
+          #
+          # @param path [String] Path to normalize
+          # @return [String] Normalized path
+          def self.normalize(path)
+            return nil if path.nil?
+
+            Pathname.new(path.to_s).cleanpath.to_s
+          end
+
+          protected
+
+          # Access environment variable by name
+          # Extracted to allow test stubbing without modifying global ENV
+          #
+          # @param var_name [String] Environment variable name
+          # @return [String, nil] Environment variable value or nil if not set
+          def get_env(var_name)
+            ENV[var_name]
+          end
+
+          private
+
+          # Resolve protocol URI
+          # @raise [PathError] if no protocol resolver is registered
+          def resolve_protocol(uri)
+            resolver = self.class.protocol_resolver
+            if resolver && resolver.respond_to?(:resolve)
+              result = resolver.resolve(uri)
+              # If resolver returns a Resource with path, extract it
+              return result.path if result.respond_to?(:path)
+              # Otherwise return the result as-is
+              return result
+            end
+
+            # No resolver registered - raise exception for consistent error handling
+            raise PathError,
+              "Protocol '#{uri}' could not be resolved. " \
+              "Register a protocol resolver with PathExpander.register_protocol_resolver(resolver)"
+          end
+
+          # Expand environment variables in path
+          #
+          # @note If an environment variable is not set, the original reference
+          #   (e.g., "$VAR" or "${VAR}") is preserved in the output. This allows
+          #   deferred resolution or detection of missing variables by the caller.
+          #   Callers should validate paths if undefined variables are unacceptable.
+          #
+          # @param path [String] Path containing environment variable references
+          # @return [String] Path with environment variables expanded
+          def expand_env_vars(path)
+            expanded = path.dup
+
+            # Handle ${VAR} format
+            expanded.gsub!(/\$\{([A-Z_][A-Z0-9_]*)\}/i) do |match|
+              var_name = match[2..-2] # Remove ${ and }
+              get_env(var_name) || match
+            end
+
+            # Handle $VAR format
+            expanded.gsub!(/\$([A-Z_][A-Z0-9_]*)/i) do |match|
+              get_env(match[1..-1]) || match
+            end
+
+            expanded
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/fs/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Fs
+      # Base error class for all ace-support-fs errors
+      class Error < StandardError; end
+
+      # Raised when a path cannot be resolved
+      class PathError < Error; end
+    end
+  end
+end

data/lib/ace/support/fs/molecules/directory_traverser.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/path_expander"
+
+module Ace
+  module Support
+    module Fs
+      module Molecules
+        # Traverses directory tree to find configuration directories
+        class DirectoryTraverser
+          attr_reader :config_dir
+
+          # Initialize traverser
+          # @param config_dir [String] Name of config directory to find (default: ".ace")
+          # @param start_path [String] Path to start traversal from
+          def initialize(config_dir: ".ace", start_path: nil)
+            @config_dir = config_dir
+            @start_path = start_path ? Atoms::PathExpander.expand(start_path) : Dir.pwd
+          end
+
+          # Traverse from current directory up to project root or filesystem root
+          # @return [Array<String>] Ordered list of directories containing config folders
+          def traverse
+            directories = []
+            current_path = @start_path
+            visited = Set.new
+
+            # Find project root
+            project_root = ProjectRootFinder.find(start_path: @start_path)
+
+            # Traverse up from current directory
+            loop do
+              # Avoid infinite loops
+              break if visited.include?(current_path)
+              visited.add(current_path)
+
+              # Check if config directory exists at this level
+              config_path = File.join(current_path, @config_dir)
+              directories << current_path if Dir.exist?(config_path)
+
+              # Get parent directory
+              parent = File.dirname(current_path)
+
+              # Stop if we've reached filesystem root
+              break if parent == current_path
+
+              # Stop if we've gone past project root (if it exists)
+              # We check after adding current_path to allow project root itself
+              if project_root && current_path == project_root
+                # Already processed project root, can stop
+                break
+              end
+
+              current_path = parent
+            end
+
+            directories
+          end
+
+          # Find all config directories in the traversal path
+          # @return [Array<String>] Full paths to config directories
+          def find_config_directories
+            traverse.map { |dir| File.join(dir, @config_dir) }
+          end
+
+          # Get the directory hierarchy from current to root
+          # @return [Array<String>] All directories from current to project/filesystem root
+          def directory_hierarchy
+            hierarchy = []
+            current_path = @start_path
+
+            # Find project root
+            project_root = ProjectRootFinder.find(start_path: @start_path)
+            stop_at = project_root || "/"
+
+            loop do
+              hierarchy << current_path
+
+              # Stop if we've reached our stopping point
+              break if current_path == stop_at
+
+              # Get parent directory
+              parent = File.dirname(current_path)
+
+              # Stop if we've reached filesystem root
+              break if parent == current_path
+
+              current_path = parent
+            end
+
+            hierarchy
+          end
+
+          # Build cascade paths with priorities
+          # @return [Hash<String, Integer>] Map of directory paths to priorities
+          def build_cascade_priorities
+            priorities = {}
+            directories = find_config_directories
+
+            # Assign priorities - closer to cwd = higher priority (lower number)
+            directories.each_with_index do |dir, index|
+              priorities[dir] = index * 10
+            end
+
+            # Add home directory with lower priority
+            home_config = File.expand_path("~/#{@config_dir}")
+            if Dir.exist?(home_config) && !priorities.key?(home_config)
+              priorities[home_config] = (directories.length + 1) * 10
+            end
+
+            priorities
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/fs/molecules/project_root_finder.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../atoms/path_expander"
+
+module Ace
+  module Support
+    module Fs
+      module Molecules
+        # Find project root directory based on markers
+        class ProjectRootFinder
+          # Common project root markers in order of preference
+          DEFAULT_MARKERS = %w[
+            .git
+            Gemfile
+            package.json
+            Cargo.toml
+            pyproject.toml
+            go.mod
+            .hg
+            .svn
+            Rakefile
+            Makefile
+          ].freeze
+
+          # Thread-safe cache for project root detection
+          @cache = {}
+          @cache_mutex = Mutex.new
+
+          class << self
+            attr_reader :cache_mutex
+
+            def cache
+              @cache ||= {}
+            end
+          end
+
+          # Initialize finder with optional custom markers
+          # @param markers [Array<String>] Project root markers to look for
+          # @param start_path [String] Path to start searching from (default: current directory)
+          # @raise [ArgumentError] if markers is nil or empty
+          def initialize(markers: DEFAULT_MARKERS, start_path: nil)
+            if markers.nil? || markers.empty?
+              raise ArgumentError, "markers cannot be nil or empty"
+            end
+            @markers = markers
+            @start_path = start_path ? Atoms::PathExpander.expand(start_path) : Dir.pwd
+          end
+
+          # Find project root directory with caching
+          # @return [String, nil] Project root path or nil if not found
+          def find
+            # Check environment variable first
+            project_root_env = env_project_root
+            if project_root_env && !project_root_env.empty?
+              project_root = Atoms::PathExpander.expand(project_root_env)
+              if Dir.exist?(project_root) && path_within_root?(@start_path, project_root)
+                return project_root
+              end
+            end
+
+            cache_key = "#{@start_path}:#{@markers.join(",")}"
+
+            # Thread-safe cache access
+            self.class.cache_mutex.synchronize do
+              # Return cached result if available
+              return self.class.cache[cache_key] if self.class.cache.key?(cache_key)
+
+              # Find and cache the result
+              result = find_without_cache
+              self.class.cache[cache_key] = result
+              result
+            end
+          end
+
+          # Find project root or fall back to current directory
+          # @return [String] Project root path or current directory
+          def find_or_current
+            find || Dir.pwd
+          end
+
+          # Check if we're in a project directory
+          # @return [Boolean] true if project root is found
+          def in_project?
+            !find.nil?
+          end
+
+          # Get the relative path from project root to a given path
+          # @param path [String] Path to make relative
+          # @return [String, nil] Relative path or nil if not in project
+          def relative_path(path)
+            root = find
+            return nil unless root
+
+            # Use realpath to handle symlinks and resolve paths
+            real_root = File.realpath(root)
+            real_path = File.realpath(Atoms::PathExpander.expand(path))
+
+            return nil unless real_path.start_with?(real_root)
+
+            Pathname.new(real_path).relative_path_from(Pathname.new(real_root)).to_s
+          end
+
+          # Clear the cache (thread-safe)
+          def self.clear_cache!
+            cache_mutex.synchronize do
+              cache.clear
+            end
+          end
+
+          # Class method for convenience
+          # @return [String, nil] Project root path
+          def self.find(start_path: nil, markers: DEFAULT_MARKERS)
+            new(start_path: start_path, markers: markers).find
+          end
+
+          # Class method to find or use current directory
+          # @return [String] Project root path or current directory
+          def self.find_or_current(start_path: nil, markers: DEFAULT_MARKERS)
+            new(start_path: start_path, markers: markers).find_or_current
+          end
+
+          protected
+
+          # Access PROJECT_ROOT_PATH environment variable
+          # Extracted to allow test stubbing without modifying global ENV
+          def env_project_root
+            ENV["PROJECT_ROOT_PATH"]
+          end
+
+          private
+
+          # Find project root without using cache
+          # @return [String, nil] Project root path or nil if not found
+          def find_without_cache
+            path = @start_path
+
+            # Traverse up the directory tree
+            loop do
+              # Check for any marker in current directory
+              @markers.each do |marker|
+                marker_path = File.join(path, marker)
+                return path if File.exist?(marker_path)
+              end
+
+              # Get parent directory
+              parent = File.dirname(path)
+
+              # Stop if we've reached the filesystem root
+              break if parent == path
+
+              path = parent
+            end
+
+            nil
+          end
+
+          def path_within_root?(candidate_path, root_path)
+            candidate = File.expand_path(candidate_path)
+            root = File.expand_path(root_path)
+            candidate == root || candidate.start_with?("#{root}/")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/fs/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Fs
+      VERSION = "0.3.0"
+    end
+  end
+end

data/lib/ace/support/fs.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "fs/version"
+require_relative "fs/errors"
+require_relative "fs/atoms/path_expander"
+require_relative "fs/molecules/project_root_finder"
+require_relative "fs/molecules/directory_traverser"
+
+module Ace
+  module Support
+    # Filesystem utilities for ace-* gems
+    #
+    # Provides unified path expansion, project root detection, and directory traversal
+    # functionality extracted from ace-support-core and ace-config.
+    #
+    # Components:
+    # - Atoms::PathExpander - Path expansion with protocol, env var, and relative path support
+    # - Molecules::ProjectRootFinder - Project root detection based on marker files
+    # - Molecules::DirectoryTraverser - Config directory discovery in directory hierarchy
+    module Fs
+    end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: ace-support-fs
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Infrastructure gem providing unified path expansion, project root detection,
+  and directory traversal functionality for ace-* gems. Library-only gem following
+  ace-support-* pattern for shared filesystem operations.
+email:
+- mc@cs3b.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/ace/support/fs.rb
+- lib/ace/support/fs/atoms/path_expander.rb
+- lib/ace/support/fs/errors.rb
+- lib/ace/support/fs/molecules/directory_traverser.rb
+- lib/ace/support/fs/molecules/project_root_finder.rb
+- lib/ace/support/fs/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/cs3b/ace
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-support-fs/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-support-fs/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Filesystem utilities for ace-* gems
+test_files: []