ace-support-nav 0.25.2 → 0.28.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3c025e29285a77e6944e76b3cafe314ab00a7042d61b55e84214ee0a0012d47
-  data.tar.gz: 0424d2d2622c8c2669a075e04ffa6292c91ea4129c7fdd11a974d03f901e59ff
+  metadata.gz: 85ee08c81f2ee6031ebb6494c4e6362cb9c5cd99fcc2f40fd8edc8ab284519ee
+  data.tar.gz: c9c477c8ec3cb1a516cdfd3917599b52e11cfcb95b780ee6f6aee1101ff3352d
 SHA512:
-  metadata.gz: 6a877791f3f020b42a403b2a252a8aa81ce44908bb3c4379b586fdf111f0a5040e7289447d9077cc29178b1471677c49d855007dee2c4ea006ebdf90b6eb00f5
-  data.tar.gz: 447dea722a4e280c83d18394e1a029dd8f189a8bf9449e43a8d8f47289ba28b825aa26070e9f9155334face35e9f9cfafaff530569b9ef1a01e281896ff29394
+  metadata.gz: 6cec2ea42760eb34c86ac9f10d56410449714478a874169e8e60ce0fae0e5efeb5f981c571fb380bea9a397bd28eeb0f2c53aece221892b5992c0d549733c648
+  data.tar.gz: 21645a38eab8b20f7629c64574fd75a37e208e5add437104e9f05c58da3501ea0d32d61e9ad2f0597eff0db68e076ebb0e42d0fb3ee6fe678f7a0a3b10ab3179

data/.ace-defaults/nav/protocols/cookbook-sources/project-local.yml

@@ -0,0 +1,13 @@
+---
+# Project-local cookbook source configuration
+# Enables cookbook discovery from repository-level handbook overlays.
+
+name: project-local-cookbooks
+type: directory
+path: .ace-handbook/cookbooks
+description: Cookbooks from project-local .ace-handbook overlay
+priority: 20
+
+config:
+  pattern: "*.cookbook.md"
+  enabled: true

data/.ace-defaults/nav/protocols/cookbook.yml

@@ -0,0 +1,58 @@
+# Protocol definition for cookbooks
+protocol: cookbook
+name: "Cookbooks"
+description: "Operational runbooks and implementation recipes"
+enabled: true
+
+# File extensions to match
+extensions:
+  - .cookbook.md
+
+# Extension inference for DWIM behavior
+inferred_extensions:
+  - .cookbook
+  - .cookbook.md
+
+# Categories for organizing cookbooks
+categories:
+  - setup
+  - migration
+  - integration
+  - debugging
+  - automation
+  - pattern
+
+# Template for creating new cookbooks
+create_template: |
+  # {Category} Cookbook: {Cookbook Name}
+
+  ## Purpose
+
+  Brief description of what this cookbook accomplishes.
+
+  ## Source Provenance
+
+  - Source workflows/guides/docs:
+  - Validation evidence:
+
+  ## Steps
+
+  ### Step 1: {Step Title}
+
+  ```bash
+  # command
+  ```
+
+  ## Propagation Notes
+
+  - Documentation updates to apply:
+  - Agent guidance updates to apply:
+
+# Protocol capabilities
+capabilities:
+  searchable: true
+  supports_glob: true
+  supports_create: true
+  supports_content: true
+  supports_list: true
+  supports_tree: true

