Improved support for path templates

[rsgalloway]

This pull request significantly refactors and extends the envstack.path module to improve path template handling, environment variable expansion, and template matching. The changes introduce more robust and flexible functions for loading templates, converting paths between platforms, and extracting or matching template fields. Several convenience functions are enhanced to allow for more explicit stack, platform, and scope selection, and error handling is improved throughout.

Enhancements to path template handling and environment variable expansion:

• Added _escape_env_vars and _expand_env_vars helpers to properly handle and expand environment variables within template strings, allowing for both literal and expanded usage as needed. [1] [2]
• Improved the get_template and match_template functions to explicitly load and resolve environment stacks, expand variables, and allow for stack, platform, and scope overrides. [1] [2]

Refactoring and API improvements:

• Refactored the Path class to support more robust platform conversion via the new to_platform method, which loads environment stacks for both source and target platforms and replaces root directories accordingly.
• Simplified and clarified the Template class and its methods, including apply_fields (now returns a Path), and improved error handling in get_fields. [1] [2] [3] [4]

Convenience and utility function improvements:

• Updated extract_fields, get_scope, and related utilities to use the new stack-aware APIs and provide better error reporting.
• Introduced _iter_template_items for heuristically discovering likely path templates in an environment, making template matching more flexible and not reliant on a special namespace.

Configuration and environment changes:

• Added a new NUKESCRIPT path template to the test environment file for demonstration and testing.

These changes make the path template system more powerful, extensible, and easier to use in multi-platform, stack-based environments.

[Copilot]

Pull request overview

This PR refactors envstack.path to improve template lookup/matching and environment-variable expansion by loading and using resolved envstack stacks, and adds new tests and an example template entry.

Changes:

• Added stack-aware helpers for env-var escaping/expansion and resolved stack loading; updated get_template() and match_template() accordingly.
• Refactored Path/Template APIs (notably Path.to_platform() and Template.apply_fields() returning Path) and updated convenience helpers like extract_fields().
• Added tests/test_path.py coverage for the new template resolution/matching behavior and a NUKESCRIPT example template.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
lib/envstack/path.py	Major refactor: resolved-stack loading, env-var expansion/escaping, updated template matching and platform conversion APIs.
tests/test_path.py	New unit tests covering template expansion, matching specificity, field extraction, and platform root rewriting.
examples/default/test.env	Adds a NUKESCRIPT example path template for demonstration/testing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.