Repository navigation
Commit 0a70e5b
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
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
68 | 68 | | |
69 | 69 | | |
70 | 70 | | |
| 71 | + | |
| 72 | + | |
71 | 73 | | |
72 | 74 | | |
73 | 75 | | |
| |||
93 | 95 | | |
94 | 96 | | |
95 | 97 | | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
96 | 133 | | |
97 | 134 | | |
98 | 135 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
63 | 63 | | |
64 | 64 | | |
65 | 65 | | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
66 | 80 | | |
67 | 81 | | |
68 | 82 | | |
| |||
381 | 395 | | |
382 | 396 | | |
383 | 397 | | |
| 398 | + | |
| 399 | + | |
| 400 | + | |
| 401 | + | |
| 402 | + | |
| 403 | + | |
| 404 | + | |
| 405 | + | |
384 | 406 | | |
385 | 407 | | |
386 | 408 | | |
| |||
524 | 546 | | |
525 | 547 | | |
526 | 548 | | |
| 549 | + | |
| 550 | + | |
| 551 | + | |
| 552 | + | |
| 553 | + | |
| 554 | + | |
| 555 | + | |
| 556 | + | |
| 557 | + | |
| 558 | + | |
| 559 | + | |
| 560 | + | |
| 561 | + | |
| 562 | + | |
| 563 | + | |
| 564 | + | |
| 565 | + | |
| 566 | + | |
| 567 | + | |
| 568 | + | |
| 569 | + | |
| 570 | + | |
| 571 | + | |
| 572 | + | |
| 573 | + | |
| 574 | + | |
| 575 | + | |
| 576 | + | |
| 577 | + | |
| 578 | + | |
| 579 | + | |
| 580 | + | |
| 581 | + | |
| 582 | + | |
| 583 | + | |
| 584 | + | |
| 585 | + | |
| 586 | + | |
| 587 | + | |
| 588 | + | |
| 589 | + | |
| 590 | + | |
| 591 | + | |
| 592 | + | |
| 593 | + | |
| 594 | + | |
| 595 | + | |
| 596 | + | |
| 597 | + | |
| 598 | + | |
| 599 | + | |
| 600 | + | |
| 601 | + | |
| 602 | + | |
| 603 | + | |
| 604 | + | |
| 605 | + | |
| 606 | + | |
| 607 | + | |
| 608 | + | |
| 609 | + | |
| 610 | + | |
| 611 | + | |
| 612 | + | |
| 613 | + | |
| 614 | + | |
| 615 | + | |
| 616 | + | |
| 617 | + | |
| 618 | + | |
| 619 | + | |
| 620 | + | |
| 621 | + | |
| 622 | + | |
| 623 | + | |
| 624 | + | |
| 625 | + | |
| 626 | + | |
| 627 | + | |
| 628 | + | |
| 629 | + | |
| 630 | + | |
527 | 631 | | |
528 | 632 | | |
529 | 633 | | |
530 | 634 | | |
531 | 635 | | |
| 636 | + | |
| 637 | + | |
| 638 | + | |
| 639 | + | |
| 640 | + | |
| 641 | + | |
| 642 | + | |
| 643 | + | |
| 644 | + | |
| 645 | + | |
| 646 | + | |
| 647 | + | |
| 648 | + | |
| 649 | + | |
| 650 | + | |
| 651 | + | |
| 652 | + | |
| 653 | + | |
| 654 | + | |
| 655 | + | |
| 656 | + | |
| 657 | + | |
| 658 | + | |
| 659 | + | |
| 660 | + | |
| 661 | + | |
| 662 | + | |
| 663 | + | |
532 | 664 | | |
533 | 665 | | |
534 | 666 | | |
| |||
841 | 973 | | |
842 | 974 | | |
843 | 975 | | |
| 976 | + | |
| 977 | + | |
| 978 | + | |
| 979 | + | |
| 980 | + | |
| 981 | + | |
| 982 | + | |
| 983 | + | |
| 984 | + | |
| 985 | + | |
| 986 | + | |
| 987 | + | |
| 988 | + | |
| 989 | + | |
| 990 | + | |
| 991 | + | |
| 992 | + | |
| 993 | + | |
| 994 | + | |
| 995 | + | |
| 996 | + | |
| 997 | + | |
| 998 | + | |
| 999 | + | |
| 1000 | + | |
| 1001 | + | |
| 1002 | + | |
| 1003 | + | |
| 1004 | + | |
| 1005 | + | |
| 1006 | + | |
| 1007 | + | |
| 1008 | + | |
| 1009 | + | |
| 1010 | + | |
| 1011 | + | |
| 1012 | + | |
| 1013 | + | |
| 1014 | + | |
| 1015 | + | |
| 1016 | + | |
| 1017 | + | |
| 1018 | + | |
| 1019 | + | |
| 1020 | + | |
| 1021 | + | |
| 1022 | + | |
| 1023 | + | |
| 1024 | + | |
| 1025 | + | |
| 1026 | + | |
| 1027 | + | |
| 1028 | + | |
| 1029 | + | |
| 1030 | + | |
| 1031 | + | |
| 1032 | + | |
| 1033 | + | |
| 1034 | + | |
| 1035 | + | |
| 1036 | + | |
| 1037 | + | |
| 1038 | + | |
| 1039 | + | |
| 1040 | + | |
| 1041 | + | |
| 1042 | + | |
| 1043 | + | |
| 1044 | + | |
| 1045 | + | |
| 1046 | + | |
| 1047 | + | |
| 1048 | + | |
| 1049 | + | |
| 1050 | + | |
| 1051 | + | |
| 1052 | + | |
| 1053 | + | |
| 1054 | + | |
| 1055 | + | |
| 1056 | + | |
| 1057 | + | |
| 1058 | + | |
| 1059 | + | |
| 1060 | + | |
| 1061 | + | |
| 1062 | + | |
| 1063 | + | |
| 1064 | + | |
| 1065 | + | |
| 1066 | + | |
| 1067 | + | |
| 1068 | + | |
| 1069 | + | |
| 1070 | + | |
| 1071 | + | |
| 1072 | + | |
| 1073 | + | |
| 1074 | + | |
| 1075 | + | |
| 1076 | + | |
| 1077 | + | |
| 1078 | + | |
| 1079 | + | |
| 1080 | + | |
| 1081 | + | |
| 1082 | + | |
| 1083 | + | |
| 1084 | + | |
| 1085 | + | |
| 1086 | + | |
| 1087 | + | |
| 1088 | + | |
| 1089 | + | |
| 1090 | + | |
| 1091 | + | |
| 1092 | + | |
| 1093 | + | |
| 1094 | + | |
| 1095 | + | |
| 1096 | + | |
| 1097 | + | |
| 1098 | + | |
| 1099 | + | |
| 1100 | + | |
| 1101 | + | |
| 1102 | + | |
| 1103 | + | |
| 1104 | + | |
| 1105 | + | |
| 1106 | + | |
| 1107 | + | |
| 1108 | + | |
| 1109 | + | |
| 1110 | + | |
| 1111 | + | |
| 1112 | + | |
| 1113 | + | |
| 1114 | + | |
| 1115 | + | |
| 1116 | + | |
| 1117 | + | |
| 1118 | + | |
| 1119 | + | |
| 1120 | + | |
| 1121 | + | |
| 1122 | + | |
844 | 1123 | | |
845 | 1124 | | |
846 | 1125 | | |
| |||
0 commit comments