ace-support-nav 0.25.0

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "../molecules/config_loader"
+
+module Ace
+  module Support
+    module Nav
+      module Organisms
+        # Handles command delegation for cmd-type protocols
+        # Executes external commands based on protocol configuration templates
+        class CommandDelegator
+          def initialize(config_loader: nil)
+            @config_loader = config_loader || Molecules::ConfigLoader.new
+          end
+
+          # Delegate a URI to an external command
+          # @param uri_string [String] The URI to delegate (e.g., "task://083")
+          # @param options [Hash] Options from CLI (e.g., {path: true, content: true})
+          # @return [Integer] Exit code from the delegated command
+          def delegate(uri_string, options = {})
+            # Parse the URI to extract protocol and reference
+            protocol, reference = parse_uri(uri_string)
+
+            # Load protocol configuration
+            protocol_config = @config_loader.load_protocol_config(protocol)
+
+            # Verify this is a cmd-type protocol
+            unless protocol_config["type"] == "cmd"
+              raise ArgumentError, "Protocol #{protocol} is not a cmd-type protocol"
+            end
+
+            # Get command template
+            command_template = protocol_config["command_template"]
+            unless command_template
+              raise ArgumentError, "Protocol #{protocol} missing command_template"
+            end
+
+            # Build the command
+            command_parts = build_command(command_template, reference, options, protocol_config)
+
+            # Execute the command
+            execute_command(command_parts)
+          end
+
+          private
+
+          # Parse a URI into protocol and reference
+          # @param uri_string [String] URI like "task://083" or "task://v.0.9.0+task.083"
+          # @return [Array<String, String>] [protocol, reference]
+          def parse_uri(uri_string)
+            unless uri_string.include?("://")
+              raise ArgumentError, "Invalid URI format: #{uri_string}"
+            end
+
+            parts = uri_string.split("://", 2)
+            protocol = parts[0]
+            reference = parts[1] || ""
+
+            [protocol, reference]
+          end
+
+          # Build command array from template and options
+          # @param template [String] Command template with %{ref} placeholder
+          # @param reference [String] The resource reference to substitute
+          # @param options [Hash] CLI options to pass through
+          # @param protocol_config [Hash] Protocol configuration
+          # @return [Array<String>] Command parts as array for safe execution
+          #
+          # @note Template parsing uses Shellwords.split() for robust parsing of command
+          #   templates, properly handling quoted strings and complex argument patterns.
+          def build_command(template, reference, options, protocol_config)
+            # Substitute reference in template
+            command_string = template.gsub("%{ref}", reference)
+
+            # Parse command using Shellwords for robust handling of quotes and spaces
+            command_parts = Shellwords.split(command_string)
+
+            # Add pass-through options
+            pass_through_options = protocol_config["pass_through_options"] || []
+
+            options.each do |key, value|
+              option_flag = "--#{key.to_s.tr("_", "-")}"
+
+              # Only add if it's in pass_through list or if we don't have a list
+              if pass_through_options.empty? || pass_through_options.include?(option_flag)
+                if value == true
+                  command_parts << option_flag
+                elsif value.is_a?(String)
+                  command_parts << option_flag
+                  command_parts << value
+                end
+              end
+            end
+
+            command_parts
+          end
+
+          # Execute command using system and return exit code
+          # @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)
+            # Use system with array argument for safety (no shell interpolation)
+            success = system(*command_parts)
+
+            # Return exit code
+            if success.nil?
+              # Command not found
+              warn "Error: Command not found: #{command_parts[0]}"
+              warn "Please install the required gem or ensure it's in your PATH"
+              1
+            elsif success
+              0
+            else
+              $?.exitstatus || 1
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/protocol_scanner"
+require_relative "../molecules/resource_resolver"
+require_relative "../atoms/path_normalizer"
+
+module Ace
+  module Support
+    module Nav
+      module Organisms
+        # Orchestrates navigation operations
+        class NavigationEngine
+          def initialize(handbook_scanner: nil, protocol_scanner: nil, resource_resolver: nil, path_normalizer: nil)
+            # Support legacy handbook_scanner parameter
+            @protocol_scanner = protocol_scanner || handbook_scanner || Molecules::ProtocolScanner.new
+            @resource_resolver = resource_resolver || Molecules::ResourceResolver.new(protocol_scanner: @protocol_scanner)
+            @path_normalizer = path_normalizer || Atoms::PathNormalizer.new
+          end
+
+          # Resolve a single resource URI to a path
+          def resolve(uri_string, options = {})
+            resource = @resource_resolver.resolve(uri_string)
+            return nil unless resource
+
+            if options[:content]
+              resource.content
+            elsif options[:verbose]
+              resource.to_h
+            else
+              resource.path
+            end
+          end
+
+          # List resources matching a pattern
+          def list(uri_pattern, options = {})
+            resources = @resource_resolver.resolve_pattern(uri_pattern)
+
+            if options[:tree]
+              format_as_tree(resources)
+            elsif options[:verbose]
+              resources.map(&:to_h)
+            else
+              format_as_list(resources)
+            end
+          end
+
+          # Create a new resource from a template
+          def create(uri_string, target_path = nil)
+            # Resolve the template
+            template = @resource_resolver.resolve(uri_string)
+            return {error: "Template not found: #{uri_string}"} unless template
+
+            # Determine target path
+            target = determine_target_path(template, target_path)
+            return {error: "Could not determine target path"} unless target
+
+            # Create directory if needed
+            target_dir = File.dirname(target)
+            FileUtils.mkdir_p(target_dir) unless Dir.exist?(target_dir)
+
+            # Copy template content
+            if template.content
+              File.write(target, template.content)
+              {created: target, from: template.path}
+            else
+              {error: "Template has no content: #{template.path}"}
+            end
+          end
+
+          # Show available sources
+          def sources(options = {})
+            all_sources = @protocol_scanner.scan_all_sources
+
+            if options[:verbose]
+              all_sources.map(&:to_h)
+            else
+              all_sources.map { |s| "#{s.alias_name} (#{s.type}): #{s.path}" }
+            end
+          end
+
+          # Get all discovered protocols
+          def discovered_protocols
+            config_loader.discovered_protocols
+          end
+
+          # Check if a protocol is cmd-type (command delegation)
+          # @param protocol_name [String] The protocol name to check
+          # @return [Boolean] true if protocol delegates to external command
+          def cmd_protocol?(protocol_name)
+            config_loader.protocol_type(protocol_name) == "cmd"
+          end
+
+          # Resolve a cmd-type protocol URI by running its command and capturing stdout
+          # Used by tools that need to programmatically obtain the resolved path
+          # @param uri_string [String] e.g., "task://8c0.t.05p"
+          # @return [String, nil] captured stdout (path), or nil on failure
+          def resolve_cmd_to_path(uri_string)
+            protocol, reference = uri_string.split("://", 2)
+            return nil unless cmd_protocol?(protocol)
+
+            protocol_config = config_loader.load_protocol_config(protocol)
+            command_template = protocol_config["command_template"]
+            return nil unless command_template
+
+            require "open3"
+            require "shellwords"
+            require "timeout"
+            args = Shellwords.split(command_template.gsub("%{ref}", Shellwords.escape(reference)))
+            stdout, status = Timeout.timeout(10) { Open3.capture2(*args) }
+            return nil unless status.success?
+
+            result = stdout.strip
+            result.empty? ? nil : result
+          rescue Timeout::Error
+            warn "Warning: cmd protocol timed out for '#{uri_string}'"
+            nil
+          end
+
+          private
+
+          def format_as_list(resources)
+            resources.map do |resource|
+              "#{resource.uri} → #{resource.path} (#{resource.source.alias_name})"
+            end
+          end
+
+          def format_as_tree(resources)
+            # Group by source
+            by_source = resources.group_by { |r| r.source.alias_name }
+
+            tree = []
+            by_source.each do |source_alias, source_resources|
+              tree << "#{source_alias}/"
+
+              # Group by protocol
+              by_protocol = source_resources.group_by(&:protocol)
+              by_protocol.each do |protocol, protocol_resources|
+                tree << "  #{protocol}://"
+
+                # Sort and display resources
+                protocol_resources.sort_by(&:resource_path).each do |resource|
+                  tree << "    #{resource.resource_path}"
+                end
+              end
+            end
+
+            tree
+          end
+
+          def determine_target_path(template, target_path)
+            # If explicit target provided, use it
+            return @path_normalizer.normalize(target_path) if target_path
+
+            # Otherwise, create in project .ace-handbook
+            project_handbook = File.expand_path("./.ace-handbook")
+
+            # Determine subdirectory based on protocol
+            subdir = case template.protocol
+            when "wfi" then "workflow-instructions"
+            when "tmpl" then "templates"
+            when "guide" then "guides"
+            when "sample" then "samples"
+            else template.protocol
+            end
+
+            # Build target path
+            filename = File.basename(template.path)
+            File.join(project_handbook, subdir, filename)
+          end
+
+          # Access the config_loader from protocol_scanner
+          # Reuses the same ConfigLoader instance across all protocol operations
+          def config_loader
+            @protocol_scanner.config_loader
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/ace/support/nav.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "nav/version"
+require "ace/support/config"
+
+# Load all ace-support-nav components
+require_relative "nav/cli"
+require_relative "nav/atoms/gem_resolver"
+require_relative "nav/atoms/path_normalizer"
+require_relative "nav/atoms/uri_parser"
+require_relative "nav/molecules/config_loader"
+require_relative "nav/molecules/handbook_scanner"
+require_relative "nav/molecules/protocol_scanner"
+require_relative "nav/molecules/resource_resolver"
+require_relative "nav/molecules/source_registry"
+require_relative "nav/organisms/navigation_engine"
+require_relative "nav/organisms/command_delegator"
+require_relative "nav/models/handbook_source"
+require_relative "nav/models/protocol_source"
+require_relative "nav/models/resource"
+require_relative "nav/models/resource_uri"
+
+module Ace
+  module Support
+    module Nav
+      class Error < StandardError; end
+
+      # Initialize mutex for thread-safe config access
+      @config_mutex = Mutex.new
+
+      # Returns the gem root directory
+      # Used by command files to locate .ace-defaults/ configuration
+      # Centralizes the path calculation to avoid duplication across commands
+      # @return [String] Path to the gem root directory
+      def self.gem_root
+        @gem_root ||= Gem.loaded_specs["ace-support-nav"]&.gem_dir ||
+          File.expand_path("../../..", __dir__)
+      end
+
+      # Check if debug mode is enabled
+      # @return [Boolean] True if debug mode is enabled
+      def self.debug?
+        ENV["ACE_DEBUG"] == "1" || ENV["DEBUG"] == "1"
+      end
+
+      # Load ace-support-nav configuration using ace-config cascade
+      # Follows ADR-022: Configuration Default and Override Pattern
+      # Uses Ace::Support::Config.create() for configuration cascade resolution
+      # Thread-safe: uses mutex for initialization
+      # @return [Hash] Configuration hash with defaults merged
+      def self.config
+        # Fast path: return cached config if already initialized
+        return @config if defined?(@config) && @config
+
+        # Thread-safe initialization
+        @config_mutex.synchronize do
+          @config ||= load_config
+        end
+      end
+
+      # Reset config cache (useful for testing)
+      # Thread-safe: uses mutex to prevent race conditions
+      def self.reset_config!
+        @config_mutex.synchronize do
+          @config = nil
+        end
+      end
+
+      # Load configuration using Ace::Support::Config cascade
+      # @return [Hash] Merged configuration
+      def self.load_config
+        resolver = Ace::Support::Config.create(
+          config_dir: ".ace",
+          defaults_dir: ".ace-defaults",
+          gem_path: gem_root
+        )
+
+        # Resolve config for nav namespace
+        config = resolver.resolve_namespace("nav")
+        config.data
+      rescue => e
+        warn "ace-support-nav: Could not load config: #{e.class} - #{e.message}" if debug?
+        # Fall back to gem defaults instead of empty hash to prevent silent config erasure
+        load_gem_defaults_fallback
+      end
+      private_class_method :load_config
+
+      # Load gem defaults directly as fallback when cascade resolution fails
+      # This ensures configuration is never silently erased due to YAML errors
+      # or user config issues
+      # @return [Hash] Defaults hash or empty hash if defaults also fail
+      def self.load_gem_defaults_fallback
+        defaults_path = File.join(gem_root, ".ace-defaults", "nav", "config.yml")
+
+        return {} unless File.exist?(defaults_path)
+
+        YAML.safe_load_file(defaults_path, permitted_classes: [Date], aliases: true) || {}
+      rescue
+        {} # Only return empty hash if even defaults fail to load
+      end
+      private_class_method :load_gem_defaults_fallback
+    end
+  end
+end