data/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.2] - 2026-04-20
+
+### Technical
+- Stabilized `TS-NAV-001` discovery-listing verification by requiring canonical `list.*` captures for the public `ace-nav list` workflow.
+
+## [0.28.1] - 2026-04-16
+
+### Technical
+- Updated `TS-NAV-001` sandbox setup to source `mise.toml` from `${ACE_E2E_SOURCE_ROOT:-$PROJECT_ROOT_PATH}` so resource-navigation smoke runs stay compatible with read-only source-root mounts.
+
+## [0.28.0] - 2026-04-15
+
+### Changed
+- Reworked `TS-NAV-001` E2E coverage to public-surface goal contracts by rewriting discovery/resolve/listing goals around actionable user outcomes instead of extension-priority internals.
+- Added `TC-006 create-from-template public path` coverage to verify end-to-end creation behavior through `ace-nav create` with real filesystem outputs.
+- Updated package Quick Start guidance to include one complete user journey (`resolve -> list -> sources -> create`) and explicit user-facing success signals.
+
+## [0.27.3] - 2026-04-13
+
+### Fixed
+- Deduplicated `cookbook://` listing output by canonicalized resource path while preserving source priority when overlaps occur.
+- Canonicalized dedupe keys with `File.realpath` (with fallback to `File.expand_path`) so symlinked and real source roots collapse to one cookbook entry.
+- Added regression coverage for mixed source types and real-path vs symlink-path overlaps to lock dedupe behavior.
+
+## [0.27.1] - 2026-04-13
+
+### Changed
+- Completed the batch i05 migration follow-through for this package and aligned it with the restarted `fast` / `feat` / `e2e` verification model.
+
+### Technical
+- Included in the coordinated assignment-driven patch release for batch i05 package updates.
+
+
+### Changed
+- Migrated package tests to the restarted `fast` / `feat` / `e2e` model, moved deterministic coverage into `test/fast` and `test/feat`, refreshed `TS-NAV-001` decision metadata/setup for sandbox reliability, and updated README testing guidance to the new lane contract.
+
+## [0.26.3] - 2026-04-01
+
+### Fixed
+- Switched protocol source config loading from `YAML.load_file` to `YAML.safe_load_file` with explicit safe-load options.
+
+### Changed
+- Documented the intent of the project-local `cookbook://` protocol override to prevent accidental cleanup of required monorepo behavior.
+
+## [0.26.2] - 2026-04-01
+
+### Fixed
+- Restricted `cookbook://` inferred extension matching to cookbook-specific forms (`.cookbook`, `.cookbook.md`) so plain `.md` files are not inferred as cookbook assets.
+
+## [0.26.1] - 2026-04-01
+
+### Fixed
+- Deduplicated `cookbook://` listings across overlapping source registrations and resource scans.
+- Added explicit project-local cookbook source support at `.ace-handbook/cookbooks` and mapped cookbook create targets to the `cookbooks/` directory.
+
+### Changed
+- Aligned cookbook protocol create-template placeholders with lint-safe brace format and tightened canonical extension matching.
+
+## [0.26.0] - 2026-04-01
+
+### Added
+- Added `cookbook://` protocol defaults, extension inference, categories, and create template for cookbook resource discovery.
+
 ## [0.25.2] - 2026-03-29
 
 ### Technical

data/README.md

@@ -37,10 +37,26 @@
 ## Quick Start
 
 ```bash
-ace-nav resolve wfi://setup           # Locate a workflow instruction
-ace-nav resolve guide://configuration # Find a guide by protocol URI
-ace-nav list 'wfi://*test*'           # Wildcard search across sources
-ace-nav --sources                     # List all registered handbook sources
+ace-nav resolve guide://markdown-style             # Resolve a guide path
+ace-nav list 'wfi://*test*'                        # Browse candidate workflows
+ace-nav sources                                    # List all registered sources
+ace-nav create wfi://setup ./tmp/setup-copy.wf.md # Create from URI into a file
+```
+
+Expected user-facing success criteria for this journey:
+- `resolve` returns a usable path for the requested resource.
+- `list` and `sources` return actionable entries for follow-up commands.
+- `create` writes the requested file at the provided target path.
+
+## Testing
+
+Use the restarted lane model for this package:
+
+```bash
+ace-test ace-support-nav       # fast deterministic lane (default)
+ace-test ace-support-nav feat  # deterministic feature lane
+ace-test ace-support-nav all   # fast + feat
+ace-test-e2e ace-support-nav   # retained workflow-value scenarios only
 ```
 
 ---

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

@@ -41,7 +41,7 @@ module Ace
               resources.concat(find_resources_in_source_internal(source, protocol_config, pattern))
             end
 
-            resources
+            deduplicate_resources(resources)
           end
 
           # Find resources in a specific source (internal implementation)
