ace-support-nav 0.28.6 → 0.28.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1948cb2b1085585f1a3ccd40d9fddd0dd130bad2ede2991bb7922ee3dba68143
-  data.tar.gz: 4d822e1cb78a2b43fe641d1a963cc68df74b97cda80004ce87a7520851793cef
+  metadata.gz: 360819ca45c3cd71302707c5bc82a4a6dc6cf867d02ca96796ba04c24ddc4f45
+  data.tar.gz: 35feb7c2fb3c43a357fe25f9aab9ec3577d853ed4ea8224cfc4fbd09a3c69a6f
 SHA512:
-  metadata.gz: 98e6c2d42e54a1b6f272689238ffe9371256446127e22c26120489043e850b036d8438164b3fd4b64caa871391caddda8b6d2fb87222e6a485a6c02e8479902e
-  data.tar.gz: 0b937920845694bf9268b5591793e8f73d51a01fe5f1590fdd26c1e62d5c2437e869a951f012bf37f0ff8bda2a780cf6ef74084d2d07435089affa0df496776f
+  metadata.gz: 3657cb2a716864179ba9f342d4cc005aa5fc6838a08a831b710a8cc8280fb405d7bc51f413c8485825d87b4462d3e05385cd70c9a82d1e390d9206fe1b9f1133
+  data.tar.gz: 1d7e62975dcc3d28e0f4a5e765909a892d9b391a5fed1858425389faf82a393cebe698940e6fa8d48bb8f1b0b915eb62e4b14d99ac5f23aed2de323c3be5c380

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.8] - 2026-10-20
+
+### Fixed
+- Honor `ACE_TOOLCHAIN=installed` for published-gem execution and context propagation without source-runtime fallback; retain default auto development behavior.
+
+## [0.28.7] - 2026-09-27
+
+### Technical
+- Resolve temporary test paths through symlinks.
+
+### Added
+- `ace-nav resolve <uri> --why` prints every duplicate candidate in resolution order with its source, priority, and origin, marks the winner, and states the source-priority rule, making override precedence observable without planting probe files.
+
 
 ## [0.28.6] - 2026-09-02
 

data/exe/ace-nav

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
+require "bundler/setup" unless ENV["ACE_TOOLCHAIN"] == "installed"
 require "ace/support/nav"
 require "ace/support/cli"
 

data/lib/ace/support/nav/cli/commands/resolve.rb

@@ -39,6 +39,9 @@ module Ace
                 # Display content
                 $ ace-nav resolve wfi://setup --content
 
+                # Explain precedence: all candidates + the rule that picked the winner
+                $ ace-nav resolve wfi://setup --why
+
                 # Wildcard patterns auto-route to list
                 $ ace-nav resolve wfi://*
 
@@ -57,6 +60,8 @@ module Ace
 
                 By default, displays resolved path
                 Use --content to display resource content
+                Use --why to print all candidates in resolution order plus the
+                rule that picked the winner (useful when duplicates exist)
                 Exit codes: 0 (success), 1 (error)
             DESC
 
@@ -71,6 +76,7 @@ module Ace
 
             option :path, type: :boolean, desc: "Display resource path"
             option :content, type: :boolean, desc: "Display resource content"
+            option :why, type: :boolean, desc: "Explain precedence: print all candidates in resolution order and the winner"
             option :tree, type: :boolean, desc: "Display resources in tree format (passed through to cmd protocols)"
             option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
             option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
@@ -103,11 +109,18 @@ module Ace
               if @uri.include?("://")
                 protocol = @uri.split("://").first
                 if @engine.cmd_protocol?(protocol)
+                  if @options[:why]
+                    raise Ace::Support::Cli::Error.new("--why is not available for cmd protocols (#{protocol} delegates to an external command; there are no local candidates)")
+                  end
                   delegator = Organisms::CommandDelegator.new
                   return delegator.delegate(@uri, @options)
                 end
               end
 
+              if @options[:why]
+                return print_explanation(@engine.explain(@uri))
+              end
+
               result = @engine.resolve(@uri, content: @options[:content], verbose: @options[:verbose])
 
               if result.nil?
@@ -127,6 +140,28 @@ module Ace
 
             private
 
