Skip to content

Commit 18a12b9

Browse files
CrazyBaranclaude
andcommitted
fix(extensions): address Copilot review round 1 on #4351
All four review findings were valid; each is applied with regression tests: 1. compute_extension_content_hash() excluded *-config.yml / *-config.local.yml at every depth, but the remove/backup/restore machinery only preserves top-level config files (_target_follows_preserved_convention), so a changed nested shipped file like templates/foo-config.yml was overwritten by installation yet invisible to staleness detection. The exclusion now applies only to direct children of the extension directory. 2. The stale-content check ran on every catalog_version <= installed_version outcome. When the installed copy is newer than the catalog or the running release's bundled copy (e.g. written by a newer CLI), a hash difference is version skew, not unbumped drift - and the suggested `extension add --force` would downgrade the installation. The check is now gated on catalog_version == installed_version at the call site AND on the bundled copy declaring the same version as the installed one inside the helper (the second guard also covers an older CLI run against an up-to-date project, which the call-site gate alone would miss). 3. _archive_extension_directory() followed file symlinks (is_file() + ZipFile.write() dereference), so a symlink in a source directory could turn out-of-tree bytes into a regular archive member before the hardened extractor sees it. Symlinks are now skipped, matching the rule in compute_extension_content_hash(). 4. The CI guard's fallback comparison only required inequality for non-dotted-numeric versions, so a PEP 440 prerelease downgrade like 2.0.0 -> 1.0.0rc1 passed. The script now compares with packaging.version.Version - the same semantics extension update/install use - and fails closed on unparseable versions; the workflow installs packaging alongside pyyaml. Verified locally that 1.1.0 -> 1.0.0rc1 with content changes is now rejected. Refs #4345 Assisted-by: Claude Code (model: claude-fable-5, autonomous) Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent 08246e5 commit 18a12b9

5 files changed

Lines changed: 144 additions & 36 deletions

File tree

‎.github/scripts/check_extension_version_bump.py‎