@@ -276,6 +276,18 @@ module Ace
             resources
           end
 
+          def deduplicate_resources(resources)
+            seen = Set.new
+
+            resources.each_with_object([]) do |resource, unique_resources|
+              key = dedupe_resource_key(resource)
+              next if seen.include?(key)
+
+              seen.add(key)
+              unique_resources << resource
+            end
+          end
+
           # Check if extension inference is enabled in settings (cached)
           def extension_inference_enabled?
             return @extension_inference_enabled unless @extension_inference_enabled.nil?
@@ -369,6 +381,17 @@ module Ace
 
           private
 
+          def dedupe_resource_key(resource)
+            protocol = resource[:protocol]
+            path = resource[:path].to_s
+            canonical_path = begin
+              File.realpath(path)
+            rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+              File.expand_path(path)
+            end
+            [protocol, canonical_path]
+          end
+
           def create_resource_info(file_path, search_path, source, protocol)
             # Ensure search_path ends with a separator for proper substitution
             normalized_search_path = search_path.end_with?("/") ? search_path : "#{search_path}/"

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

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require "yaml"
+require "date"
 require "pathname"
+require "rubygems"
 require "ace/support/fs"
 require_relative "../models/protocol_source"
 
@@ -39,8 +41,34 @@ module Ace
             # Discover from project hierarchy
             sources.concat(discover_project_sources(protocol))
 
+            # Discover packaged defaults from installed ace-* gems
+            sources.concat(discover_gem_default_sources(protocol))
+
             # Sort by priority (lower number = higher priority)
-            sources.sort_by(&:priority)
+            deduplicate_sources(sources.sort_by(&:priority))
+          end
+
+          def deduplicate_sources(sorted_sources)
+            seen = {}
+
+            sorted_sources.each_with_object([]) do |source, unique_sources|
+              key = dedupe_key(source)
+              next if seen[key]
+
+              seen[key] = true
+              unique_sources << source
+            end
+          end
+
+          def dedupe_key(source)
+            config = source.config || {}
+            [
+              source.name,
+              source.type,
+              source.path,
+              config["relative_path"],
+              config["pattern"]
+            ]
           end
 
           def discover_user_sources(protocol)
@@ -78,8 +106,27 @@ module Ace
             sources
           end
 
+          def discover_gem_default_sources(protocol)
+            sources = []
+            sources_dir_suffix = File.join(".ace-defaults", "nav", "protocols", "#{protocol}-sources")
+
+            Gem::Specification.each do |spec|
+              next unless spec.name.start_with?("ace-")
+
+              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")
+                sources << source if source
+              end
+            end
+
+            sources
+          end
+
           def load_source_file(file_path, origin)
-            data = YAML.load_file(file_path)
+            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)
@@ -122,8 +169,10 @@ module Ace
               10  # Highest priority
             when "user"
               50  # Medium priority
+            when "gem-default"
+              100 # Installed gem defaults
             else
-              100 # Lower priority for gems
+              150 # Lowest priority for unknown origins
             end
           end
         end

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

@@ -159,6 +159,7 @@ module Ace
             when "wfi" then "workflow-instructions"
             when "tmpl" then "templates"
             when "guide" then "guides"
+            when "cookbook" then "cookbooks"
             when "sample" then "samples"
             else template.protocol
             end

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

@@ -3,7 +3,7 @@
 module Ace
   module Support
     module Nav
-      VERSION = '0.25.2'
+      VERSION = '0.28.2'
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-support-nav
 version: !ruby/object:Gem::Version
-  version: 0.25.2
+  version: 0.28.2
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-03-29 00:00:00.000000000 Z
+date: 2026-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -161,6 +161,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".ace-defaults/nav/config.yml"
+- ".ace-defaults/nav/protocols/cookbook-sources/project-local.yml"
+- ".ace-defaults/nav/protocols/cookbook.yml"
 - ".ace-defaults/nav/protocols/guide-sources/ace-support-nav.yml"
 - ".ace-defaults/nav/protocols/guide.yml"
 - ".ace-defaults/nav/protocols/prompt.yml"