microsoft / microsoft/amplifier

recipes tool: Add tilde expansion and improve bundle path handling

Open
#175 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
3.1k
Forks
261
Avg merge
3h 28m
Merged PRs (30d)
13

Description

Summary

The recipes tool's path resolution has two issues that cause confusing "Recipe file not found" errors:

Issue 1: Tilde (~) expansion not supported

When a path like ~/dev/my-recipes/recipe.yaml is passed to the recipes tool, it fails because tilde is not expanded.

Current code (amplifier-bundle-recipes/.../amplifier_module_tool_recipes/__init__.py:344-359):

def _resolve_path(self, path_str: str) -> Path | None:
    if path_str.startswith("@"):
        mention_resolver = self.coordinator.get_capability("mention_resolver")
        if mention_resolver is None:
            return None
        return mention_resolver.resolve(path_str)
    return Path(path_str)  # <-- No .expanduser() call

Fix: Add .expanduser() to the fallback path:

return Path(path_str).expanduser()
Issue 2: Bundle paths without @ prefix fail silently

When users pass bundle:path/to/recipe.yaml (without the @ prefix), it falls through to Path(path_str) which treats it as a literal path and fails.

This is confusing because:

  • The bundle.md format uses bundle:path syntax (no @)
  • The @ requirement is not immediately obvious

Options:

  1. Document clearly that @ is required (done in amplifier-module-stories README)
  2. Detect colon in path and provide a helpful error message suggesting the @ prefix
  3. Auto-detect bundle paths (if path contains : and doesn't look like a Windows drive letter)
Reproduction
# Fails - tilde not expanded
amplifier tool invoke recipes operation=validate recipe_path="~/dev/my-bundle/recipes/test.yaml"

# Fails - missing @ prefix (confusing)
amplifier tool invoke recipes operation=validate recipe_path="my-bundle:recipes/test.yaml"

# Works
amplifier tool invoke recipes operation=validate recipe_path="@my-bundle:recipes/test.yaml"
Suggested Fix

Minimal change to _resolve_path():

def _resolve_path(self, path_str: str) -> Path | None:
    """Resolve a path string, handling @mention syntax."""
    if path_str.startswith("@"):
        mention_resolver = self.coordinator.get_capability("mention_resolver")
        if mention_resolver is None:
            return None
        return mention_resolver.resolve(path_str)
    
    # Expand ~ to home directory
    return Path(path_str).expanduser()
Impact

This affects any user who:

  • Uses ~ in recipe paths (common pattern)
  • Forgets the @ prefix on bundle paths (easy mistake)

Both result in the same unhelpful error: "Recipe file not found: [path]"


Discovered while using amplifier-module-stories recipes

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at amplifier-bundle-recipes/.../amplifier_module_tool_recipes/init.py:344-359 and read _resolve_path(), then compare its handling of plain paths with @-prefixed bundle paths. Done means tilde-based recipe paths resolve correctly and the chosen behavior for bundle:path inputs is clear and covered by the tool's validation behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, tooling
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.