+            # Print a precedence explanation produced by NavigationEngine#explain
+            def print_explanation(explanation)
+              if explanation[:candidates].empty?
+                raise Ace::Support::Cli::Error.new("Resource not found: #{@uri}")
+              end
+
+              if @options[:verbose]
+                require "json"
+                puts JSON.pretty_generate(explanation)
+                return
+              end
+
+              puts "uri: #{explanation[:uri]}"
+              puts "rule: #{explanation[:rule]}"
+              puts "candidates (resolution order):"
+              explanation[:candidates].each do |candidate|
+                origin = candidate[:origin] || candidate[:source_type]
+                puts "  #{candidate[:position]}. [priority #{candidate[:priority]}] #{candidate[:source]} (#{origin}) → #{candidate[:path]}"
+                puts "     ← winner" if candidate[:winner]
+              end
+            end
+
             # Normalize bare protocol names (e.g., "wfi") to protocol:// format
             # This allows users to type "ace-nav wfi" instead of "ace-nav wfi://"
             def normalize_protocol_shorthand(uri)

data/lib/ace/support/nav/models/protocol_source.rb

@@ -33,8 +33,19 @@ module Ace
 
                 # Get relative path from config, or use default
                 relative = @config&.dig("relative_path") || "handbook/workflow-instructions"
+                return File.join(gem_dir, relative) unless Ace::Support::Cli::Toolchain.installed?
 
-                File.join(gem_dir, relative)
+                candidate = File.expand_path(relative, gem_dir)
+                if Ace::Support::Cli::Toolchain.installed?
+                  unless Ace::Support::Cli::Toolchain.installed_spec?(spec) &&
+                      candidate.start_with?("#{File.expand_path(gem_dir)}/")
+                    raise Ace::Support::Cli::Toolchain::Error, "generic document source is outside installed gem #{@name}"
+                  end
+                  if File.exist?(candidate) && !File.realpath(candidate).start_with?("#{File.realpath(gem_dir)}/")
+                    raise Ace::Support::Cli::Toolchain::Error, "generic document source escapes installed gem #{@name}"
+                  end
+                end
+                candidate
               rescue Gem::LoadError => e
                 # Gem not found, return a placeholder path
                 warn "Gem '#{@name}' not found: #{e.message}" if ENV["VERBOSE"]

data/lib/ace/support/nav/molecules/config_loader.rb

@@ -89,6 +89,8 @@ module Ace
               @protocols[key] = protocol_data if key
             end
 
+            return @protocols if Ace::Support::Cli::Toolchain.installed?
+
             # 1. Load from user ~/.ace/nav/protocols/
             load_directory_protocols(File.expand_path("~/.ace/nav/protocols")).each do |protocol_data|
               key = protocol_data["protocol"]

data/lib/ace/support/nav/molecules/protocol_scanner.rb

@@ -352,6 +352,8 @@ module Ace
             # Remove @ prefix if present
             name = alias_name.start_with?("@") ? alias_name[1..] : alias_name
 
+            return nil if Ace::Support::Cli::Toolchain.installed? && %w[project local user global].include?(name)
+
             # Handle special aliases
             case name
             when "project", "local"

data/lib/ace/support/nav/molecules/source_registry.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "yaml"
+require "ace/support/cli/toolchain"
 require "date"
 require "pathname"
 require "rubygems"
@@ -36,10 +37,10 @@ module Ace
             sources = []
 
             # Discover from user directory
-            sources.concat(discover_user_sources(protocol))
+            sources.concat(discover_user_sources(protocol)) unless Ace::Support::Cli::Toolchain.installed?
 
             # Discover from project hierarchy
-            sources.concat(discover_project_sources(protocol))
+            sources.concat(discover_project_sources(protocol)) unless Ace::Support::Cli::Toolchain.installed?
 
             # Discover packaged defaults from installed ace-* gems
             sources.concat(discover_gem_default_sources(protocol))
@@ -112,12 +113,13 @@ module Ace
 
             Gem::Specification.each do |spec|
               next unless spec.name.start_with?("ace-")
+              next if Ace::Support::Cli::Toolchain.installed? && !Ace::Support::Cli::Toolchain.installed_spec?(spec)
 
               sources_dir = File.join(spec.gem_dir, sources_dir_suffix)
               next unless Dir.exist?(sources_dir)
 
               Dir.glob(File.join(sources_dir, "*.yml")).each do |source_file|
