ace-support-nav 0.25.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e493ee4ffdce85ef637ce1ab36225ce053b40f85b24570ec2503823bf981b8f3
+  data.tar.gz: 7b2f34fadee418efd1e2bbf7d66a836b7d54e5ca6a72fb549eb1424c85d0f68f
+SHA512:
+  metadata.gz: 8dea4d0a2c5e5f511e84e76a72e33692aeda77eebf5d30d1a2549e980735d3253c2c27c68184d2a495d026b1681d9a33a87f613028e49fbe6e50a0a043680cfd
+  data.tar.gz: 9e9053d151aa8e3aa55d8d457114afe149c501263e3ddff69af774943bc502924458e70fb7424be5ff24e0485e8022ea4dd18fea91d978351384d4ebb215077f

data/.ace-defaults/nav/config.yml

@@ -0,0 +1,33 @@
+# ace-nav configuration
+# Place in .ace/nav/config.yml to customize
+# ADR-022: This file is the single source of truth for defaults
+#
+# Configuration cascade:
+#   1. .ace-defaults/nav/config.yml (gem defaults - this file)
+#   2. ~/.ace/nav/config.yml (user defaults)
+#   3. .ace/nav/config.yml (project overrides)
+
+# Cache settings for protocol resolution
+cache:
+  enabled: false  # Enable caching of protocol lookups
+  directory: ".ace-local/nav"  # Cache directory path
+  ttl: 3600  # Cache TTL in seconds (1 hour)
+
+# Fuzzy matching settings for resource names
+fuzzy:
+  enabled: true  # Enable fuzzy matching for resource names
+  threshold: 0.6  # Minimum similarity score (0.0 - 1.0)
+
+# Output settings
+output:
+  color: true  # Enable colored output
+  verbose: false  # Enable verbose output
+
+# Extension inference settings for protocol resolution
+extension_inference:
+  enabled: true  # Enable DWIM extension inference when exact match fails
+  fallback_order:
+    - protocol_shorthand  # e.g., .g, .wf
+    - protocol_full       # e.g., .g.md, .wf.md
+    - generic_markdown    # .md
+    - bare               # no extension

data/.ace-defaults/nav/protocols/guide-sources/ace-support-nav.yml

@@ -0,0 +1,7 @@
+# Example: ace-support-nav guide sources
+# Copy this file to .ace/protocols/guide-sources/ to enable
+name: ace-support-nav
+type: directory
+path: ./handbook/guides/
+priority: 100
+description: "ace-support-nav guides and documentation"

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

