ace-support-nav 0.25.0

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

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../../molecules/config_loader"
+require_relative "../../organisms/navigation_engine"
+require_relative "../../organisms/command_delegator"
+
+module Ace
+  module Support
+    module Nav
+      module CLI
+        module Commands
+          # ace-support-cli Command class for the resolve command
+          class Resolve < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+
+            desc <<~DESC.strip
+              Resolve resource path or content
+
+              SYNTAX:
+                ace-nav resolve [URI] [OPTIONS]
+
+              Automatically detects list mode for wildcards, patterns ending with /,
+              and protocol-only URIs (e.g., wfi://, tmpl://).
+
+              Magic Wildcard Routing:
+                Wildcard patterns are auto-routed to 'list' command:
+                  ace-nav resolve wfi://*              → ace-nav list wfi://*
+                  ace-nav resolve tmpl://@ace-*/*     → ace-nav list tmpl://@ace-*
+                  ace-nav resolve wfi://              → ace-nav list wfi:// (protocol-only)
+                Recognized patterns: *, ?, trailing /, protocol-only
+
+              EXAMPLES:
+
+                # Resolve URI to path
+                $ ace-nav resolve wfi://setup
+
+                # Display content
+                $ ace-nav resolve wfi://setup --content
+
+                # Wildcard patterns auto-route to list
+                $ ace-nav resolve wfi://*
+
+                # Protocol-only URIs auto-route to list
+                $ ace-nav resolve tmpl:///
+
+              CONFIGURATION:
+
+                Global config:  ~/.ace/nav/config.yml
+                Project config: .ace/nav/config.yml
+                Example:        ace-support-nav/.ace-defaults/nav/config.yml
+
+                Sources configured via nav.sources in config
+
+              OUTPUT:
+
+                By default, displays resolved path
+                Use --content to display resource content
+                Exit codes: 0 (success), 1 (error)
+            DESC
+
+            example [
+              "wfi://setup                # Resolve workflow",
+              "wfi://*                    # List workflows (auto-routing)",
+              "tmpl://                    # List templates (auto-routing)",
+              "wfi://setup --content      # Display resource content"
+            ]
+
+            argument :uri, required: true, desc: "Resource URI to resolve"
+
+            option :path, type: :boolean, desc: "Display resource path"
+            option :content, type: :boolean, desc: "Display resource content"
+            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"
+            option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+            def call(uri:, **options)
+              # Normalize bare protocol names to protocol:// format for listing
+              uri = normalize_protocol_shorthand(uri)
+
+              # Handle magic patterns (wildcards → list)
+              if magic_wildcard_pattern?(uri)
+                # Delegate to list command
+                require_relative "list"
+                list_cmd = List.new
+                return list_cmd.call(pattern: uri, **options)
+              end
+
+              # Initialize instance variables for use in private methods
+              @uri = uri
+              @options = options
+              @engine = Organisms::NavigationEngine.new
+
+              execute
+            end
+
+            def execute
+              display_config_summary
+
+              # Check for cmd:// protocol delegation
+              if @uri.include?("://")
+                protocol = @uri.split("://").first
+                if @engine.cmd_protocol?(protocol)
+                  delegator = Organisms::CommandDelegator.new
+                  return delegator.delegate(@uri, @options)
+                end
+              end
+
+              result = @engine.resolve(@uri, content: @options[:content], verbose: @options[:verbose])
+
+              if result.nil?
+                raise Ace::Support::Cli::Error.new("Resource not found: #{@uri}")
+              end
+
+              if @options[:verbose] && result.is_a?(Hash)
+                require "json"
+                puts JSON.pretty_generate(result)
+              elsif @options[:path]
+                # Show path only
+                puts result.is_a?(Hash) ? result[:path] || result : result
+              else
+                puts result
+              end
+            end
+
+            private
+
+            # 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)
+              return uri if uri.include?("://")
+
+              # Check if input is a known protocol name
+              config_loader = Molecules::ConfigLoader.new
+              if config_loader.valid_protocol?(uri)
+                "#{uri}://"
+              else
+                uri
+              end
+            end
+
+            # Check if URI pattern should trigger list mode
+            def magic_wildcard_pattern?(uri)
+              return true if uri.include?("*") || uri.include?("?")
+              return true if uri.match?(%r{/$})
+              return true if uri.match?(/^\w+:\/\/$/)
+              false
+            end
+
+            def display_config_summary
+              return if @options[:quiet]
+
+              require "ace/core"
+              Ace::Core::Atoms::ConfigSummary.display(
+                command: "resolve",
+                config: load_effective_config,
+                defaults: default_config,
+                options: @options,
+                quiet: false
+              )
+            end
+
+            def load_effective_config
+              # Use Ace::Support::Nav.config which already handles the cascade
+              require_relative "../../../nav"
+              Ace::Support::Nav.config
+            end
+
+            def default_config
+              # Use centralized gem_root from Nav module (avoids path depth duplication)
+              defaults_path = File.join(Ace::Support::Nav.gem_root, ".ace-defaults", "nav", "config.yml")
+
+              if File.exist?(defaults_path)
+                require "yaml"
+                YAML.safe_load_file(defaults_path, permitted_classes: [Date], aliases: true) || {}
+              else
+                {}
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../../organisms/navigation_engine"
+
+module Ace
+  module Support
+    module Nav
+      module CLI
+        module Commands
+          # ace-support-cli Command class for the sources command
+          class Sources < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+
+            desc <<~DESC.strip
+              Show available sources
+
+              Show all available sources for resources.
+
+              EXAMPLES:
+
+                # Show all sources
+                $ ace-nav sources
+
+                # Verbose JSON output
+                $ ace-nav sources --verbose
+
+              CONFIGURATION:
+
+                Sources configured in: .ace/nav/config.yml
+                Global config:  ~/.ace/nav/config.yml
+                Project config: .ace/nav/config.yml
+
+              OUTPUT:
+
+                Table format with source details
+                Use --verbose for JSON output
+                Exit codes: 0 (success), 1 (error)
+            DESC
+
+            example [
+              "                          # Show all sources",
+              "--verbose                 # Show detailed information (JSON)"
+            ]
+
+            option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+            option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+            option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+            def call(**options)
+              # Initialize instance variables for use in private methods
+              @options = options
+              @engine = Organisms::NavigationEngine.new
+
+              execute
+            end
+
+            def execute
+              display_config_summary
+
+              sources = @engine.sources(verbose: @options[:verbose])
+
+              if @options[:verbose]
+                require "json"
+                puts JSON.pretty_generate(sources)
+              else
+                puts "Available sources:"
+                sources.each { |source| puts "  #{source}" }
+              end
+
+              0
+            end
+
+            private
+
+            def display_config_summary
+              return if @options[:quiet]
+
+              require "ace/core"
+              Ace::Core::Atoms::ConfigSummary.display(
+                command: "sources",
+                config: load_effective_config,
+                defaults: default_config,
+                options: @options,
+                quiet: false
+              )
+            end
+
+            def load_effective_config
+              # Use Ace::Support::Nav.config which already handles the cascade
+              require_relative "../../../nav"
+              Ace::Support::Nav.config
+            end
+
+            def default_config
+              # Use centralized gem_root from Nav module (avoids path depth duplication)
+              defaults_path = File.join(Ace::Support::Nav.gem_root, ".ace-defaults", "nav", "config.yml")
+
+              if File.exist?(defaults_path)
+                require "yaml"
+                YAML.safe_load_file(defaults_path, permitted_classes: [Date], aliases: true) || {}
+              else
+                {}
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../nav"
+# Commands (Hanami pattern: CLI::Commands::)
+require_relative "cli/commands/resolve"
+require_relative "cli/commands/list"
+require_relative "cli/commands/create"
+require_relative "cli/commands/sources"
+
+module Ace
+  module Support
+    module Nav
+      # ace-support-cli based CLI registry for ace-nav
+      module CLI
+        extend Ace::Support::Cli::RegistryDsl
+
+        PROGRAM_NAME = "ace-nav"
+
+        REGISTERED_COMMANDS = [
+          ["resolve", "Resolve resource path or content"],
+          ["list", "List matching resources"],
+          ["create", "Create resource from template"],
+          ["sources", "Show available sources"]
+        ].freeze
+
+        HELP_EXAMPLES = [
+          "ace-nav resolve wfi://task/work       # Get workflow file path",
+          "ace-nav list 'wfi://*'               # Browse all workflows",
+          "ace-nav sources                       # Show registered sources"
+        ].freeze
+
+        # Register the resolve command (default) - Hanami pattern: CLI::Commands::
+        register "resolve", CLI::Commands::Resolve.new
+
+        # Register the list command
+        register "list", CLI::Commands::List.new
+
+        # Register the create command
+        register "create", CLI::Commands::Create.new
+
+        # Register the sources command
+        register "sources", CLI::Commands::Sources.new
+
+        # Register version command
+        version_cmd = Ace::Support::Cli::VersionCommand.build(
+          gem_name: "ace-support-nav",
+          version: Ace::Support::Nav::VERSION
+        )
+        register "version", version_cmd
+        register "--version", version_cmd
+
+        help_cmd = Ace::Support::Cli::HelpCommand.build(
+          program_name: PROGRAM_NAME,
+          version: Ace::Support::Nav::VERSION,
+          commands: REGISTERED_COMMANDS,
+          examples: HELP_EXAMPLES
+        )
+        register "help", help_cmd
+        register "--help", help_cmd
+        register "-h", help_cmd
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Nav
+      module Models
+        # Represents a source of handbook resources
+        class HandbookSource
+          attr_reader :name, :path, :alias_name, :type, :priority, :resource_root
+
+          def initialize(name:, path:, alias_name: nil, type: :gem, priority: 100, resource_root: nil)
+            @name = name
+            @path = path
+            @alias_name = alias_name || derive_alias(name, type)
+            @type = type # :project, :user, :gem, :custom
+            @priority = priority
+            @resource_root = resource_root || default_resource_root
+          end
+
+          def project?
+            type == :project
+          end
+
+          def user?
+            type == :user
+          end
+
+          def gem?
+            type == :gem
+          end
+
+          def custom?
+            type == :custom
+          end
+
+          def handbook_path
+            resource_root
+          end
+
+          def exists?
+            Dir.exist?(handbook_path)
+          end
+
+          def to_h
+            {
+              name: name,
+              path: path,
+              alias: alias_name,
+              type: type,
+              priority: priority,
+              exists: exists?
+            }
+          end
+
+          private
+
+          def default_resource_root
+            gem? ? File.join(path, "handbook") : path
+          end
+
+          def derive_alias(name, type)
+            case type
+            when :project then "@project"
+            when :user then "@user"
+            when :gem then "@#{name}"
+            else "@#{name.downcase.gsub(/[^a-z0-9-]/, "-")}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Nav
+      module Models
+        # Represents a source registration for a protocol
+        class ProtocolSource
+          attr_reader :name, :type, :path, :priority, :description, :origin, :config_file, :alias_name, :config_dir, :config
+
+          def initialize(name:, type:, path:, priority:, description: nil, origin: nil, config_file: nil, config_dir: nil, config: nil)
+            @name = name
+            @type = type
+            @path = path
+            @priority = priority
+            @description = description
+            @origin = origin
+            @config_file = config_file
+            @config_dir = config_dir
+            @config = config
+            @alias_name = "@#{name}"
+          end
+
+          # Get the full path for this source
+          def full_path
+            case @type
+            when "gem"
+              # For gem type, resolve through RubyGems
+              require "rubygems"
+              begin
+                spec = Gem::Specification.find_by_name(@name)
+                gem_dir = spec.gem_dir
+
+                # Get relative path from config, or use default
+                relative = @config&.dig("relative_path") || "handbook/workflow-instructions"
+
+                File.join(gem_dir, relative)
+              rescue Gem::LoadError => e
+                # Gem not found, return a placeholder path
+                warn "Gem '#{@name}' not found: #{e.message}" if ENV["VERBOSE"]
+                "/gem-not-found/#{@name}"
+              end
+            else
+              # Original path resolution logic for directory/path types
+              return path if path&.start_with?("/")
+
+              if config_dir && path
+                # Resolve relative paths from project root (parent of .ace directory)
+                project_dir = find_project_root(config_dir)
+                if project_dir
+                  File.expand_path(File.join(project_dir, path))
+                else
+                  File.expand_path(path)
+                end
+              elsif path
+                # Fallback to expand from current directory
+                File.expand_path(path)
+              else
+                # No path specified
+                "/no-path-specified"
+              end
+            end
+          end
+
+          def exists?
+            Dir.exist?(full_path)
+          end
+
+          def to_h
+            {
+              name: name,
+              type: type,
+              path: path,
+              full_path: full_path,
+              priority: priority,
+              description: description,
+              origin: origin,
+              exists: exists?
+            }
+          end
+
+          def to_s
+            "#{name} (#{type}): #{full_path}"
+          end
+
+          private
+
+          # Walk up from config_dir to find the .ace directory, return its parent (project root)
+          # config_dir is like /path/to/project/.ace/protocols/wfi-sources/local.yml
+          def find_project_root(dir)
+            ace_dir = dir
+            while ace_dir && !ace_dir.end_with?("/.ace")
+              parent = File.dirname(ace_dir)
+              break if parent == ace_dir # Reached filesystem root
+              ace_dir = parent
+            end
+
+            File.dirname(ace_dir) if ace_dir&.end_with?("/.ace")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Nav
+      module Models
+        # Represents a resource within a handbook
+        class Resource
+          attr_reader :uri, :path, :source, :protocol, :resource_path
+
+          def initialize(uri:, path:, source:, protocol:, resource_path:)
+            @uri = uri
+            @path = path
+            @source = source
+            @protocol = protocol
+            @resource_path = resource_path
+          end
+
+          def content
+            return nil unless File.exist?(path)
+            File.read(path)
+          end
+
+          def exists?
+            File.exist?(path)
+          end
+
+          def directory?
+            File.directory?(path)
+          end
+
+          def to_h
+            {
+              uri: uri,
+              path: path,
+              source: source.to_h,
+              protocol: protocol,
+              resource_path: resource_path,
+              exists: exists?
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/config_loader"
+
+module Ace
+  module Support
+    module Nav
+      module Models
+        # Represents a parsed resource URI
+        class ResourceUri
+          attr_reader :protocol, :source, :path, :raw
+
+          def initialize(raw_uri, config_loader: nil)
+            @raw = raw_uri
+            @config_loader = config_loader || Molecules::ConfigLoader.new
+            parse_uri(raw_uri)
+          end
+
+          def valid?
+            !protocol.nil? && @config_loader.valid_protocol?(protocol)
+          end
+
+          def source_specific?
+            !source.nil?
+          end
+
+          def cascade_search?
+            source.nil?
+          end
+
+          def to_s
+            raw
+          end
+
+          def to_h
+            {
+              raw: raw,
+              protocol: protocol,
+              source: source,
+              path: path,
+              source_specific: source_specific?,
+              cascade_search: cascade_search?
+            }
+          end
+
+          private
+
+          def parse_uri(raw_uri)
+            return unless raw_uri.include?("://")
+
+            parts = raw_uri.split("://", 2)
+            @protocol = parts[0]
+
+            return unless parts[1]
+
+            # Check for @ prefix indicating source-specific lookup
+            if parts[1].start_with?("@")
+              # Extract source and path
+              # Format: @source/path or just @source
+              if parts[1].include?("/")
+                source_parts = parts[1].split("/", 2)
+                @source = source_parts[0] # includes @
+                @path = source_parts[1]
+              else
+                @source = parts[1] # just @source
+                @path = nil
+              end
+            else
+              # No source specified - cascade search
+              @source = nil
+              @path = parts[1].empty? ? nil : parts[1]
+            end
+          end
+        end
+      end
+    end
+  end
+end