-                source = load_source_file(source_file, "gem-default")
+                source = load_source_file(source_file, "gem-default", gem_root: spec.gem_dir)
                 sources << source if source
               end
             end
@@ -125,12 +127,19 @@ module Ace
             sources
           end
 
-          def load_source_file(file_path, origin)
+          def load_source_file(file_path, origin, gem_root: nil)
             data = YAML.safe_load_file(file_path, permitted_classes: [Date], aliases: true)
             return nil unless data.is_a?(Hash)
 
             # Expand environment variables in path (only for non-gem types)
             path = (data["type"] == "gem") ? nil : expand_path(data["path"]) if data["path"]
+            if Ace::Support::Cli::Toolchain.installed? && data["type"] != "gem"
+              return nil unless gem_root && data["path"]
+
+              path = File.expand_path(data["path"], gem_root)
+              return nil unless File.directory?(path) &&
+                File.realpath(path).start_with?("#{File.realpath(gem_root)}/")
+            end
 
             # Log warning if path is provided for gem type
             if data["type"] == "gem" && data["path"]

data/lib/ace/support/nav/organisms/command_delegator.rb

@@ -100,8 +100,16 @@ module Ace
           # @param command_parts [Array<String>] Command parts for safe execution
           # @return [Integer] Exit code (0 for success, 1 for failure)
           def execute_command(command_parts)
+            if Ace::Support::Cli::Toolchain.installed?
+              command_parts = command_parts.dup
+              command_parts[0] = Ace::Support::Cli::Toolchain.executable(command_parts.fetch(0))
+            end
             # Use system with array argument for safety (no shell interpolation)
-            success = system(*command_parts)
+            success = if Ace::Support::Cli::Toolchain.installed?
+              system(Ace::Support::Cli::Toolchain.child_environment, *command_parts)
+            else
+              system(*command_parts)
+            end
 
             # Return exit code
             if success.nil?

data/lib/ace/support/nav/organisms/navigation_engine.rb

@@ -17,6 +17,15 @@ module Ace
             @path_normalizer = path_normalizer || Atoms::PathNormalizer.new
           end
 
+          # Resolution rule applied when multiple sources register the same resource.
+          # Sources are ordered by ascending priority (lower number = higher precedence)
+          # and the first source containing the resource wins.
+          RESOLUTION_RULE = "Candidates are tried in ascending source-priority order " \
+            "(lower priority number wins); the first source containing the resource is " \
+            "the winner and remaining duplicates are ignored. Registration defaults: " \
+            "project sources 10, user sources 50, gem defaults 100 - individual source " \
+            "registrations may pin other values.".freeze
+
           # Resolve a single resource URI to a path
           def resolve(uri_string, options = {})
             resource = @resource_resolver.resolve(uri_string)
@@ -31,6 +40,28 @@ module Ace
             end
           end
 
+          # Explain resolution precedence for a URI
+          # Returns every candidate in resolution order plus the rule that picked the winner
+          def explain(uri_string)
+            candidates = @resource_resolver.resolve_pattern(uri_string)
+
+            {
+              uri: uri_string,
+              rule: RESOLUTION_RULE,
+              candidates: candidates.each_with_index.map do |resource, index|
+                {
+                  position: index + 1,
+                  winner: index.zero?,
+                  path: resource.path,
+                  source: resource.source.alias_name,
+                  source_type: resource.source.type.to_s,
+                  priority: resource.source.priority,
+                  origin: resource.source.respond_to?(:origin) ? resource.source.origin : nil
+                }
+              end
+            }
+          end
+
           # List resources matching a pattern
           def list(uri_pattern, options = {})
             resources = @resource_resolver.resolve_pattern(uri_pattern)

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

@@ -3,7 +3,7 @@
 module Ace
   module Support
     module Nav
-      VERSION = "0.28.6"
+      VERSION = "0.28.8"
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-support-nav
 version: !ruby/object:Gem::Version
-  version: 0.28.6
+  version: 0.28.8
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -16,6 +16,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.10
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +26,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.10
 - !ruby/object:Gem::Dependency
   name: ace-support-core
   requirement: !ruby/object:Gem::Requirement