Skip to content

Commit 0a70e5b

Browse files
authored
feat(presets): let a preset declare a required extension (#4250)
* feat(presets): let a preset declare a required extension A preset whose command overrides call into an extension is inert without it, but the overrides fall through to the core workflow, so nothing errors -- the feature just silently does less than the user expects. Until now the only place that dependency could be stated was the README, which fails exactly the user who did not read it. Add an optional requires.extensions to preset.yml, accepting either a bare extension id or a mapping with an optional version specifier and an optional required flag. Validation mirrors the requires.speckit_version strictness from #3980: a non-list, a member that is neither string nor mapping, a missing or malformed id, a non-string or unparseable version, and a non-boolean required each raise PresetValidationError rather than surfacing later as a bare TypeError from re.match or SpecifierSet. On `specify preset add`, warn once for each unsatisfied dependency, naming the extension and the command that installs it. The check runs at the single point where the --dev, --from, and catalog paths converge, so all three behave the same. It warns rather than fails: these presets are written to degrade safely, and three catalog entries already declare the dependency, so failing would break installs that work today. The field is optional, so every existing preset stays valid and silent. Closes #4231 Assisted-by: Claude Code (model: Claude Opus 5, autonomous) * fix(presets): match dependency remediation to the reason, and flag disabled Addresses review feedback on #4250. `specify extension add <id>` refuses an already-installed extension without --force, so suggesting it for a version mismatch handed the user a command that could only fail. Suggest `extension update` for a version mismatch and `extension enable` for a disabled one, keeping `add` for a genuinely missing extension. A disabled extension was also treated as satisfied, because the registry entry exists. Resolution skips disabled extensions, so the preset stays exactly as inert as if the extension were absent, with no warning to explain it. Report it as a distinct "disabled" reason, ahead of any version check -- enabling is the prerequisite, and the version may be fine once it is. Also correct the closing line, which said the extensions "will do nothing until they are present" -- inaccurate for a disabled extension, which is present. Assisted-by: Claude Code (model: Claude Opus 5, autonomous) * fix(presets): avoid promising unsatisfiable extension updates Assisted-by: ChatGPT (model: GPT-5, supervised) * docs(presets): describe requires.extensions version as a full constraint Addresses review feedback on #4250. The guide said a mapping was for "a version floor", but the field accepts any PEP 440 specifier, so upper bounds, exact pins, and exclusions were all undocumented. Say "version constraint", show a bounded range in the example, and state the accepted forms explicitly. Two adjacent claims had also drifted from the behaviour and are corrected in the same pass. The guide promised the warning would "name the command that fixes it", which stopped being true for a version mismatch once that case began stating the constraint instead of naming a command that cannot satisfy every specifier. And the notes listed only missing and version-unsatisfied dependencies as warned about, never mentioning disabled ones. Assisted-by: Claude Code (model: Claude Opus 5, autonomous) * fix(presets): treat stale entries as unmet and unparseable versions as uncomparable Addresses review feedback on #4250. A registry entry is not proof the extension can contribute. When the entry survives after .specify/extensions/<id> is removed, PresetResolver skips the extension outright -- both template lookup and layer collection guard on is_dir() -- so the preset is as inert as if it were never installed, while the surviving entry read as satisfied. Report that state as a distinct "stale" reason, ahead of the disabled and version checks, and remediate it with a forced reinstall rather than a plain add. The uncomparable-version guard also only covered non-string values. An unparseable string such as "unknown" passed it and reached version_satisfies(), which catches InvalidVersion and returns False -- reporting a mismatch against a version that was never actually evaluated, and contradicting the documented behaviour that unusable versions are not invented into mismatches. Check parseability before comparing so only real comparisons reach the warning. The test helper now creates the extension directory alongside the registry entry, matching what the installer does, with an opt-out for the stale case. Assisted-by: Claude Code (model: Claude Opus 5, autonomous) * fix(presets): treat an unregistered extension directory as satisfied Addresses review feedback on #4250. An absent registry entry was reported as a missing dependency, but it does not mean the extension is unusable. _get_all_extensions_by_priority() admits a safe on-disk directory as an unregistered extension at implicit priority 10, so its artifacts resolve and the preset works -- the warning was a false alarm telling users to install something already in use. Treat a matching directory as present, guarded the same way resolution guards itself: the id must be a safe registry id, and the registry must not be corrupt, since a corrupt one makes that path fail closed and contribute nothing. An unregistered extension has no recorded version, so a declared constraint is uncomparable rather than unsatisfied. This is the mirror of the stale case in the previous commit. Between them, the check now agrees with resolution in both directions: an entry without files is unmet, and files without an entry are satisfied. Assisted-by: Claude Code (model: Claude Opus 5, autonomous) * fix(presets): exclude corrupted registry ids and flag discovery-only installs Addresses review feedback on #4250. ExtensionRegistry.get() returns None for a corrupted (non-dict) entry exactly as it does for an absent one, so a corrupted entry whose directory survived reached the unregistered-directory fallback and was reported satisfied. keys() deliberately retains corrupted ids precisely so resolution does not re-admit those directories, so the fallback now requires the id to be absent from keys() -- it can no longer revive what resolution excludes. is_corrupt() does not cover this, as it validates only the registry container. `extension add <id>` resolves through the catalogs, and the default community catalog is discovery-only, so installing by id is rejected for anything listed only there. That covers all three extensions this feature exists to serve -- aide, mde, and speckit-inventory -- meaning the first live warnings would have pointed at a command that exits 1. Note the --from <archive-url> form once, after the list, for the two reasons that suggest an install by id. Determining discovery-only status per dependency would mean a catalog fetch inside `preset add`, so the note is unconditional rather than risking a network call on an install path that has never needed one. Assisted-by: Claude Code (model: Claude Opus 5, autonomous) * fix(presets): keep leading-hyphen ids out of suggested extension commands Addresses review feedback on #4250. `^[a-z0-9-]+$` admits a leading hyphen, so a dependency id such as `--force` produced `specify extension add --force`. Typer parses that as an option rather than the positional extension argument, so the advertised fix could not run at all -- and the stale, disabled, and version remedies had the same flaw. Reuse _command_safe_id from the extensions commands, which already rejects a leading hyphen and falls back to a `<extension-id>` placeholder, rather than adding a second implementation of the same rule that could drift from it. The displayed id keeps plain Rich escaping, since only the copyable command needs to survive the parser. Assisted-by: Claude Code (model: Claude Opus 5, autonomous) * fix(presets): report corrupt entries, survive an unreadable registry, correct the footer Addresses review feedback on #4250, plus two issues found while self-reviewing the same code. ExtensionRegistry construction can raise OSError -- _load() recovers from malformed content but deliberately lets OSError through, and is_corrupt() re-reads the file. This check runs after the install has already completed and preset_add handles only preset-domain errors, so an unreadable registry turned a finished install into a traceback over what is only a warning. An unreadable registry now yields no results instead. A corrupted entry was conflated with an absent one. get() returns None for both, but is_installed() still counts the key, so the suggested `extension add <id>` is refused as already installed. It is now a distinct "corrupt" reason remediated with a forced reinstall. The closing note asserted that dependent features "will do nothing" and that the preset is "safe to use". Neither holds for a version mismatch: the extension is installed and enabled, so the preset does invoke it, and the combination is untested against the declared constraint rather than safe. The note is now split by consequence. Found while self-reviewing, in the same two areas this review keeps surfacing: the id pattern used re.match with an anchored `^...$`, but `$` also matches before a trailing newline, so "demo-ext\n" validated here while PresetResolver._is_safe_registry_id (fullmatch) rejects it, and the newline would have reached a printed command. And declaring one dependency twice warned twice; exact repeats now collapse, while two entries for one id with different constraints are still both checked, since both have to hold. Assisted-by: Claude Code (model: Claude Opus 5, autonomous) * fix(presets): stop advertising a bare-id install as a guaranteed fix Addresses review feedback on #4250. The per-dependency line labelled `specify extension add <id>` as "Fix with", while the closing note said an archive URL is required -- the remedy and the note contradicted each other, and for every extension motivating this feature the bare-id command is refused outright, since all three are listed only in the discovery-only community catalog. Label the remedy by the action it performs rather than asserting it fixes the problem: "Install with", "Reinstall with", "Enable with", and "Needs" for a version constraint, which was never a command in the first place. Replace the contradictory note with what actually happens. The discovery-only rejection prints the exact `--from <archive-url>` invocation to use, so the bare command is a signpost rather than a dead end, and saying so is both accurate and useful. Determining which catalog an extension came from would require a catalog fetch on an install path that touches no network, so the note stays unconditional and is now only emitted when a suggested command actually resolves through the catalogs. Assisted-by: Claude Code (model: Claude Opus 5, autonomous)
1 parent d4ba753 commit 0a70e5b

4 files changed

Lines changed: 1019 additions & 0 deletions

File tree

‎presets/PUBLISHING.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,8 @@ preset:
6868

6969
requires:
7070
speckit_version: ">=0.1.0" # Required spec-kit version
71+
extensions: # Optional: extensions this preset needs
72+
- "companion-extension"
7173

7274
provides:
7375
templates:
@@ -93,6 +95,41 @@ tags: # 2-5 relevant tags
9395
- ✅ Command names use dot notation (e.g. `speckit.specify`)
9496
- ✅ Tags are lowercase and descriptive
9597

98+
#### Declaring extension dependencies
99+
100+
If your preset overrides commands that call into an extension, declare it in
101+
`requires.extensions`. Without the extension the preset still installs and the
102+
overrides fall through to the core workflow, so nothing errors — the feature
103+
just silently does less than the user expects. Declaring the dependency makes
104+
`specify preset add` say so, and spell out how to resolve it.
105+
106+
Use a bare id, or a mapping when you need a version constraint or an optional
107+
dependency:
108+
109+
```yaml
110+
requires:
111+
speckit_version: ">=0.9.0"
112+
extensions:
113+
- "companion-extension" # required, any version
114+
- id: "other-extension"
115+
version: ">=1.2.0,<2" # optional PEP 440 specifier
116+
required: false # optional, defaults to true
117+
```
118+
119+
`version` accepts any PEP 440 specifier, not just a lower bound — upper bounds
120+
(`<2`), exact pins (`==1.2.0`), and exclusions (`!=1.3.0`) all work.
121+
122+
Notes:
123+
124+
- The field is optional. A preset that declares nothing behaves exactly as before.
125+
- A dependency that is missing, stale, disabled, or version-unsatisfied produces a **warning, not a failure** — the install still succeeds.
126+
- A disabled extension counts as unmet, and so does one whose registry entry survives after its files were removed. Resolution skips both, so the preset is just as inert as if the extension were absent.
127+
- The warning names an exact command for the missing, stale, and disabled cases. For a version mismatch it states the constraint to satisfy rather than naming a command, because `specify extension update` only moves forward to the catalog release and cannot satisfy an upper bound, a pin, or a downgrade.
128+
- A recorded version that cannot be parsed is treated as uncomparable rather than as a mismatch, so an extension whose registry version reads `unknown` is not reported as failing a constraint it was never evaluated against.
129+
- An extension present on disk but absent from the registry counts as satisfied. Resolution admits unregistered directories, so the preset works and warning about it would be a false alarm — though with no recorded version, a `version` constraint cannot be checked against it.
130+
- `required: false` documents an enhancing-but-optional extension and is never warned about.
131+
- Declare it in `preset.yml`, not only in your catalog entry. The catalog is not consulted for `--dev` and `--from <url>` installs, so the manifest is the only copy present on every install path.
132+
96133
### 3. Test Locally
97134

98135
```bash

‎src/specify_cli/presets/__init__.py‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,20 @@ def _content_sha256(content: bytes) -> str:
6363
return hashlib.sha256(content).hexdigest()
6464

6565

66+
def _is_comparable_version(value: str) -> bool:
67+
"""Return whether a recorded version can be evaluated against a specifier.
68+
69+
``version_satisfies()`` answers "does not satisfy" for an unparseable
70+
version, which is indistinguishable from a genuine mismatch. Callers that
71+
need to tell those apart check here first.
72+
"""
73+
try:
74+
pkg_version.Version(value)
75+
except pkg_version.InvalidVersion:
76+
return False
77+
return True
78+
79+
6680
def _constitution_is_generated(
6781
project_root: Path,
6882
memory_constitution: Path,
@@ -381,6 +395,14 @@ def _validate(self):
381395
f"got {type(requires['speckit_version']).__name__}"
382396
)
383397

398+
# Validate the optional extension dependency list. A preset that
399+
# overrides commands calling into an extension is inert without it, and
400+
# until now the only place that could be said was the README -- see
401+
# issue #4231. Absent means "no dependencies", so every existing preset
402+
# stays valid.
403+
if "extensions" in requires:
404+
self._validate_requires_extensions(requires["extensions"])
405+
384406
# Validate provides section
385407
provides = self.data["provides"]
386408
if "templates" not in provides:
@@ -524,11 +546,121 @@ def author(self) -> str:
524546
"""Get preset author."""
525547
return self.data["preset"].get("author", "")
526548

549+
@staticmethod
550+
def _validate_requires_extensions(declared: Any) -> None:
551+
"""Validate the optional ``requires.extensions`` list.
552+
553+
Accepts either a bare extension id or a mapping carrying an optional
554+
version specifier and an optional ``required`` flag:
555+
556+
.. code-block:: yaml
557+
558+
requires:
559+
extensions:
560+
- speckit-inventory
561+
- id: other-ext
562+
version: ">=1.2.0"
563+
required: false
564+
565+
Raises:
566+
PresetValidationError: If the list or any entry is malformed.
567+
"""
568+
if not isinstance(declared, list):
569+
raise PresetValidationError(
570+
"Invalid requires.extensions: expected a list, "
571+
f"got {type(declared).__name__}"
572+
)
573+
574+
for index, entry in enumerate(declared):
575+
label = f"requires.extensions[{index}]"
576+
577+
if isinstance(entry, str):
578+
entry = {"id": entry}
579+
elif not isinstance(entry, dict):
580+
raise PresetValidationError(
581+
f"Invalid {label}: expected a string or a mapping, "
582+
f"got {type(entry).__name__}"
583+
)
584+
585+
if "id" not in entry:
586+
raise PresetValidationError(f"Missing {label}.id")
587+
extension_id = entry["id"]
588+
if not isinstance(extension_id, str):
589+
raise PresetValidationError(
590+
f"Invalid {label}.id: expected a string, "
591+
f"got {type(extension_id).__name__}"
592+
)
593+
# Same id shape the extension loader enforces, so a dependency can
594+
# never name something that could not be installed in the first
595+
# place. fullmatch rather than match with an anchored pattern: `$`
596+
# also matches before a trailing newline, so "demo-ext\n" would
597+
# otherwise validate here while PresetResolver._is_safe_registry_id
598+
# (which uses fullmatch) rejects it, and the newline would land in
599+
# a suggested command.
600+
if not re.fullmatch(r'[a-z0-9-]+', extension_id):
601+
raise PresetValidationError(
602+
f"Invalid {label}.id {extension_id!r}: "
603+
"must be lowercase alphanumeric with hyphens only"
604+
)
605+
606+
if "version" in entry:
607+
constraint = entry["version"]
608+
# Mirrors the requires.speckit_version reasoning: a non-string
609+
# escapes InvalidSpecifier two ways -- scalars raise TypeError
610+
# from the constructor, and a list/dict is iterable so it
611+
# constructs and only fails later inside .contains().
612+
if not isinstance(constraint, str) or not constraint.strip():
613+
raise PresetValidationError(
614+
f"Invalid {label}.version: expected a non-empty string, "
615+
f"got {type(constraint).__name__}"
616+
)
617+
try:
618+
SpecifierSet(constraint)
619+
except InvalidSpecifier:
620+
raise PresetValidationError(
621+
f"Invalid {label}.version '{constraint}': "
622+
"not a valid version specifier"
623+
)
624+
625+
if "required" in entry and not isinstance(entry["required"], bool):
626+
raise PresetValidationError(
627+
f"Invalid {label}.required: expected a boolean, "
628+
f"got {type(entry['required']).__name__}"
629+
)
630+
527631
@property
528632
def requires_speckit_version(self) -> str:
529633
"""Get required spec-kit version range."""
530634
return self.data["requires"]["speckit_version"]
531635

636+
@property
637+
def requires_extensions(self) -> List[Dict[str, Any]]:
638+
"""Get declared extension dependencies, normalized to mappings.
639+
640+
Returns:
641+
One entry per dependency with ``id``, ``version`` (``None`` when
642+
unconstrained), and ``required`` (defaulting to ``True``). Empty
643+
when the manifest declares no dependencies.
644+
"""
645+
declared = self.data["requires"].get("extensions")
646+
if not isinstance(declared, list):
647+
return []
648+
649+
normalized: List[Dict[str, Any]] = []
650+
for entry in declared:
651+
if isinstance(entry, str):
652+
entry = {"id": entry}
653+
if not isinstance(entry, dict) or not isinstance(entry.get("id"), str):
654+
continue
655+
normalized.append(
656+
{
657+
"id": entry["id"],
658+
"version": entry.get("version"),
659+
"required": entry.get("required", True),
660+
}
661+
)
662+
return normalized
663+
532664
@property
533665
def templates(self) -> List[Dict[str, Any]]:
534666
"""Get list of provided templates."""
@@ -841,6 +973,153 @@ def check_compatibility(
841973

842974
return True
843975

976+
def find_unmet_extension_dependencies(
977+
self,
978+
manifest: PresetManifest
979+
) -> List[Dict[str, Any]]:
980+
"""Find declared extension dependencies that are not satisfied.
981+
982+
Reports rather than raises. A preset whose overrides call into an
983+
extension is written to degrade safely -- without the extension the
984+
core workflow still runs -- so a missing dependency is a warning, not
985+
an install failure. See issue #4231.
986+
987+
Args:
988+
manifest: Preset manifest to inspect
989+
990+
Returns:
991+
One entry per unsatisfied dependency, each with ``id``, the
992+
requested ``version`` specifier (``None`` when unconstrained), the
993+
``installed`` version (``None`` when absent or unusable), and a
994+
``reason`` of ``"missing"``, ``"corrupt"``, ``"stale"``,
995+
``"disabled"``, or ``"version"``. Optional dependencies
996+
(``required: false``) are never reported.
997+
998+
An unreadable registry yields no results rather than raising, since
999+
this runs after the install has already succeeded.
1000+
1001+
A registry version that cannot be parsed is treated as
1002+
uncomparable, not as a mismatch: the extension is installed and
1003+
usable, and only its recorded version is unreadable. An extension
1004+
present on disk but absent from the registry is likewise treated as
1005+
satisfied, because resolution admits unregistered directories.
1006+
"""
1007+
# Defense in depth, mirroring check_compatibility(): this method is
1008+
# public and also reachable with a hand-built manifest object that
1009+
# predates this field. A manifest without it declares nothing.
1010+
candidates = getattr(manifest, "requires_extensions", None)
1011+
if not isinstance(candidates, list):
1012+
return []
1013+
1014+
# Collapse exact repeats so a manifest naming the same dependency twice
1015+
# warns once. Two entries for one id with *different* constraints are
1016+
# kept, since both genuinely have to hold.
1017+
declared: List[Dict[str, Any]] = []
1018+
seen: Set[tuple] = set()
1019+
for dep in candidates:
1020+
if not isinstance(dep, dict) or not dep.get("required", True):
1021+
continue
1022+
key = (dep.get("id"), dep.get("version"))
1023+
if key in seen:
1024+
continue
1025+
seen.add(key)
1026+
declared.append(dep)
1027+
if not declared:
1028+
return []
1029+
1030+
extensions_dir = self.project_root / ".specify" / "extensions"
1031+
try:
1032+
registry = ExtensionRegistry(extensions_dir)
1033+
registered_ids = registry.keys()
1034+
registry_corrupt = registry.is_corrupt()
1035+
except OSError:
1036+
# Both reads can raise: _load() recovers from malformed content but
1037+
# deliberately lets OSError through, and is_corrupt() re-reads the
1038+
# file. This check runs *after* the install has completed, and
1039+
# preset_add only handles preset-domain errors, so letting that
1040+
# escape would turn a finished install into a traceback over a
1041+
# warning. An unreadable registry simply cannot be inspected.
1042+
return []
1043+
1044+
unmet: List[Dict[str, Any]] = []
1045+
1046+
for dep in declared:
1047+
metadata = registry.get(dep["id"])
1048+
if metadata is None:
1049+
# An absent registry entry does not mean the extension is
1050+
# unusable. _get_all_extensions_by_priority() admits a safe
1051+
# on-disk directory as an unregistered extension at implicit
1052+
# priority 10, so it resolves and the preset works -- but only
1053+
# when the registry is readable, since a corrupt one makes that
1054+
# path fail closed and contribute nothing.
1055+
#
1056+
# get() returns None for a corrupted (non-dict) entry as well as
1057+
# an absent one, but keys() retains corrupted ids -- both so
1058+
# resolution does not re-admit their directories as
1059+
# unregistered, and because is_installed() still counts them, so
1060+
# a plain `extension add` would be refused as already installed.
1061+
# That is a different state from absent, and needs a different
1062+
# remedy.
1063+
if dep["id"] in registered_ids:
1064+
unmet.append({**dep, "installed": None, "reason": "corrupt"})
1065+
continue
1066+
if (
1067+
(extensions_dir / dep["id"]).is_dir()
1068+
and PresetResolver._is_safe_registry_id(dep["id"])
1069+
and not registry_corrupt
1070+
):
1071+
# Unregistered means no recorded version, so a constraint
1072+
# cannot be evaluated -- uncomparable, not unsatisfied.
1073+
continue
1074+
unmet.append({**dep, "installed": None, "reason": "missing"})
1075+
continue
1076+
1077+
installed_version = metadata.get("version")
1078+
installed_version = (
1079+
installed_version if isinstance(installed_version, str) else None
1080+
)
1081+
1082+
# A registry entry is not proof the extension can contribute. If
1083+
# its directory is gone, PresetResolver skips it outright (both
1084+
# template lookup and layer collection guard on ``is_dir()``), so
1085+
# the preset is as inert as if it were never installed -- but the
1086+
# surviving entry would otherwise read as satisfied.
1087+
if not (extensions_dir / dep["id"]).is_dir():
1088+
unmet.append(
1089+
{**dep, "installed": installed_version, "reason": "stale"}
1090+
)
1091+
continue
1092+
1093+
# A disabled extension is registered but contributes nothing:
1094+
# resolution skips it (see _collect_extension_layers), so the
1095+
# preset is just as inert as if it were absent. Report it before
1096+
# any version check -- enabling it is the prerequisite, and the
1097+
# version may well be fine once it is.
1098+
if not metadata.get("enabled", True):
1099+
unmet.append(
1100+
{**dep, "installed": installed_version, "reason": "disabled"}
1101+
)
1102+
continue
1103+
1104+
constraint = dep["version"]
1105+
if not constraint:
1106+
continue
1107+
1108+
# A version that cannot be compared is not a mismatch. Absent or
1109+
# non-string is one way to be unusable; an unparseable string such
1110+
# as "unknown" is another, and version_satisfies() cannot tell them
1111+
# apart -- it catches InvalidVersion and returns False, which would
1112+
# report a mismatch against a version nobody can evaluate. Check
1113+
# parseability up front so only real comparisons reach the warning.
1114+
if installed_version is None or not _is_comparable_version(installed_version):
1115+
continue
1116+
if not version_satisfies(installed_version, constraint):
1117+
unmet.append(
1118+
{**dep, "installed": installed_version, "reason": "version"}
1119+
)
1120+
1121+
return unmet
1122+
8441123
def _register_commands(
8451124
self,
8461125
manifest: PresetManifest,

0 commit comments

Comments
 (0)