ace-support-nav 0.25.0

data/exe/ace-nav

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ace/support/nav"
+require "ace/support/cli"
+
+def translate_legacy_args(args)
+  return ["--help"] if args.empty?
+
+  if args.include?("--sources")
+    return ["sources"] + args.reject { |arg| arg == "--sources" }
+  end
+
+  return args unless args.include?("--create")
+
+  create_index = args.index("--create")
+  uri = args[create_index + 1]
+  target = args[create_index + 2]
+  translated = ["create"]
+  consumed = [create_index]
+
+  if uri && !uri.start_with?("-")
+    translated << uri
+    consumed << create_index + 1
+  end
+
+  if target && !target.start_with?("-")
+    translated << target
+    consumed << create_index + 2
+  end
+
+  args.each_with_index do |arg, index|
+    translated << arg unless consumed.include?(index)
+  end
+
+  translated
+end
+
+# Start CLI with exception-based exit code handling (per ADR-023)
+begin
+  argv = translate_legacy_args(ARGV.dup)
+  Ace::Support::Cli::Runner.new(Ace::Support::Nav::CLI).call(args: argv)
+rescue SystemExit => e
+  exit(e.status)
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit(e.exit_code)
+end

data/handbook/workflow-instructions/test.wfi.md

@@ -0,0 +1,14 @@
+# Test Workflow
+
+## Goal
+Test the new protocol source registration system.
+
+## Process Steps
+1. Register sources via YAML files
+2. Discover sources dynamically
+3. Resolve resources using the new system
+
+## Success Criteria
+- [x] Sources can be registered per protocol
+- [x] Multiple sources are discovered
+- [x] Resources are resolved correctly