Lines changed: 19 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,9 @@
1010
This check enforces two invariants on the extensions listed in
1111
`extensions/catalog.json`:
1212
13-
1. Any change to a file under `extensions/<id>/` must be accompanied by
14-
a `version:` change in that extension's `extension.yml`.
13+
1. Any change to a file under `extensions/<id>/` must increase the
14+
`version:` in that extension's `extension.yml` (PEP 440 comparison,
15+
the same semantics `extension update` uses).
1516
2. The `version` in `extensions/catalog.json` must equal the manifest's
1617
`extension.version` (the catalog is what update checks compare
1718
against, and the update preflight rejects a manifest whose version
@@ -37,6 +38,7 @@
3738
from pathlib import Path
3839

3940
import yaml
41+
from packaging.version import InvalidVersion, Version
4042

4143
EXTENSIONS_ROOT = "extensions"
4244
CATALOG_PATH = f"{EXTENSIONS_ROOT}/catalog.json"
@@ -66,14 +68,6 @@ def _manifest_version(manifest_text: str, origin: str) -> str:
6668
return version.strip()
6769

6870

69-
def _version_tuple(version: str) -> tuple[int, ...] | None:
70-
"""Parse a dotted-numeric version, or None when any part is non-numeric."""
71-
try:
72-
return tuple(int(part) for part in version.split("."))
73-
except ValueError:
74-
return None
75-
76-
7771
def main(argv: list[str]) -> int:
7872
if len(argv) < 2 or len(argv) > 3:
7973
print(__doc__, file=sys.stderr)
@@ -117,19 +111,23 @@ def main(argv: list[str]) -> int:
117111
errors.append(str(exc))
118112
continue
119113

120-
base_parsed = _version_tuple(base_version)
121-
head_parsed = _version_tuple(head_version)
122-
if base_parsed is not None and head_parsed is not None:
123-
if head_parsed <= base_parsed:
124-
errors.append(
125-
f"{manifest_path}: files under {EXTENSIONS_ROOT}/{ext_id}/ changed but "
126-
f"extension.version did not increase ({base_version} -> {head_version}). "
127-
f"Installed copies only receive changes when the version is bumped."
128-
)
129-
elif head_version == base_version:
114+
# Compare with the same PEP 440 semantics the extension update and
115+
# install code use (packaging.version), so prereleases and other
116+
# accepted forms cannot bypass the guard (e.g. 2.0.0 -> 1.0.0rc1 is
117+
# a downgrade). Unparseable versions fail closed.
118+
try:
119+
base_parsed = Version(base_version)
120+
head_parsed = Version(head_version)
121+
except InvalidVersion as exc:
122+
errors.append(
123+
f"{manifest_path}: could not compare versions "
124+
f"{base_version!r} -> {head_version!r}: {exc}"
125+
)
126+
continue
127+
if head_parsed <= base_parsed:
130128
errors.append(
131129
f"{manifest_path}: files under {EXTENSIONS_ROOT}/{ext_id}/ changed but "
132-
f"extension.version is still {base_version}. "
130+
f"extension.version did not increase ({base_version} -> {head_version}). "
133131
f"Installed copies only receive changes when the version is bumped."
134132
)
135133

‎.github/workflows/extension-version-guard.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ jobs:
2828
with:
2929
python-version: "3.14"
3030

31-
- name: Install PyYAML
32-
run: python -m pip install --quiet pyyaml
31+
- name: Install check dependencies
32+
run: python -m pip install --quiet pyyaml packaging
3333

3434
# For pull_request events the checkout is the merge of the PR head
3535
# into the base tip, so diffing base.sha against HEAD yields exactly

‎src/specify_cli/extensions/__init__.py‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -742,10 +742,13 @@ def compute_extension_content_hash(ext_dir: Path) -> str:
742742
(#4345). This hash covers every regular file an install would copy:
743743
it folds in the sorted POSIX-style relative path and raw bytes of each
744744
file, excluding exactly what installs treat as user-owned or skip —
745-
``*-config.yml`` / ``*-config.local.yml`` (preserved across installs)
746-
and ``.extensionignore`` plus whatever it ignores. The same function
747-
therefore yields comparable hashes for a bundled source directory and
748-
an installation made from it.
745+
top-level ``*-config.yml`` / ``*-config.local.yml`` (the only config
746+
paths the remove/backup/restore machinery preserves, see
747+
``_target_follows_preserved_convention``) and ``.extensionignore``
748+
plus whatever it ignores. Nested config-suffixed files are hashed:
749+
installs overwrite them, so their changes are real staleness. The
750+
same function therefore yields comparable hashes for a bundled source
751+
directory and an installation made from it.
749752
750753
Symlinks are never followed: an entry linking outside the extension
751754
directory must not pull external bytes into the hash. Bundled
@@ -767,8 +770,9 @@ def walk(directory: Path) -> None:
767770
if entry.is_dir():
768771
walk(entry)
769772
elif entry.is_file():
770-
if entry.name.endswith("-config.yml") or entry.name.endswith(
771-
"-config.local.yml"
773+
if entry.parent == ext_dir and (
774+
entry.name.endswith("-config.yml")
775+
or entry.name.endswith("-config.local.yml")
772776
):
773777
continue
774778
data = entry.read_bytes()

‎src/specify_cli/extensions/_commands.py‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,7 @@ def _bundled_content_is_stale(
116116
metadata: dict[str, Any],
117117
ext_info: dict[str, Any],
118118
manager: ExtensionManager,
119+
installed_version: Version,
119120
) -> bool:
120121
"""Report whether a bundled extension's installed content is stale.
121122
@@ -128,13 +129,19 @@ def _bundled_content_is_stale(
128129
running spec-kit version. Only meaningful for bundled extensions with
129130
no download URL — anything downloadable is served by the normal
130131
version flow.
132+
133+
The comparison requires the local bundled copy to declare the same
134+
version as the installed one: a hash difference against an older or
135+
newer local copy is version skew, not unbumped content drift, and a
136+
`--force` refresh recommendation against an older copy would downgrade
137+
the installation.
131138
"""
132139
from . import compute_extension_content_hash
133140

134141
if not ext_info.get("bundled") or ext_info.get("download_url"):
135142
return False
136-
bundled_path = _locate_bundled_extension(ext_id)
137-
if bundled_path is None:
143+
bundled_path, bundled_version = _bundled_update_source(ext_id)
144+
if bundled_path is None or bundled_version != installed_version:
138145
return False
139146
try:
140147
bundled_hash = compute_extension_content_hash(bundled_path)
@@ -189,6 +196,13 @@ def _archive_extension_directory(source_dir: Path) -> Path:
189196
with os.fdopen(fd, "wb") as archive_file:
190197
with zipfile.ZipFile(archive_file, "w", zipfile.ZIP_DEFLATED) as zf:
191198
for path in sorted(source_dir.rglob("*")):
199+
# Never follow symlinks: is_file() follows the target
200+
# and ZipFile.write() reads its bytes, which would turn
201+
# an out-of-tree target into a regular archive member
202+
# before the hardened extractor ever sees it. Matches
203+
# the symlink rule in compute_extension_content_hash.
204+
if path.is_symlink():
205+
continue
192206
if path.is_file():
193207
zf.write(path, path.relative_to(source_dir).as_posix())
194208
except BaseException:
@@ -1783,10 +1797,15 @@ def extension_update(
17831797
"bundled_dir": bundled_dir,
17841798
}
17851799
)
1786-
elif _bundled_content_is_stale(ext_id, metadata, ext_info, manager):
1800+
elif catalog_version == installed_version and _bundled_content_is_stale(
1801+
ext_id, metadata, ext_info, manager, installed_version
1802+
):
17871803
# Bundled content changed without a version bump (#4345):
17881804
# the semver comparison alone would report "Up to date"
17891805
# while the installed copy keeps missing shipped fixes.
1806+
# Guarded to equal versions: an installed copy newer than
1807+
# the catalog (e.g. written by a newer CLI) must not be
1808+
# steered into a downgrading --force refresh.
17901809
stale_content.append(ext_id)
17911810
console.print(
17921811
f"⚠ {safe_ext_id}: v{installed_version} matches the catalog, but the "

‎tests/test_extension_content_staleness.py‎

Lines changed: 91 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@
2424
)
2525

2626

27-
def _create_extension_source(base_dir: Path, name: str = "test-ext") -> Path:
27+
def _create_extension_source(
28+
base_dir: Path, name: str = "test-ext", version: str = "1.0.0"
29+
) -> Path:
2830
"""Create a minimal installable extension source directory."""
2931
ext_dir = base_dir / name
3032
ext_dir.mkdir(parents=True, exist_ok=True)
@@ -34,7 +36,7 @@ def _create_extension_source(base_dir: Path, name: str = "test-ext") -> Path:
3436
"extension": {
3537
"id": "test-ext",
3638
"name": "Test Extension",
37-
"version": "1.0.0",
39+
"version": version,
3840
"description": "A test extension",
3941
},
4042
"requires": {"speckit_version": ">=0.1.0"},
@@ -108,6 +110,18 @@ def test_user_config_files_excluded(self, tmp_path):
108110
(ext_dir / "test-ext-config.local.yml").write_text("local: override\n")
109111
assert compute_extension_content_hash(ext_dir) == before
110112

113+
def test_nested_config_suffixed_files_are_hashed(self, tmp_path):
114+
"""Only top-level config files are preserved across installs
115+
(_target_follows_preserved_convention); a nested *-config.yml is
116+
overwritten by installation, so its changes are real staleness."""
117+
ext_dir = _create_extension_source(tmp_path)
118+
templates = ext_dir / "templates"
119+
templates.mkdir()
120+
(templates / "scaffold-config.yml").write_text("shipped: v1\n")
121+
before = compute_extension_content_hash(ext_dir)
122+
(templates / "scaffold-config.yml").write_text("shipped: v2\n")
123+
assert compute_extension_content_hash(ext_dir) != before
124+
111125
def test_extensionignore_and_ignored_files_excluded(self, tmp_path):
112126
ext_dir = _create_extension_source(tmp_path)
113127
before = compute_extension_content_hash(ext_dir)
@@ -143,6 +157,46 @@ def test_matches_between_source_and_installation(self, tmp_path):
143157
) == compute_extension_content_hash(source)
144158

145159

160+
class TestArchiveExtensionDirectory:
161+
def test_archive_contains_regular_files_only(self, tmp_path):
162+
import zipfile
163+
164+
from specify_cli.extensions._commands import _archive_extension_directory
165+
166+
ext_dir = _create_extension_source(tmp_path)
167+
archive_path = _archive_extension_directory(ext_dir)
168+
try:
169+
with zipfile.ZipFile(archive_path) as zf:
170+
names = set(zf.namelist())
171+
assert "extension.yml" in names
172+
assert "commands/hello.md" in names
173+
finally:
174+
archive_path.unlink()
175+
176+
def test_archive_never_follows_symlinks(self, tmp_path):
177+
"""A symlink in the source must not pull out-of-tree bytes into the
178+
archive before the hardened extractor sees it."""
179+
import zipfile
180+
181+
from specify_cli.extensions._commands import _archive_extension_directory
182+
183+
ext_dir = _create_extension_source(tmp_path)
184+
outside = tmp_path / "outside.txt"
185+
outside.write_text("external bytes\n")
186+
try:
187+
(ext_dir / "scripts" / "link.txt").symlink_to(outside)
188+
except OSError:
189+
pytest.skip("symlink creation requires privileges on this platform")
190+
191+
archive_path = _archive_extension_directory(ext_dir)
192+
try:
193+
with zipfile.ZipFile(archive_path) as zf:
194+
names = set(zf.namelist())
195+
assert "scripts/link.txt" not in names
196+
finally:
197+
archive_path.unlink()
198+
199+
146200
class TestInstallStoresContentHash:
147201
def test_registry_entry_records_source_content_hash(self, tmp_path):
148202
project_dir = _make_project(tmp_path)
@@ -167,13 +221,13 @@ def _flat(result) -> str:
167221
"""Console output with Rich's line wrapping collapsed."""
168222
return " ".join(result.output.split())
169223

170-
def _run_update(self, project_dir, bundled_path):
224+
def _run_update(self, project_dir, bundled_path, catalog_info=None):
171225
runner = CliRunner()
172226
with patch.object(Path, "cwd", return_value=project_dir), \
173227
patch.object(
174228
ExtensionCatalog,
175229
"get_extension_info",
176-
return_value=dict(BUNDLED_CATALOG_INFO),
230+
return_value=dict(catalog_info or BUNDLED_CATALOG_INFO),
177231
), \
178232
patch(
179233
"specify_cli._locate_bundled_extension",
@@ -220,6 +274,39 @@ def test_stale_check_covers_registry_entries_without_content_hash(self, tmp_path
220274
assert result.exit_code == 0, result.output
221275
assert "differ from the copy bundled" in self._flat(result)
222276

277+
def test_no_stale_flag_when_bundled_copy_is_older_version(self, tmp_path):
278+
"""An installed copy newer than the running release's bundled copy is
279+
version skew, not content drift — flagging it would steer the user
280+
into a downgrading --force refresh."""
281+
project_dir = _make_project(tmp_path)
282+
v2_source = _create_extension_source(tmp_path / "installed-src", version="2.0.0")
283+
ExtensionManager(project_dir).install_from_directory(v2_source, "0.1.0")
284+
old_bundled = _create_extension_source(tmp_path / "bundled", version="1.0.0")
285+
(old_bundled / "scripts" / "run.sh").write_text("#!/bin/sh\necho old\n")
286+
catalog_info = dict(BUNDLED_CATALOG_INFO)
287+
catalog_info["version"] = "2.0.0"
288+
289+
result = self._run_update(project_dir, old_bundled, catalog_info)
290+
291+
assert result.exit_code == 0, result.output
292+
assert "Up to date (v2.0.0)" in self._flat(result)
293+
assert "differ from the copy bundled" not in self._flat(result)
294+
295+
def test_no_stale_flag_when_catalog_lags_installed_version(self, tmp_path):
296+
"""The stale check only runs when catalog and installed versions are
297+
equal; a catalog behind the installed version must not trigger it."""
298+
project_dir = _make_project(tmp_path)
299+
v2_source = _create_extension_source(tmp_path / "installed-src", version="2.0.0")
300+
ExtensionManager(project_dir).install_from_directory(v2_source, "0.1.0")
301+
old_bundled = _create_extension_source(tmp_path / "bundled", version="1.0.0")
302+
(old_bundled / "scripts" / "run.sh").write_text("#!/bin/sh\necho old\n")
303+
304+
result = self._run_update(project_dir, old_bundled)
305+
306+
assert result.exit_code == 0, result.output
307+
assert "Up to date (v2.0.0)" in self._flat(result)
308+
assert "differ from the copy bundled" not in self._flat(result)
309+
223310
def test_user_config_edits_are_not_reported_as_stale(self, tmp_path):
224311
project_dir, source = self._install(tmp_path)
225312
installed_config = (

0 commit comments

Comments
 (0)