mirror of
https://github.com/github/spec-kit.git
synced 2026-07-06 05:53:12 +08:00
feat(extensions): per-event hook lists with priority ordering (#2798)
* 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
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user