data/lib/ace/support/nav/atoms/extension_inferrer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Nav
+      module Atoms
+        # Infers file extensions for protocol-based resource resolution
+        # Implements DWIM (Do What I Mean) extension inference
+        class ExtensionInferrer
+          # Default extension inference order when not configured
+          DEFAULT_FALLBACK_ORDER = %w[
+            protocol_shorthand
+            protocol_full
+            generic_markdown
+            bare
+          ].freeze
+
+          class << self
+            # Generate candidate extensions for a pattern based on protocol config
+            # @param pattern [String] The search pattern (e.g., "markdown-style")
+            # @param protocol_extensions [Array<String>] Protocol-specific extensions (e.g., [".g.md", ".guide.md"])
+            # @param enabled [Boolean] Whether extension inference is enabled
+            # @param fallback_order [Array<String>] Order of extension types to try
+            # @return [Array<String>] List of candidate patterns to try
+            def infer_extensions(pattern, protocol_extensions: [], enabled: true, fallback_order: DEFAULT_FALLBACK_ORDER)
+              return [pattern] unless enabled
+              return [pattern] if pattern.empty?
+
+              # Guard against nil fallback_order
+              fallback_order ||= DEFAULT_FALLBACK_ORDER
+
+              # Extract shorthand extensions from protocol extensions
+              # e.g., from [".g.md", ".guide.md"] extract [".g"]
+              shorthand_extensions = extract_shorthand_extensions(protocol_extensions)
+
+              candidates = []
+
+              fallback_order.each do |fallback_type|
+                case fallback_type
+                when "protocol_shorthand"
+                  # Try with shorthand extensions first (e.g., ".g")
+                  shorthand_extensions.each do |ext|
+                    candidate = "#{pattern}#{ext}"
+                    candidates << candidate unless candidates.include?(candidate)
+                  end
+                when "protocol_full"
+                  # Try with full protocol extensions (e.g., ".g.md", ".guide.md")
+                  protocol_extensions.each do |ext|
+                    candidate = "#{pattern}#{ext}"
+                    candidates << candidate unless candidates.include?(candidate)
+                  end
+                when "generic_markdown"
+                  # Try with generic markdown extension (e.g., ".md")
+                  candidate = "#{pattern}.md"
+                  candidates << candidate unless candidates.include?(candidate)
+                when "bare"
+                  # Try with no extension
+                  candidates << pattern unless candidates.include?(pattern)
+                end
+              end
+
+              candidates
+            end
+
+            # Check if a pattern already includes an extension from the list
+            # @param pattern [String] The pattern to check
+            # @param extensions [Array<String>] List of extensions to check against
+            # @return [Boolean] True if pattern ends with any of the extensions
+            def has_extension?(pattern, extensions)
+              return false if pattern.nil? || pattern.empty?
+              return false if extensions.nil? || extensions.empty?
+
+              extensions.any? { |ext| pattern.end_with?(ext) }
+            end
+
+            # Extract shorthand extensions from full protocol extensions
+            # e.g., from [".g.md", ".guide.md"] extract [".g"]
+            # @param protocol_extensions [Array<String>] Full protocol extensions
+            # @return [Array<String>] Shorthand extensions
+            def extract_shorthand_extensions(protocol_extensions)
+              return [] if protocol_extensions.nil? || protocol_extensions.empty?
+
+              shorthand_extensions = []
+
+              protocol_extensions.each do |ext|
+                # Extract the part before the first dot after the initial dot
+                # e.g., ".g.md" -> ".g", ".guide.md" -> ".guide"
+                parts = ext.split(".")
+                if parts.length >= 2
+                  shorthand = ".#{parts[1]}"
+                  shorthand_extensions << shorthand unless shorthand_extensions.include?(shorthand)
+                end
+              end
+
+              shorthand_extensions
+            end
+
+            # Get the base pattern without any extension
+            # @param pattern [String] The pattern to process
+            # @param extensions [Array<String>] List of extensions to strip
+            # @return [String] Pattern without extension
+            def strip_extension(pattern, extensions)
+              return pattern if extensions.nil? || extensions.empty?
+
+              result = pattern.dup
+              extensions.each do |ext|
+                result = result.sub(/#{Regexp.escape(ext)}\z/, "") if result.end_with?(ext)
+              end
+
+              result
+            end
+          end
+
+          # Instance method wrappers for backwards compatibility (deprecated)
+          def infer_extensions(...)
+            self.class.infer_extensions(...)
+          end
+
+          def has_extension?(...)
+            self.class.has_extension?(...)
+          end
+
+          def extract_shorthand_extensions(...)
+            self.class.extract_shorthand_extensions(...)
+          end
+
+          def strip_extension(...)
+            self.class.strip_extension(...)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/nav/atoms/gem_resolver.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rubygems"
+
+module Ace
+  module Support
+    module Nav
+      module Atoms
+        # Discovers ace-* gems and their handbook paths
+        class GemResolver
+          def find_ace_gems
+            ace_gems = []
+
+            Gem::Specification.each do |spec|
+              next unless spec.name.start_with?("ace-")
+
+              gem_info = {
+                name: spec.name,
+                version: spec.version.to_s,
+                path: spec.gem_dir,
+                handbook_path: File.join(spec.gem_dir, "handbook")
+              }
+
+              # Check if handbook exists
+              gem_info[:has_handbook] = Dir.exist?(gem_info[:handbook_path])
+
+              ace_gems << gem_info
+            end
+
+            ace_gems
+          end
+
+          def find_gem_by_name(gem_name)
+            spec = Gem::Specification.find_by_name(gem_name)
+            return nil unless spec
+
+            {
+              name: spec.name,
+              version: spec.version.to_s,
+              path: spec.gem_dir,
+              handbook_path: File.join(spec.gem_dir, "handbook"),
+              has_handbook: Dir.exist?(File.join(spec.gem_dir, "handbook"))
+            }
+          rescue Gem::LoadError
+            nil
+          end
+
+          def gem_handbook_path(gem_name)
+            gem_info = find_gem_by_name(gem_name)
+            return nil unless gem_info
+            return nil unless gem_info[:has_handbook]
+
+            gem_info[:handbook_path]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/nav/atoms/path_normalizer.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Nav
+      module Atoms
+        # Normalizes and expands paths
+        class PathNormalizer
+          def normalize(path)
+            return nil if path.nil? || path.empty?
+
+            # Expand home directory
+            path = File.expand_path(path) if path.start_with?("~")
+
+            # Resolve relative paths
+            path = File.expand_path(path) unless path.start_with?("/")
+
+            path
+          end
+
+          def join_paths(*parts)
+            File.join(*parts.compact)
+          end
+
+          def dirname(path)
+            File.dirname(path)
+          end
+
+          def basename(path, suffix = nil)
+            suffix ? File.basename(path, suffix) : File.basename(path)
+          end
+
+          def extname(path)
+            File.extname(path)
+          end
+
+          def exists?(path)
+            File.exist?(path)
+          end
+
+          def directory?(path)
+            File.directory?(path)
+          end
+
+          def file?(path)
+            File.file?(path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/nav/atoms/uri_parser.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/config_loader"
+
+module Ace
+  module Support
+    module Nav
+      module Atoms
+        # Parses resource URIs
+        class UriParser
+          def initialize(config_loader: nil)
+            @config_loader = config_loader || Molecules::ConfigLoader.new
+          end
+
+          def parse(uri_string)
+            return nil unless uri_string.is_a?(String)
+            return nil unless uri_string.include?("://")
+
+            parts = uri_string.split("://", 2)
+            protocol = parts[0]
+            rest = parts[1]
+
+            return nil unless valid_protocol?(protocol)
+            return {protocol: protocol, source: nil, path: nil} if rest.nil? || rest.empty?
+
+            # Check for source-specific syntax (@source/path or @source)
+            if rest.start_with?("@")
+              parse_source_specific(protocol, rest)
+            else
+              {protocol: protocol, source: nil, path: rest}
+            end
+          end
+
+          def valid_protocol?(protocol)
+            @config_loader.valid_protocol?(protocol)
+          end
+
+          def valid_protocols
+            @config_loader.valid_protocols
+          end
+
+          def extract_protocol(uri_string)
+            return nil unless uri_string.include?("://")
+            uri_string.split("://", 2)[0]
+          end
+
+          private
+
+          def parse_source_specific(protocol, rest)
+            # Format: @source/path or just @source
+            if rest.include?("/")
+              source_parts = rest.split("/", 2)
+              {protocol: protocol, source: source_parts[0], path: source_parts[1]}
+            else
+              {protocol: protocol, source: rest, path: nil}
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# 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 create command
+          class Create < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+
+            desc <<~DESC.strip
+              Create resource from template
+
+              SYNTAX:
+                ace-nav create [URI] [TARGET] [OPTIONS]
+
+              EXAMPLES:
+
+                # Create from workflow template
+                $ ace-nav create wfi://my-workflow
+
+                # Create from template to specific file
+                $ ace-nav create tmpl://custom ./output.md
+
+              CONFIGURATION:
+
+                Global config:  ~/.ace/nav/config.yml
+                Project config: .ace/nav/config.yml
+                Example:        ace-support-nav/.ace-defaults/nav/config.yml
+
+              OUTPUT:
+
+                Creates resource at specified path or default location
+                Exit codes: 0 (success), 1 (error)
+            DESC
+
+            example [
+              "wfi://my-workflow           # Create from workflow template",
+              "tmpl://custom ./output.md   # Create from template to file"
+            ]
+
+            argument :uri, required: true, desc: "Template URI"
+            argument :target, required: false, desc: "Target file path"
+
+            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:, target: nil, **options)
+              # Initialize instance variables for use in private methods
+              @uri = uri
+              @target = target
+              @options = options
+              @engine = Organisms::NavigationEngine.new
+
+              execute
+            end
+
+            def execute
+              display_config_summary
+
+              result = @engine.create(@uri, @target)
+
+              if result[:error]
+                raise Ace::Support::Cli::Error.new(result[:error])
+              end
+
+              puts "Created: #{result[:created]}"
+              puts "From: #{result[:from]}" if @options[:verbose]
+            end
+
+            private
+
+            def display_config_summary
+              return if @options[:quiet]
+
+              require "ace/core"
+              Ace::Core::Atoms::ConfigSummary.display(
+                command: "create",
+                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/list.rb

@@ -0,0 +1,122 @@
+# 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 list command
+          class List < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+
+            desc <<~DESC.strip
+              List matching resources
+
+              SYNTAX:
+                ace-nav list [PATTERN] [OPTIONS]
+
+              EXAMPLES:
+
+                # List all workflows
+                $ ace-nav list 'wfi://*'
+
+                # List templates with pattern
+                $ ace-nav list 'tmpl://@ace-*/*'
+
+                # Tree format
+                $ ace-nav list wfi:// --tree
+
+              CONFIGURATION:
+
+                Global config:  ~/.ace/nav/config.yml
+                Project config: .ace/nav/config.yml
+                Example:        ace-support-nav/.ace-defaults/nav/config.yml
+
+              OUTPUT:
+
+                Table format with columns: URI, path, type
+                Use --tree for hierarchical format
+                Exit codes: 0 (success), 1 (error)
+            DESC
+
+            example [
+              "'wfi://*'                 # List all workflows",
+              "'tmpl://@ace-*/*'         # List templates with pattern",
+              "wfi:// --tree             # Tree format"
+            ]
+
+            argument :pattern, required: true, desc: "Pattern to match resources"
+
+            option :tree, type: :boolean, desc: "Display resources in tree format"
+            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(pattern:, **options)
+              # Initialize instance variables for use in private methods
+              @pattern = pattern
+              @options = options
+              @engine = Organisms::NavigationEngine.new
+
+              execute
+            end
+
+            def execute
+              display_config_summary
+
+              resources = @engine.list(@pattern, tree: @options[:tree], verbose: @options[:verbose])
+
+              if resources.empty?
+                raise Ace::Support::Cli::Error.new("No resources found matching: #{@pattern}")
+              end
+
+              if @options[:verbose]
+                require "json"
+                puts JSON.pretty_generate(resources)
+              else
+                resources.each { |resource| puts resource }
+              end
+            end
+
+            private
+
+            def display_config_summary
+              return if @options[:quiet]
+
+              require "ace/core"
+              Ace::Core::Atoms::ConfigSummary.display(
+                command: "list",
+                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