metadata

@@ -0,0 +1,228 @@
+--- !ruby/object:Gem::Specification
+name: ace-support-nav
+version: !ruby/object:Gem::Version
+  version: 0.25.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-support-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: ace-support-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+- !ruby/object:Gem::Dependency
+  name: ace-support-config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: ace-support-fs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: ace-support-test-helpers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: ace-support-nav provides unified navigation and path resolution across
+  the ACE ecosystem. It automatically discovers handbooks bundled within ace-* gems,
+  resolves resource URIs to actual file paths, and supports a multi-level override
+  cascade.
+email:
+- mc@cs3b.com
+executables:
+- ace-nav
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ace-defaults/nav/config.yml"
+- ".ace-defaults/nav/protocols/guide-sources/ace-support-nav.yml"
+- ".ace-defaults/nav/protocols/guide.yml"
+- ".ace-defaults/nav/protocols/prompt.yml"
+- ".ace-defaults/nav/protocols/skill-sources/ace-support-nav.yml"
+- ".ace-defaults/nav/protocols/skill.yml"
+- ".ace-defaults/nav/protocols/tmpl-sources/ace-support-nav.yml"
+- ".ace-defaults/nav/protocols/tmpl.yml"
+- ".ace-defaults/nav/protocols/wfi-sources/ace-support-nav.yml"
+- ".ace-defaults/nav/protocols/wfi.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- docs/demo/ace-support-nav-getting-started.gif
+- docs/demo/ace-support-nav-getting-started.tape.yml
+- exe/ace-nav
+- handbook/workflow-instructions/test.wfi.md
+- lib/ace/support/nav.rb
+- lib/ace/support/nav/atoms/extension_inferrer.rb
+- lib/ace/support/nav/atoms/gem_resolver.rb
+- lib/ace/support/nav/atoms/path_normalizer.rb
+- lib/ace/support/nav/atoms/uri_parser.rb
+- lib/ace/support/nav/cli.rb
+- lib/ace/support/nav/cli/commands/create.rb
+- lib/ace/support/nav/cli/commands/list.rb
+- lib/ace/support/nav/cli/commands/resolve.rb
+- lib/ace/support/nav/cli/commands/sources.rb
+- lib/ace/support/nav/models/handbook_source.rb
+- lib/ace/support/nav/models/protocol_source.rb
+- lib/ace/support/nav/models/resource.rb
+- lib/ace/support/nav/models/resource_uri.rb
+- lib/ace/support/nav/molecules/config_loader.rb
+- lib/ace/support/nav/molecules/handbook_scanner.rb
+- lib/ace/support/nav/molecules/protocol_scanner.rb
+- lib/ace/support/nav/molecules/resource_resolver.rb
+- lib/ace/support/nav/molecules/source_registry.rb
+- lib/ace/support/nav/organisms/command_delegator.rb
+- lib/ace/support/nav/organisms/navigation_engine.rb
+- lib/ace/support/nav/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-nav/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-support-nav/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: Unified navigation and resource discovery for ACE ecosystem
+test_files: []