@@ -0,0 +1,69 @@
+# Protocol definition for guides
+protocol: guide
+name: "Guides"
+description: "Documentation and how-to guides"
+enabled: true
+
+
+# File extensions to match
+extensions:
+  - .g.md        # shorthand first
+  - .guide.md    # full second
+  - .md          # generic last
+
+# Extension inference for DWIM behavior
+inferred_extensions:
+  - .g
+  - .guide
+  - .g.md
+  - .guide.md
+  - .md
+
+# Categories for organizing guides
+categories:
+  - getting-started
+  - architecture
+  - development
+  - deployment
+  - troubleshooting
+  - best-practices
+
+# Template for creating new guides
+create_template: |
+  # %{name}
+
+  ## Overview
+
+  Brief introduction to this guide.
+
+  ## Table of Contents
+
+  - [Section 1](#section-1)
+  - [Section 2](#section-2)
+  - [Section 3](#section-3)
+
+  ## Section 1
+
+  Content for section 1.
+
+  ## Section 2
+
+  Content for section 2.
+
+  ## Section 3
+
+  Content for section 3.
+
+  ## Related Guides
+
+  - Link to related guide 1
+  - Link to related guide 2
+
+# Protocol capabilities
+capabilities:
+  searchable: true
+  supports_glob: true
+  supports_create: true
+  supports_content: true
+  supports_list: true
+  supports_tree: true

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

@@ -0,0 +1,39 @@
+# Protocol definition for system prompts
+protocol: prompt
+name: "System Prompts"
+description: "System prompts for LLM interactions and tools"
+enabled: true
+
+# File extensions to match
+extensions:
+  - .md
+  - .prompt.md
+
+# Template for creating new prompts
+create_template: |
+  # %{name} System Prompt
+
+  You are an expert in %{domain}. Your task is to %{task}.
+
+  ## Instructions
+
+  1. Follow these guidelines
+  2. Maintain consistency
+  3. Be precise and clear
+
+  ## Format
+
+  Describe the expected output format.
+
+  ## Examples
+
+  Provide concrete examples of expected behavior.
+
+# Protocol capabilities
+capabilities:
+  searchable: true
+  supports_glob: true
+  supports_create: true
+  supports_content: true
+  supports_list: true
+  supports_tree: true

data/.ace-defaults/nav/protocols/skill-sources/ace-support-nav.yml

@@ -0,0 +1,19 @@
+---
+# Skill Sources Protocol Configuration for ace-support-nav
+# This enables canonical skill discovery from the ace-support-nav gem
+
+name: ace-support-nav
+type: gem
+description: Canonical skills from ace-support-nav gem
+priority: 10
+
+# Configuration for skill discovery within the gem
+config:
+  # Relative path within the gem
+  relative_path: handbook/skills
+
+  # Pattern for finding canonical skill files
+  pattern: "*/SKILL.md"
+
+  # Enable discovery
+  enabled: true

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

@@ -0,0 +1,22 @@
+# Protocol definition for canonical skills
+protocol: skill
+name: "Canonical Skills"
+description: "Canonical package-owned SKILL.md resources"
+enabled: true
+
+# Canonical skills resolve to handbook/skills/<name>/SKILL.md
+extensions:
+  - /SKILL.md
+
+# Extension inference for shorthand lookups
+inferred_extensions:
+  - /SKILL.md
+
+# Protocol capabilities
+capabilities:
+  searchable: true
+  supports_glob: true
+  supports_create: false
+  supports_content: true
+  supports_list: true
+  supports_tree: true

data/.ace-defaults/nav/protocols/tmpl-sources/ace-support-nav.yml

@@ -0,0 +1,7 @@
+# Example: ace-support-nav template sources
+# Copy this file to .ace/protocols/tmpl-sources/ to enable
+name: ace-support-nav
+type: directory
+path: ./handbook/templates/
+priority: 100
+description: "ace-support-nav templates"

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

@@ -0,0 +1,55 @@
+# Protocol definition for templates
+protocol: tmpl
+name: "Templates"
+description: "Reusable document and code templates"
+enabled: true
+
+
+# File extensions to match
+extensions:
+  - .tmpl.md
+  - .template.md
+
+# Categories for organizing templates
+categories:
+  - minitest
+  - rspec
+  - task
+  - release
+  - documentation
+  - code-review
+
+# Template for creating new templates
+create_template: |
+  ---
+  name: %{name}
+  category: %{category}
+  description: Template description
+  ---
+
+  # %{name} Template
+
+  ## Usage
+
+  Describe how to use this template.
+
+  ## Template Content
+
+  [Your template content here]
+
+  ## Variables
+
+  - `%{variable}`: Description of this variable
+
+  ## Examples
+
+  Show examples of the template in use.
+
+# Protocol capabilities
+capabilities:
+  searchable: true
+  supports_glob: true
+  supports_create: true
+  supports_content: true
+  supports_list: true
+  supports_tree: true

data/.ace-defaults/nav/protocols/wfi-sources/ace-support-nav.yml

@@ -0,0 +1,7 @@
+# Example: ace-support-nav workflow instruction sources
+# Copy this file to .ace/protocols/wfi-sources/ to enable
+name: ace-support-nav
+type: directory
+path: ./handbook/workflow-instructions/
+priority: 100
+description: "ace-support-nav workflow instructions"

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

@@ -0,0 +1,61 @@
+# Protocol definition for workflow instructions
+protocol: wfi
+name: "Workflow Instructions"
+description: "Step-by-step workflow guides for development tasks"
+enabled: true
+
+# File extensions to match
+extensions:
+  - .wf.md       # shorthand first
+  - .wfi.md
+  - .workflow.md
+
+# Extension inference for DWIM behavior
+inferred_extensions:
+  - .wf
+  - .wfi
+  - .workflow
+  - .wf.md
+  - .wfi.md
+  - .workflow.md
+  - .md
+
+# Template for creating new workflows
+create_template: |
+  # %{name}
+
+  ## Goal
+
+  Describe the objective of this workflow.
+
+  ## Prerequisites
+
+  - List any requirements
+  - Tools or access needed
+
+  ## Process Steps
+
+  1. **Step One**
+     - Details about this step
+     - Sub-steps if needed
+
+  2. **Step Two**
+     - Details about this step
+
+  ## Success Criteria
+
+  - [ ] Criteria one
+  - [ ] Criteria two
+
+  ## Common Issues
+
+  Document any common problems and solutions.
+
+# Protocol capabilities
+capabilities:
+  searchable: true
+  supports_glob: true
+  supports_create: true
+  supports_content: true
+  supports_list: true
+  supports_tree: true

data/CHANGELOG.md

@@ -0,0 +1,231 @@
+# Changelog
+
+All notable changes to ace-support-nav will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.25.0] - 2026-03-23
+
+### Added
+- Added getting-started demo tape and recorded GIF showing `ace-nav sources`, `list`, and `resolve` commands.
+
+### Changed
+- Added Quick Start section with `ace-nav` CLI examples and handbook link in README footer navigation.
+- Added `docs/**/*` to gemspec file glob for demo and documentation assets.
+
+## [0.24.0] - 2026-03-23
+
+### Changed
+- Refreshed the README layout for clearer package positioning, quick section navigation, and streamlined `ace-nav` usage/configuration guidance.
+
+## [0.23.4] - 2026-03-22
+
+### Changed
+- Standardized README usage examples to consistently run `ace-nav` and `ace-test` commands via `mise exec --` for clear execution context.
+
+## [0.23.3] - 2026-03-22
+
+### Changed
+- Refreshed README structure with explicit purpose framing, standardized license/footer sections, and consistent support-package layout.
+- Updated README navigation examples and feature inventory to include canonical `skill://` protocol usage.
+
+## [0.23.2] - 2026-03-19
+
+### Changed
+- Expanded `TS-NAV-001` Goal 1 to include `ace-nav sources` command evidence capture in the runner and verifier contracts.
+- Tightened Goal 4 and Goal 5 verifier expectations for missing-resource identification and protocol-specific shorthand evidence.
+
+## [0.23.1] - 2026-03-18
+
+### Changed
+- Migrated CLI namespace from `Ace::Core::CLI::*` to `Ace::Support::Cli::*` (ace-support-cli is now the canonical home for CLI infrastructure).
+
+
+## [0.23.0] - 2026-03-18
+
+### Changed
+- Removed legacy backward-compatibility behavior as part of the 0.10 cleanup release.
+
+
+## [0.22.1] - 2026-03-15
+
+### Changed
+- Migrated CLI framework from dry-cli to ace-support-cli
+
+## [0.22.0] - 2026-03-12
+
+### Added
+- Added explicit `start_path:` support to `SourceRegistry` so protocol source discovery can be rooted at an arbitrary project instead of always using process cwd.
+
+### Technical
+- Added regression coverage for rooted source discovery used by nav-backed handbook skill inventory.
+
+## [0.21.0] - 2026-03-12
+
+### Added
+- Added project and user handbook override root support for dedicated `.ace-handbook` and `~/.ace-handbook` directories, including default `ace-nav create` targets under the new project root.
+
+### Changed
+- Changed project-local workflow registration and user-facing nav docs to point at `.ace-handbook` instead of `.ace/handbook`.
+
+### Technical
+- Added regression coverage for `@project` / `@user` source discovery under the new override roots and for default create-target placement.
+
+## [0.20.0] - 2026-03-09
+
+### Added
+- Added scanner/CLI/regression coverage for canonical `skill://` wildcard and direct lookup behavior, including priority-based duplicate resolution for canonical `SKILL.md` paths.
+
+### Changed
+- Converted default `skill-sources` registration to gem-backed canonical discovery config and aligned it with `handbook/skills` + `*/SKILL.md` matching.
+
+## [0.19.0] - 2026-03-09
+
+### Added
+- Added canonical `skill://` protocol defaults for package-owned skill discovery.
+- Added default `skill-sources` scaffold for `handbook/skills` registration in nav protocol configuration.
+
+## [0.18.2] - 2026-03-04
+
+### Fixed
+- Sandbox-safe HOME isolation in user-source and user-protocol tests to avoid permission errors when writing under real `~/.ace`.
+
+## [0.18.1] - 2026-03-04
+
+### Changed
+- Default nav cache directory now uses `.ace-local/nav`.
+
+
+## [0.18.0] - 2026-03-04
+
+### Added
+- `resolve_cmd_to_path` method for programmatic resolution of cmd-type protocol URIs (e.g., `task://ref`)
+
+### Fixed
+- Prevent argument injection in `resolve_cmd_to_path` by escaping reference before command template interpolation
+- Add 10-second timeout to cmd protocol execution to prevent indefinite hangs
+
+## [0.17.10] - 2026-02-23
+
+### Technical
+- Updated internal dependency version constraints to current releases
+
+## [0.17.9] - 2026-02-22
+
+### Changed
+- Migrate `ace-nav` to the standard multi-command help pattern with explicit top-level `help`, `--help`, and `-h` commands.
+- Remove implicit default-command routing and require explicit `resolve`/`list`/`create`/`sources` command usage.
+- Update README and command help examples to canonical explicit command forms.
+
+### Technical
+- Remove custom default-routing from `CLI` (`start`, `KNOWN_COMMANDS`, `DEFAULT_COMMAND`) and switch executable dispatch to `Dry::CLI.new(...).call(arguments: ...)`.
+- Normalize no-argument invocation to `--help` in `exe/ace-nav` and preserve legacy `--sources` / `--create` aliases via executable argument translation.
+- Update integration tests to assert explicit dry-cli invocation behavior.
+
+## [0.17.7] - 2026-02-19
+
+### Technical
+- Add test coverage for subdirectory protocol resolution patterns
+
+## [0.17.6] - 2026-02-17
+
+### Fixed
+- Add `--tree` option to Resolve command to prevent dry-cli from calling `exit(1)` on unknown option
+  - This caused integration tests to crash mid-process, breaking both grouped and single-batch test execution
+  - `ace-test-suite` reported 0 tests for ace-support-nav because the subprocess died before minitest output
+
+### Technical
+- Remove dead `navigation_integration_test.rb` that was permanently skipped via `runnable_methods` returning `[]`
+- Consolidate E2E test configuration fixtures
+
+## [0.17.5] - 2026-02-11
+
+### Changed
+- Simplified path resolution in `ProtocolSource` to consistently use project root
+- Extracted `find_project_root` private method for cleaner code structure
+
+### Technical
+- Migrate E2E tests to per-TC directory format
+- Add E2E tests for ace-nav and ace-timestamp
+
+## [0.17.4] - 2026-02-02
+
+### Fixed
+- Protocol listing with empty path (`wfi://`) now correctly lists all resources
+  - Empty path after `://` is now normalized to `nil` in `ResourceUri`
+  - Enables `pattern = uri.path || "*"` to default to wildcard
+- Bare protocol names (`wfi`, `tmpl`, `guide`) now auto-expand to `protocol://` format
+  - Added `normalize_protocol_shorthand` in Resolve command
+  - Both `ace-nav wfi` and `ace-nav wfi://` now list all workflow instructions
+- Extension inference prefix matching bug (TC-004)
+  - `start_with?` was too permissive, matching `multi-ext.guide.md` when searching for `multi-ext.g`
+  - Now validates character following candidate is either end-of-string or dot separator
+
+## [0.17.3] - 2026-01-24
+
+### Added
+- Extension inference for protocol resolution (task 224)
+  - Add `ExtensionInferrer` atom for DWIM extension inference
+  - Configure inference via `.ace/nav/config.yml` with `extension_inference.enabled` and `fallback_order`
+  - Add `inferred_extensions` to protocol configs (guide.yml, wfi.yml)
+  - Update `ProtocolScanner` to use inference when exact match fails
+  - Strip extensions using both protocol and inferred extension lists
+
+## [0.17.2] - 2026-01-16
+
+### Changed
+- Updated README.md references from ace-context to ace-bundle (task 206)
+
+## [0.17.1] - 2026-01-15
+
+### Changed
+- Migrate CLI commands to Hanami pattern
+  - Move commands from `commands/` to `cli/commands/`
+  - Update namespace from `Commands::*` to `CLI::Commands::*`
+  - Update test file references for new namespace
+
+## [0.17.0] - 2026-01-12
+
+### Changed
+- **BREAKING**: Renamed gem from `ace-nav` to `ace-support-nav`
+  - Namespace changed from `Ace::Nav` to `Ace::Support::Nav`
+  - Import path changed from `require "ace/nav"` to `require "ace/support/nav"`
+  - Gem dependency changed from `ace-nav` to `ace-support-nav`
+  - Executable remains `ace-nav` for backwards compatibility
+  - User config path `.ace/nav/` preserved for backward compatibility
+
+### Migration Guide
+```ruby
+# Before
+require "ace/nav"
+Ace::Nav.config
+Ace::Nav::CLI.start(ARGV)
+
+# After
+require "ace/support/nav"
+Ace::Support::Nav.config
+Ace::Support::Nav::CLI.start(ARGV)
+```
+
+## Previous Releases (as ace-nav)
+
+For detailed changes prior to 0.17.0, see the git history of the ace-nav directory before the rename (commit da99d457b and earlier).
+
+### Notable releases before rename:
+
+- **0.16.1**: Eliminated wrapper pattern in dry-cli commands
+- **0.16.0**: Migrated CLI framework from Thor to dry-cli
+- **0.15.0**: Thor CLI migration with standardized command structure
+- **0.14.0**: Minimum Ruby version raised to 3.3.0
+- **0.13.0**: Renamed `.ace.example/` to `.ace-defaults/`
+- **0.10.0**: Added task:// Protocol Support
+- **0.9.0**: Initial release with core navigation functionality
+
+
+## [0.17.8] - 2026-02-22
+
+### Fixed
+- Standardized quiet, verbose, debug option descriptions to canonical strings

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,48 @@
+<div align="center">
+  <h1> ACE - Support Nav </h1>
+
+  Protocol-aware navigation and resource discovery for ACE handbook content.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-support-nav"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-support-nav.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+`ace-support-nav` powers the `ace-nav` CLI with cascade-aware URI resolution across project, user, and gem sources. It supports built-in protocols (`wfi://`, `guide://`, `tmpl://`, `skill://`, `prompt://`) and extensible command protocols like `task://` for tool delegation, with override targeting, wildcard discovery, and fast cached lookups.
+
+## How It Works
+
+1. Accept a protocol URI (e.g., `wfi://setup`) and search project, user, and gem handbook sources in cascade order.
+2. Apply extension inference and override targeting (`@project` for repo `.ace-handbook/`, `@user` for `~/.ace-handbook/`, `@gem` for a specific gem's bundled handbook) to locate the best match.
+3. Return the resolved path, content, or a list of candidates for wildcard and prefix patterns.
+
+## Use Cases
+
+**Resolve ACE resources without memorizing file paths** - run `ace-nav resolve wfi://setup` or `ace-nav resolve guide://configuration` to locate workflows, guides, templates, and skills through protocol URLs instead of raw paths.
+
+**Target the right override layer explicitly** - use `@project`, `@user`, or specific gem aliases (e.g., `wfi://@ace-git/setup`) to bypass cascade ambiguity when multiple sources provide the same resource.
+
+**Discover matching resources quickly** - use wildcard and prefix patterns like `ace-nav list 'wfi://*test*'` or `ace-nav resolve prompt://guidelines/` to browse available content across all handbook sources.
+
+**Navigate task specs through the same interface** - use `task://` references (e.g., `ace-nav resolve task://083`) so task lookup shares the same navigation workflow as handbook resources, delegating to [ace-task](../ace-task) under the hood.
+
+**Load resolved content into agent workflows** - pair with [ace-bundle](../ace-bundle) to fetch and embed resources discovered through `ace-nav` into agent context for skills and workflows.
+
+## 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
+```
+
+---
+
+[Handbook](handbook/) | Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/docs/demo/ace-support-nav-getting-started.tape.yml

@@ -0,0 +1,28 @@
+---
+description: Browse and resolve ACE handbook resources with ace-nav
+tags:
+- docs
+- nav
+- getting-started
+settings:
+  font_size: 16
+  width: 960
+  height: 480
+  format: gif
+scenes:
+- name: Show registered handbook sources
+  commands:
+  - type: ace-nav sources
+    sleep: 4s
+- name: List all workflow instructions
+  commands:
+  - type: clear
+    sleep: 1s
+  - type: ace-nav list 'wfi://*'
+    sleep: 4s
+- name: Resolve a specific workflow
+  commands:
+  - type: clear
+    sleep: 1s
+  - type: ace-nav resolve wfi://task/work
+    sleep: 4s