github/github-spec-kit
1
0
Fork 0
mirror of https://github.com/github/spec-kit.git synced 2026-07-06 14:01:01 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(extensions): per-event hook lists with priority ordering (#2798)

Browse Source 
* feat(extensions): per-event hook lists with priority ordering

The manifest validator restricted each hook event to a single mapping,
even though HookExecutor stores entries as a list per event. This blocked
an extension from running multiple commands on one event (e.g. a
verification step plus a doc-generation step after speckit.plan), and
get_hooks_for_event returned entries in raw insertion order with no way
to influence execution order across or within extensions.

This change:

1. Validator: accept hooks.<event> as either a single mapping or a list
   of mappings. Each entry is validated individually and may carry an
   optional integer `priority` (>= 1, default 10; bool rejected).
2. Command-ref normalization: apply rename / alias->canonical rewriting
   to every entry in the list, not just the head.
3. register_hooks: expand list entries, persist `priority`, and
   purge-and-replace all entries owned by the extension on each event so a
   reinstall whose shape changed (single<->list, or a shorter list) leaves
   no orphaned entries behind.
4. get_hooks_for_event: sort enabled entries by `priority` ascending with
   a stable sort (ties keep insertion order). The existing
   normalize_priority helper is reused as the sort key so corrupted
   on-disk values fall back to the default instead of raising.

Backward compatible: existing single-mapping manifests parse and register
unchanged with priority defaulting to 10. The extension-level `priority`
used by preset/template resolution is independent of the new hook-entry
`priority`.

Implements #2378

* fix(extensions): harden register_hooks per PR review

- Skip non-dict hook entries before .get() so a manifest that bypasses
  validation can't crash register_hooks with AttributeError.
- Normalize `priority` on save via normalize_priority so the on-disk
  config stays clean, mirroring the read-side defense in
  get_hooks_for_event.
- Tests: cover the non-dict-entry skip and add encoding="utf-8" to the
  new tests' manifest writes.

* fix(extensions): purge dropped-event hook orphans on reinstall

register_hooks only purged events the new manifest still declared, so an
extension that dropped an event on reinstall left stale entries for it in
the project config. Purge this extension's entries from undeclared events
(and prune emptied events) before registering; scoped to this extension,
and a no-op for the install/update flow where unregister_hooks runs first.

* fix(extensions): reject boolean priority and complete orphan purge

- normalize_priority falls back to default for bool values
- dedup deletes duplicate commands before re-insert for last-wins ties
- register_hooks purges orphans even when all hooks are dropped

* docs(extensions): document per-event hook lists and priority

- EXTENSION-API-REFERENCE: hook event accepts a mapping or list; add
  priority field reference and last-wins dedup note
- EXTENSION-DEVELOPMENT-GUIDE: add list-form example with priority

* docs(extensions): show both single and list hook forms in schema snippet

* docs(extensions): reference DEFAULT_HOOK_PRIORITY in normalize_priority

normalize_priority hard-coded the default as the literal 10 in both its
signature and docstring, duplicating DEFAULT_HOOK_PRIORITY. Reference the
constant in the signature and drop the literal from the docstring so the
default has a single source of truth.
This commit is contained in:
Seiya Kojima
2026-06-08 22:03:46 +09:00
committed by GitHub
parent 7106858c4e
commit 4ec4635dd1
5 changed files with 718 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
src/specify_cli/extensions.py
View File

