feat(extensions): scripts support, command filtering, and template discovery

[mbachorik]

Summary

Brings the extension system to parity with presets across three areas:

• Extension system: Add template type diversity (scripts support) #1847 — Scripts support: Extensions now accept provides.scripts alongside commands in the manifest. Includes name format validation (^[a-z0-9-]+$), path safety checks (no traversal), executable permissions on .sh files during install, and CLI display in extension list, extension add, and extension info.

• Extension system: Add extension filtering for ext-specific commands #1848 — Command filtering: Adds _filter_commands_for_installed_extensions() to CommandRegistrar — filters extension-specific commands (speckit.<ext-id>.<cmd>) against installed extension directories. Mirrors the preset filtering logic at presets.py:518-529. Available as a utility for cross-boundary filtering (e.g. when presets provide commands for extensions that may not be installed). Not applied during extension self-registration since all commands in an extension's own manifest are always valid.

• Extension system: Add template resolution system #1846 — Template resolution & discovery: Introduces ExtensionResolver — a dedicated class in extensions.py that owns extension template resolution, source attribution, and discovery. PresetResolver now delegates its tier-3 (extension) lookups to ExtensionResolver instead of walking extension directories directly. New specify preset list-templates --type <type> CLI command for template discovery across the full 4-tier stack.

Why ExtensionResolver instead of using PresetResolver?

The PresetResolver already had extension logic baked in (tier 3 of its resolution stack), but this meant extensions had to go through the preset system to discover their own templates — mixing concerns. ExtensionResolver gives extensions their own resolution/discovery API:

• resolve(name, type) — find a template from extensions
• resolve_with_source(name, type) — with source attribution
• list_templates(type) — discover all templates provided by extensions

PresetResolver remains the unified resolver across all 4 tiers (overrides → presets → extensions → core) but now delegates to ExtensionResolver for the extension tier rather than owning that logic directly. Each system owns its own domain.

Closes #1846, closes #1847, closes #1848

Test plan

• 843 tests pass (1 pre-existing failure in test_search_with_cached_data unrelated to this PR)
• Verify specify extension add with a scripts-only extension
• Verify specify preset list-templates outputs templates with correct source attribution
• Verify command filtering works when a preset provides commands for an uninstalled extension

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR extends Spec Kit’s extension and preset ecosystems to improve parity and discoverability: extensions can now declare scripts, commands can be filtered based on installed extensions, and presets gain a resolver-backed template discovery/listing command.

Changes:

• Add extension manifest + manager support for provides.scripts, including validation, install-time .sh executable bits, and CLI surface area (list/add/info).
• Introduce CommandRegistrar._filter_commands_for_installed_extensions() plus tests to filter speckit.<ext-id>.<cmd> commands when the target extension isn’t installed.
• Add PresetResolver.list_available() and a new specify preset list-templates --type <...> command, with template discovery tests.

Reviewed changes

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

Show a summary per file

File	Description
src/specify_cli/extensions.py	Adds scripts support to extension manifests/installs and introduces command filtering utility.
src/specify_cli/presets.py	Adds PresetResolver.list_available() for priority-stack template discovery with sources.
src/specify_cli/__init__.py	Adds preset list-templates CLI command and surfaces script counts in extension CLI output.
tests/test_extensions.py	Updates manifest validation tests and adds coverage for scripts support + command filtering utility.
tests/test_presets.py	Adds tests for PresetResolver.list_available() behavior (priority, sources, sorting).

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

src/specify_cli/extensions.py:160

• The commands/scripts validators assume each entry is a dict with string fields. If a manifest has provides.commands: ["foo"] or name/file values that aren’t strings, this will raise TypeError/KeyError (e.g., on cmd["name"] / regex) rather than a ValidationError. Validate isinstance(cmd, dict) and that name/file are strings before running regex/path checks.

        # Validate commands
        for cmd in commands:
            if "name" not in cmd or "file" not in cmd:
                raise ValidationError("Command missing 'name' or 'file'")

            # Validate command name format
            if not re.match(r'^speckit\.[a-z0-9-]+\.[a-z0-9-]+$', cmd["name"]):

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

ExtensionManifest validates that provides.scripts[*].file is relative and non-traversing, but it doesn’t enforce that the file name/extension matches the script name (or even that it ends in .sh/.ps1). Since ExtensionResolver.resolve(..., template_type='script') and list_templates('script') rely on {template_name}.sh|.ps1 naming, a manifest like name: setup + file: scripts/setup-v2.sh will install/list as setup but will never resolve/discover as setup. Consider validating that the script file is under scripts/ and that its stem equals script['name'] with an allowed suffix (.sh/.ps1) to keep manifest display, resolution, and discovery consistent.

Suggested change

	# Enforce resolver/discovery conventions:
	# - script files must live under "scripts/"
	# - file name stem must match the script name
	# - extension must be one of the allowed script types
	if not p.parts or p.parts[0] != "scripts":
	raise ValidationError(
	f"Invalid script file path '{file_path}': "
	"script files must be located under the 'scripts/' directory"
	)
	if p.suffix not in {".sh", ".ps1"}:
	raise ValidationError(
	f"Invalid script file path '{file_path}': "
	"script files must have a '.sh' or '.ps1' extension"
	)
	if p.stem != script["name"]:
	raise ValidationError(
	f"Invalid script file path '{file_path}': "
	f"file name (without extension) must match script name '{script['name']}'"
	)

[Copilot]

ExtensionResolver.list_templates() docstring promises results are sorted by extension priority then alphabetically, but the implementation returns templates in “scan order” (subdir order + filesystem order) and never sorts results before returning. This can produce non-alphabetical output for template type (because both templates/ and extension root are scanned). Either sort results (e.g., by (priority, name)) before returning or adjust the docstring to match the actual ordering guarantee.

[Copilot]

PresetResolver.resolve() still accepts unknown template_type values via the else: subdirs = [''] fallback, which means callers can accidentally resolve arbitrary *.md files from preset/extension roots. Since list_available() (and ExtensionResolver._type_config) now reject unsupported types, it would be more consistent (and safer) for resolve() to validate template_type against VALID_PRESET_TEMPLATE_TYPES and raise ValueError for invalid values.

Suggested change

	subdirs = [""]
	raise ValueError(f"Unsupported template_type: {template_type!r}")

[github-actions]

This pull request has been automatically marked as stale because it has not had any activity for 150 days. It will be closed in 30 days if no further activity occurs.