@@ -41,6 +41,8 @@ _FALLBACK_CORE_COMMAND_NAMES = frozenset({
})
EXTENSION_COMMAND_NAME_PATTERN = re.compile(r"^speckit\.([a-z0-9-]+)\.([a-z0-9-]+)$")
DEFAULT_HOOK_PRIORITY = 10
REINSTALL_COMMAND = "uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git"
@@ -89,19 +91,21 @@ class CompatibilityError(ExtensionError):
pass
def normalize_priority(value: Any, default: int = 10) -> int:
def normalize_priority(value: Any, default: int = DEFAULT_HOOK_PRIORITY) -> int:
"""Normalize a stored priority value for sorting and display.
Corrupted registry data may contain missing, non-numeric, or non-positive
values. In those cases, fall back to the default priority.
Corrupted registry data may contain missing, non-numeric, non-positive, or
boolean values. In those cases, fall back to the default priority.
Args:
value: Priority value to normalize (may be int, str, None, etc.)
default: Default priority to use for invalid values (default: 10)
default: Default priority to use for invalid values
Returns:
Normalized priority as positive integer (>= 1)
"""
if isinstance(value, bool):
return default
try:
priority = int(value)
except (TypeError, ValueError):
@@ -109,6 +113,15 @@ def normalize_priority(value: Any, default: int = 10) -> int:
return priority if priority >= 1 else default
def coerce_hook_entries(hook_config: Any) -> List[Any]:
"""Return a hook event's config as a list of entries.
A hook event may be declared as a single mapping or a list of mappings.
Both shapes are normalized to a list so callers can iterate uniformly.
"""
return hook_config if isinstance(hook_config, list) else [hook_config]
@dataclass
class CatalogEntry(BaseCatalogEntry):
"""Represents a single catalog entry in the catalog stack."""
@@ -215,17 +228,36 @@ class ExtensionManifest:
"Extension must provide at least one command or hook"
)
# Validate hook values (if present)
# Validate hook values (if present).
# Each event is a single mapping or a list of mappings.
if hooks:
for hook_name, hook_config in hooks.items():
if not isinstance(hook_config, dict):
if isinstance(hook_config, list) and not hook_config:
raise ValidationError(
f"Invalid hook '{hook_name}': expected a mapping"
)
if not hook_config.get("command"):
raise ValidationError(
f"Hook '{hook_name}' missing required 'command' field"
f"Invalid hook '{hook_name}': list must contain at least one entry"
)
for entry in coerce_hook_entries(hook_config):
if not isinstance(entry, dict):
raise ValidationError(
f"Invalid hook '{hook_name}': "
"expected a mapping or list of mappings"
)
if not entry.get("command"):
raise ValidationError(
f"Hook '{hook_name}' missing required 'command' field"
)
if "priority" in entry:
priority = entry["priority"]
if not isinstance(priority, int) or isinstance(priority, bool):
raise ValidationError(
f"Hook '{hook_name}' has invalid 'priority': "
"must be an integer"
)
if priority < 1:
raise ValidationError(
f"Hook '{hook_name}' has invalid 'priority': "
"must be >= 1"
)
# Validate commands; track renames so hook references can be rewritten.
rename_map: Dict[str, str] = {}
@@ -275,28 +307,30 @@ class ExtensionManifest:
# an alias-form ref (ext.cmd → speckit.ext.cmd). Always emit a warning when
# the reference is changed so extension authors know to update the manifest.
for hook_name, hook_data in self.data.get("hooks", {}).items():
if not isinstance(hook_data, dict):
raise ValidationError(
f"Hook '{hook_name}' must be a mapping, got {type(hook_data).__name__}"
)
command_ref = hook_data.get("command")
if not isinstance(command_ref, str):
continue
# Step 1: apply any rename from the auto-correction pass.
after_rename = rename_map.get(command_ref, command_ref)
# Step 2: lift alias-form '{ext_id}.cmd' to canonical 'speckit.{ext_id}.cmd'.
parts = after_rename.split(".")
if len(parts) == 2 and parts[0] == ext["id"]:
final_ref = f"speckit.{ext['id']}.{parts[1]}"
else:
final_ref = after_rename
if final_ref != command_ref:
hook_data["command"] = final_ref
self.warnings.append(
f"Hook '{hook_name}' referenced command '{command_ref}'; "
f"updated to canonical form '{final_ref}'. "
f"The extension author should update the manifest."
)
for entry in coerce_hook_entries(hook_data):
if not isinstance(entry, dict):
raise ValidationError(
f"Hook '{hook_name}' must be a mapping or list of mappings, "
f"got {type(entry).__name__}"
)
command_ref = entry.get("command")
if not isinstance(command_ref, str):
continue
# Step 1: apply any rename from the auto-correction pass.
after_rename = rename_map.get(command_ref, command_ref)
# Step 2: lift alias-form '{ext_id}.cmd' to canonical 'speckit.{ext_id}.cmd'.
parts = after_rename.split(".")
if len(parts) == 2 and parts[0] == ext["id"]:
final_ref = f"speckit.{ext['id']}.{parts[1]}"
else:
final_ref = after_rename
if final_ref != command_ref:
entry["command"] = final_ref
self.warnings.append(
f"Hook '{hook_name}' referenced command '{command_ref}'; "
f"updated to canonical form '{final_ref}'. "
f"The extension author should update the manifest."
)
@staticmethod
def _try_correct_command_name(name: str, ext_id: str) -> Optional[str]:
@@ -2734,9 +2768,6 @@ class HookExecutor:
# Always ensure the extension is in the installed list
self.register_extension(manifest.id)
if not hasattr(manifest, "hooks") or not manifest.hooks:
return
config = self.get_project_config()
# Ensure config is a dict (defensive)
@@ -2762,39 +2793,68 @@ class HookExecutor:
config["hooks"][h_name] = sanitized_h_list
changed = True
# Purge this extension's entries from events the new manifest no longer
# declares, so dropping an event on reinstall leaves no orphans.
declared_events = set(manifest.hooks.keys())
for h_name in list(config["hooks"].keys()):
if h_name in declared_events:
continue
kept = [
h for h in config["hooks"][h_name]
if not (isinstance(h, dict) and h.get("extension") == manifest.id)
]
if kept != config["hooks"][h_name]:
config["hooks"][h_name] = kept
changed = True
# Register each hook
for hook_name, hook_config in manifest.hooks.items():
if hook_name not in config["hooks"] or not isinstance(config["hooks"][hook_name], list):
config["hooks"][hook_name] = []
changed = True
# Add hook entry
hook_entry = {
"extension": manifest.id,
"command": hook_config.get("command"),
"enabled": True,
"optional": hook_config.get("optional", True),
"prompt": hook_config.get(
"prompt", f"Execute {hook_config.get('command')}?"
),
"description": hook_config.get("description", ""),
"condition": hook_config.get("condition"),
}
# Key by command to dedup within the manifest. Deleting before
# re-insert moves a duplicate to the end so "last wins" also breaks ties.
new_entries: Dict[str, Dict[str, Any]] = {}
for entry in coerce_hook_entries(hook_config):
if not isinstance(entry, dict):
continue
command = entry.get("command")
if not command:
continue
if command in new_entries:
del new_entries[command]
new_entries[command] = {
"extension": manifest.id,
"command": command,
"enabled": True,
"optional": entry.get("optional", True),
"priority": normalize_priority(
entry.get("priority"), DEFAULT_HOOK_PRIORITY
),
"prompt": entry.get("prompt", f"Execute {command}?"),
"description": entry.get("description", ""),
"condition": entry.get("condition"),
}
# Deduplicate: remove all existing entries for this extension on this
# hook event, then append the single canonical entry. This prevents
# multiple hooks firing when hand-edited or older versions leave
# duplicate entries behind. (Feedback from review)
# Purge then re-add all of this extension's entries for the event.
# A reinstall with a changed shape (single<->list or a shorter list)
# then leaves no orphaned entries behind.
original_list = config["hooks"][hook_name]
deduped = [
h for h in original_list
if not (isinstance(h, dict) and h.get("extension") == manifest.id)
]
deduped.append(hook_entry)
deduped.extend(new_entries.values())
if deduped != original_list:
config["hooks"][hook_name] = deduped
changed = True
non_empty = {name: hooks for name, hooks in config["hooks"].items() if hooks}
if non_empty != config["hooks"]:
config["hooks"] = non_empty
changed = True
if changed:
self.save_project_config(config)
@@ -2838,19 +2898,26 @@ class HookExecutor:
self.save_project_config(config)
def get_hooks_for_event(self, event_name: str) -> List[Dict[str, Any]]:
"""Get all registered hooks for a specific event.
"""Get all enabled hooks for a specific event, sorted by priority ascending.
Lower ``priority`` runs first. Ties keep insertion order via a stable
sort. Missing or corrupted on-disk priorities fall back to the default.
Args:
event_name: Name of the event (e.g., 'after_tasks')
Returns:
List of hook configurations
List of enabled hook configurations sorted by priority.
"""
config = self.get_project_config()
hooks = config.get("hooks", {}).get(event_name, [])
# Filter to enabled hooks only
return [h for h in hooks if h.get("enabled", True)]
enabled = [h for h in hooks if h.get("enabled", True)]
return sorted(
enabled,
key=lambda h: normalize_priority(h.get("priority"), DEFAULT_HOOK_PRIORITY),
)
def should_execute_hook(self, hook: Dict[str, Any]) -> bool:
"""Determine if a hook should be executed based on its condition.