Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

fix(bundles): allow newer packaged patch releases with warnings (#4942)

Manfred Riem93eb96a75997
diff --git a/docs/reference/bundles.md b/docs/reference/bundles.md
index f6bf87971..d9ca00804 100644
--- a/docs/reference/bundles.md
+++ b/docs/reference/bundles.md
@@ -74,7 +74,7 @@ specify bundle install <bundle_id | path>
Installs a bundle's full component set through each primitive's machinery. The argument may be a catalog bundle id, or a local path to a built `.zip` artifact, a bundle directory, or a `bundle.yml` file; local sources install directly without consulting the catalog stack.
-If the current directory is not yet a Spec Kit project, `install` initializes one first so a fresh checkout reaches a working state in a single command. `--integration` selects the integration when initializing a new project, and confirms the target when a bundle pins a specific integration but the project's active integration can't be determined (missing or unreadable `.specify/integration.json`). It does **not** override an already-initialized project's active integration: if a bundle targets a different integration than the project's, install aborts with no changes. Integration-agnostic bundles inherit the project's active integration. Without `--refresh`, installation is idempotent β€” already-installed components matching their pins are skipped. A missing or different installed version cannot satisfy a pin. Only `--refresh` can repair a drifted version owned exclusively by this bundle; independently installed components are skipped and never adopted or replaced. On failure, no provenance record is written (a failed install records nothing), and the components installed during that run are removed on a best-effort basis β€” removal errors are swallowed, so partial on-disk state may remain.
+If the current directory is not yet a Spec Kit project, `install` initializes one first so a fresh checkout reaches a working state in a single command. `--integration` selects the integration when initializing a new project, and confirms the target when a bundle pins a specific integration but the project's active integration can't be determined (missing or unreadable `.specify/integration.json`). It does **not** override an already-initialized project's active integration: if a bundle targets a different integration than the project's, install aborts with no changes. Integration-agnostic bundles inherit the project's active integration. Without `--refresh`, installation is idempotent β€” already-installed components matching their pins are skipped, as are bundle-owned compatible packaged patch releases with a warning (see below). Other differing or missing installed versions cannot satisfy a pin. Only `--refresh` can repair a drifted version owned exclusively by this bundle; independently installed components are skipped and never adopted or replaced. On failure, no provenance record is written (a failed install records nothing), and the components installed during that run are removed on a best-effort basis β€” removal errors are swallowed, so partial on-disk state may remain.
Installed-bundle records store required component pins separately from contributed components. A compatible independently installed component satisfies a bundle's requirement but remains independently owned: its pin still blocks a later bundle from installing an incompatible version, while removing the bundle does not uninstall it. An unpinned install or refresh cannot replace a component another bundle requires at a pinned version; sharing an already installed matching version without refreshing remains allowed. Shared bundles must also agree on component source and, for presets, priority and strategy before installing or refreshing the shared component. Older records without the requirement list retain their known contributed pins; reinstall or refresh the bundle to record its full requirements.
@@ -88,6 +88,23 @@ The source may also be a bundle directory or `.zip` artifact. Refresh uses the s
A local bundle source supplies the manifest, not its component payloads. Components resolved through catalogs still require network access to refresh, even when already installed. Add `--offline` only when the components being installed or refreshed ship with Spec Kit; otherwise the command reports which component needs network access. Re-run without `--offline` to fetch that component through its catalog.
+**Packaged patch compatibility.** When an extension, preset, or workflow shipped
+with the CLI is a newer stable patch release within the pinned major/minor
+version, installation and refresh warn and use that packaged release. For
+example, a bundle pinning `bug` to `1.0.0` can use packaged `bug` `1.0.1` without
+editing its manifest. Validation reports the same warning. Downgrades,
+major/minor mismatches, and differing prerelease versions remain errors; an
+explicit component `source` also retains exact-pin enforcement. Catalog-resolved
+components still require exact matches. This exception improves compatibility
+across CLI upgrades, but a patch release is not a guarantee of unchanged behavior.
+
+Bundle records retain requested versions in `required_components` and
+`contributed_components` and
+store actual known installed versions under `installed_versions`, keyed by
+`kind:id` (for example, `"extensions:bug": "1.0.1"`). These are also visible in
+`specify bundle list --json`. Component version ranges, `latest`, and omitted
+extension versions are not supported.
+
> **Step payloads resolve through the step catalog only.** A bundle's `provides.steps` entries still resolve exclusively through the active step catalogs. Bundle-local `steps/<id>/` payloads and relative `provides.steps[].source` overrides are **not** resolved in this release, so a step declared that way cannot be installed offline. To ship a step with a bundle today, publish it to a step catalog the bundle's users can reach.
## Catalog Release History
@@ -129,11 +146,11 @@ specify bundle update [<bundle_id>]
| `--integration` | Override the integration used when refreshing components; applied only when the project's active integration can't be determined |
| `--offline` | Do not access the network |
-Re-resolves a bundle and **refreshes** its components through each primitive's update path, bringing already-installed components up to the bundle's newly pinned versions while preserving primitive-level overrides (such as preset priority). Provide a bundle id, or use `--all` to update everything installed.
+Re-resolves a bundle and **refreshes** its components through each primitive's update path, bringing already-installed components up to the bundle's newly pinned versions (or compatible newer packaged patches, with a warning) while preserving primitive-level overrides (such as preset priority). Provide a bundle id, or use `--all` to update everything installed.
**Pinned catalog releases.** Extensions, presets, workflows, and steps with version pins select that exact release from the highest-priority active catalog entry. Historical releases must be advertised under `releases` with their own artifact URL and SHA-256 digest; the bundler never guesses an old URL from the current one or falls through to another catalog. Legacy extension and preset entries that advertise no version are an exception: the bundler uses the winning entry as-is and cannot enforce its pin or verify the installed archive's version. Publish a versioned entry to make that pin enforceable. The primitive installer uses the selected workflow or step record without re-reading the catalog, and verifies downloaded archive or workflow/step metadata against that release. A pinned workflow that ships with Spec Kit uses its bundled copy when the version matches, and the catalog release when it differs and network access is allowed. A step without a pin installs the current catalog release.
-Without an explicit `source`, bundled extensions and presets take precedence over catalog releases. Validation rejects a pin that differs from the bundled version even when a matching catalog release exists; specify the winning catalog as `source` to opt into its release.
+Without an explicit `source`, bundled extensions and presets take precedence over catalog releases. Validation rejects an incompatible pin even when a matching catalog release exists; compatible newer stable packaged patches produce a warning instead. Specify the winning catalog as `source` to opt into its exact release.
> **One installed version per component ID.** Bundles sharing a component must agree on its pinned version. A different or unknown pin from another bundle is rejected before installation, including during `bundle update`; refreshing one bundle cannot replace a version required by another.
diff --git a/src/specify_cli/bundles/_commands.py b/src/specify_cli/bundles/_commands.py
index eb8d4a70d..512773b66 100644
--- a/src/specify_cli/bundles/_commands.py
+++ b/src/specify_cli/bundles/_commands.py
@@ -8,6 +8,7 @@ Typer-free modules in this package.
from __future__ import annotations
from pathlib import Path
+from typing import TYPE_CHECKING
import typer
from rich.markup import escape as _escape_markup
@@ -17,6 +18,9 @@ from . import BundlerError
from .project import active_integration
from .records import load_records
+if TYPE_CHECKING:
+ from .installer import InstallResult
+
bundle_app = typer.Typer(
name="bundle",
help="Discover, install, and author Spec Kit bundles",
@@ -42,6 +46,11 @@ def _fail(message: str, *, as_json: bool = False) -> None:
raise typer.Exit(code=1)
+def _render_install_warnings(result: InstallResult) -> None:
+ for warning in result.warnings:
+ err_console.print(f"[yellow]Warning:[/yellow] {_escape_markup(warning.message)}")
+
+
def _user_config_dir() -> Path:
# User-scope Spec Kit config lives under ~/.specify (same convention as
# auth.json, extension/preset catalogs). Passing this through to the source
diff --git a/src/specify_cli/bundles/adapters.py b/src/specify_cli/bundles/adapters.py
index 5427f0125..46433cb00 100644
--- a/src/specify_cli/bundles/adapters.py
+++ b/src/specify_cli/bundles/adapters.py
@@ -16,6 +16,7 @@ import ssl
import urllib.error
import warnings
from pathlib import Path
+from typing import TYPE_CHECKING
from urllib.parse import ParseResult, urlparse
from urllib.request import url2pathname
@@ -26,6 +27,9 @@ from .catalogs import CatalogSource
from .manifest import ComponentRef
from .yamlio import loads_json
+if TYPE_CHECKING:
+ from .primitives import BundledPatchWarning
+
COMMUNITY_CATALOG_URL = (
"https://raw.githubusercontent.com/github/spec-kit/main/"
"bundles/catalog.community.json"
@@ -330,6 +334,22 @@ class DefaultPrimitiveInstaller:
manager = self._manager_for(component, project_root)
return manager.installed_version(component)
+ def bundled_patch_warning(
+ self, component: ComponentRef, actual: str,
+ ) -> BundledPatchWarning | None:
+ from .primitives import _bundled_component_version, _bundled_pin_warning
+ from .versioning import is_newer_patch, same_version
+
+ packaged = _bundled_component_version(component)
+ if (
+ component.version
+ and packaged
+ and same_version(actual, packaged)
+ and is_newer_patch(actual, component.version)
+ ):
+ return _bundled_pin_warning(component.kind[:-1].capitalize(), component, actual)
+ return None
+
def validate_source(self, project_root: Path, component: ComponentRef) -> None:
if not self._allow_network:
raise BundlerError(
@@ -354,13 +374,17 @@ class DefaultPrimitiveInstaller:
f"'{component.source}': {detail}."
)
- def install(self, project_root: Path, component: ComponentRef) -> None:
+ def install(
+ self, project_root: Path, component: ComponentRef,
+ ) -> BundledPatchWarning | None:
manager = self._manager_for(component, project_root)
- manager.install(component)
+ return manager.install(component)
- def refresh(self, project_root: Path, component: ComponentRef) -> None:
+ def refresh(
+ self, project_root: Path, component: ComponentRef,
+ ) -> BundledPatchWarning | None:
manager = self._manager_for(component, project_root)
- manager.refresh(component)
+ return manager.refresh(component)
def remove(self, project_root: Path, component: ComponentRef) -> None:
manager = self._manager_for(component, project_root)
diff --git a/src/specify_cli/bundles/command_install.py b/src/specify_cli/bundles/command_install.py
index 090f5c134..877adff55 100644
--- a/src/specify_cli/bundles/command_install.py
+++ b/src/specify_cli/bundles/command_install.py
@@ -14,6 +14,7 @@ from ._commands import (
_bundle_overlaps,
_default_script_type,
_fail,
+ _render_install_warnings,
_resolve_init_integration,
_run_init,
_speckit_version,
@@ -143,6 +144,7 @@ def bundle_install(
_fail(str(exc))
return
+ _render_install_warnings(result)
refresh_summary = (
f", {len(result.refreshed)} refreshed, {len(result.uninstalled)} removed"
if refresh
diff --git a/src/specify_cli/bundles/command_update.py b/src/specify_cli/bundles/command_update.py
index 753085ed9..db4d54ada 100644
--- a/src/specify_cli/bundles/command_update.py
+++ b/src/specify_cli/bundles/command_update.py
@@ -7,7 +7,13 @@ from rich.markup import escape as _escape_markup
from .._console import console
from . import BundlerError
-from ._commands import _build_stack, _fail, _speckit_version, bundle_app
+from ._commands import (
+ _build_stack,
+ _fail,
+ _render_install_warnings,
+ _speckit_version,
+ bundle_app,
+)
from .project import active_integration, require_project_root
from .records import load_records
from .sources import _download_manifest
@@ -57,9 +63,10 @@ def bundle_update(
active_integration=detected if detected is not None else integration,
integration_explicit=bool(integration) and detected is None,
)
- install_bundle(
+ result = install_bundle(
project_root, plan, installer, manifest=manifest, refresh=True
)
+ _render_install_warnings(result)
console.print(
f"[green]βœ“[/green] Updated '{_escape_markup(str(target))}' "
f"to v{_escape_markup(str(plan.version))}."
diff --git a/src/specify_cli/bundles/installer.py b/src/specify_cli/bundles/installer.py
index 23fcf1e94..6428c140d 100644
--- a/src/specify_cli/bundles/installer.py
+++ b/src/specify_cli/bundles/installer.py
@@ -18,6 +18,7 @@ from typing import Protocol
from . import BundlerError
from .conflict import detect_conflicts
from .manifest import BundleManifest, ComponentRef
+from .primitives import BundledPatchWarning
from .records import (
InstalledBundleRecord,
components_still_needed,
@@ -43,18 +44,23 @@ class PrimitiveInstaller(Protocol):
def validate_source(self, project_root: Path, component: ComponentRef) -> None: ...
- def install(self, project_root: Path, component: ComponentRef) -> None: ...
+ def install(
+ self, project_root: Path, component: ComponentRef,
+ ) -> BundledPatchWarning | None: ...
def remove(self, project_root: Path, component: ComponentRef) -> None: ...
@dataclass
class InstallResult:
+ """Bundle changes and structured warnings for presentation by the caller."""
+
bundle_id: str
installed: list[ComponentRef] = field(default_factory=list)
skipped: list[ComponentRef] = field(default_factory=list)
refreshed: list[ComponentRef] = field(default_factory=list)
uninstalled: list[ComponentRef] = field(default_factory=list)
+ warnings: list[BundledPatchWarning] = field(default_factory=list)
@property
def changed(self) -> bool:
@@ -81,9 +87,9 @@ def install_bundle(
When *refresh* is True (used by ``specify bundle update``), components that
are already installed are re-applied through the primitive machinery so they
- are brought up to the plan's pinned versions, rather than skipped. Primitive
- config (e.g. preset priority overrides) is preserved by the underlying
- machinery.
+ are brought up to the plan's pinned versions, or compatible newer packaged
+ patches with a warning, rather than skipped. Primitive config (e.g. preset
+ priority overrides) is preserved by the underlying machinery.
Already-installed components must match their pins before they can be
skipped. A refresh may repair drift in components owned exclusively by
@@ -91,6 +97,8 @@ def install_bundle(
independently installed component. Changes to owned component metadata
still require refresh. Other bundles' source and preset settings cannot be
changed by sharing or refreshing a component.
+ Compatible packaged patch substitutions are accepted for bundle-owned
+ components, with requested and installed versions recorded separately.
"""
records = load_records(project_root)
@@ -149,11 +157,12 @@ def install_bundle(
other_pins.setdefault(key, set()).add(component.version)
contributed: list[ComponentRef] = []
done: list[ComponentRef] = []
+ installed_versions: dict[str, str] = {}
try:
- _check_installed_pins(
+ result.warnings.extend(_check_installed_pins(
project_root, plan, installer, prior_ours, other_tracked,
other_pins, other_requirements, refresh=refresh,
- )
+ ))
for component in plan.components:
key = (component.kind, component.id)
if installer.is_installed(project_root, component):
@@ -164,14 +173,18 @@ def install_bundle(
# does not own (FR-022).
owned = key in prior_ours or key in other_tracked
if refresh and owned:
- _refresh_component(project_root, installer, component)
+ warning = _refresh_component(project_root, installer, component)
+ if warning is not None:
+ result.warnings.append(warning)
result.refreshed.append(component)
else:
result.skipped.append(component)
if owned:
contributed.append(component)
continue
- installer.install(project_root, component)
+ warning = installer.install(project_root, component)
+ if warning is not None:
+ result.warnings.append(warning)
done.append(component)
result.installed.append(component)
contributed.append(component)
@@ -197,6 +210,12 @@ def install_bundle(
if installer.is_installed(project_root, component):
installer.remove(project_root, component)
result.uninstalled.append(component)
+ version_reader = getattr(installer, "installed_version", None)
+ if callable(version_reader):
+ for component in plan.components:
+ actual = version_reader(project_root, component)
+ if actual is not None:
+ installed_versions[f"{component.kind}:{component.id}"] = actual
except BundlerError:
_rollback(project_root, installer, done)
raise
@@ -215,6 +234,7 @@ def install_bundle(
# Preserve the original install time across refresh/update so
# ``bundle list`` keeps reporting when the bundle was first installed.
installed_at=existing.installed_at if existing is not None else None,
+ installed_versions=installed_versions,
)
updated = upsert_record(records, record)
if refresh and existing is not None:
@@ -294,9 +314,10 @@ def _check_installed_pins(
other_requirements: dict[tuple[str, str], list[tuple[str, ComponentRef]]],
*,
refresh: bool,
-) -> None:
+) -> list[BundledPatchWarning]:
"""Check installed pins and other bundles' requirements before mutation."""
mismatches = []
+ warnings: list[BundledPatchWarning] = []
for component in plan.components:
key = component.kind, component.id
for bundle_id, required in other_requirements.get(key, []):
@@ -348,6 +369,13 @@ def _check_installed_pins(
actual = installer.installed_version(project_root, component)
if actual and same_version(actual, component.version):
continue
+ patch_warning = getattr(installer, "bundled_patch_warning", None)
+ if actual and key in prior_ours | other_tracked and callable(patch_warning):
+ warning = patch_warning(component, actual)
+ if warning:
+ if not refresh:
+ warnings.append(warning)
+ continue
if refresh and key in prior_ours and key not in other_tracked:
continue
pinned = f"{component.kind[:-1]} '{component.id}' to {component.version}"
@@ -361,13 +389,14 @@ def _check_installed_pins(
"version can be installed per ID; independently installed and "
"other bundles' components cannot be replaced by this bundle."
)
+ return warnings
def _refresh_component(
project_root: Path,
installer: PrimitiveInstaller,
component: ComponentRef,
-) -> None:
+) -> BundledPatchWarning | None:
"""Re-apply an already-installed component to bring it up to its pinned version.
Prefers a primitive-provided ``refresh`` hook when available; otherwise falls
@@ -375,9 +404,8 @@ def _refresh_component(
"""
op = getattr(installer, "refresh", None)
if callable(op):
- op(project_root, component)
- else:
- installer.install(project_root, component)
+ return op(project_root, component)
+ return installer.install(project_root, component)
def _rollback(
diff --git a/src/specify_cli/bundles/primitives.py b/src/specify_cli/bundles/primitives.py
index bb37955ab..51206a853 100644
--- a/src/specify_cli/bundles/primitives.py
+++ b/src/specify_cli/bundles/primitives.py
@@ -21,8 +21,9 @@ from __future__ import annotations
import contextlib
import os
+from dataclasses import dataclass
from pathlib import Path
-from typing import Protocol
+from typing import Literal, Protocol
from . import BundlerError
from .manifest import ComponentRef
@@ -31,6 +32,21 @@ from .versioning import same_version
DEFAULT_PRIORITY = 10
+@dataclass(frozen=True)
+class BundledPatchDetails:
+ kind: str
+ component_id: str
+ requested_version: str
+ installed_version: str
+
+
+@dataclass(frozen=True)
+class BundledPatchWarning:
+ message: str
+ details: BundledPatchDetails
+ code: Literal["bundled_patch_upgrade"] = "bundled_patch_upgrade"
+
+
def _assert_pinned_version(
kind: str, component_id: str, pinned: str | None, advertised: object
) -> None:
@@ -132,6 +148,36 @@ def _selected_catalog_info(kind: str, component: ComponentRef, catalog) -> dict:
return selected
+def _bundled_pin_warning(
+ kind: str, component: ComponentRef, advertised: object,
+) -> BundledPatchWarning | None:
+ """Allow packaged stable patch upgrades without weakening catalog pins."""
+ from .versioning import is_newer_patch
+
+ if (
+ component.source is None
+ and component.version
+ and isinstance(advertised, str)
+ and is_newer_patch(advertised.strip(), component.version)
+ ):
+ return BundledPatchWarning(
+ message=(
+ f"{kind} '{component.id}' is pinned to version {component.version}, "
+ f"but Spec Kit ships {advertised.strip()}; using the newer packaged patch. "
+ "Bundle installation records the actual installed version "
+ "alongside the requested pin."
+ ),
+ details=BundledPatchDetails(
+ kind=component.kind,
+ component_id=component.id,
+ requested_version=component.version,
+ installed_version=advertised.strip(),
+ ),
+ )
+ _assert_pinned_version(kind, component.id, component.version, advertised)
+ return None
+
+
def _bundled_manifest_version(manifest_path: Path, root_key: str) -> str | None:
"""Best-effort read of a bundled asset's declared version from its manifest.
@@ -156,6 +202,29 @@ def _bundled_manifest_version(manifest_path: Path, root_key: str) -> str | None:
return None
+def _bundled_component_version(component: ComponentRef) -> str | None:
+ from .._assets import (
+ _locate_bundled_extension,
+ _locate_bundled_preset,
+ _locate_bundled_workflow,
+ )
+
+ if component.source is not None:
+ return None
+ locate = {
+ "extensions": _locate_bundled_extension,
+ "presets": _locate_bundled_preset,
+ "workflows": _locate_bundled_workflow,
+ }.get(component.kind)
+ if locate is None:
+ return None
+ bundled = locate(component.id)
+ if bundled is None:
+ return None
+ kind = component.kind[:-1]
+ return _bundled_manifest_version(bundled / f"{kind}.yml", kind)
+
+
def _registry_version(registry, component_id: str) -> str | None:
"""Version a primitive registry recorded for an installed component.
@@ -177,10 +246,10 @@ class _KindManager(Protocol):
def installed_version(self, component: ComponentRef) -> str | None:
pass
- def install(self, component: ComponentRef) -> None:
+ def install(self, component: ComponentRef) -> BundledPatchWarning | None:
pass
- def refresh(self, component: ComponentRef) -> None:
+ def refresh(self, component: ComponentRef) -> BundledPatchWarning | None:
pass
def remove(self, component: ComponentRef) -> None:
@@ -248,13 +317,15 @@ class _PresetKindManager:
def installed_version(self, component: ComponentRef) -> str | None:
return _registry_version(self._manager.registry, component.id)
- def install(self, component: ComponentRef) -> None:
- self._do_install(component, force=False)
+ def install(self, component: ComponentRef) -> BundledPatchWarning | None:
+ return self._do_install(component, force=False)
- def refresh(self, component: ComponentRef) -> None:
- self._do_install(component, force=True)
+ def refresh(self, component: ComponentRef) -> BundledPatchWarning | None:
+ return self._do_install(component, force=True)
- def _do_install(self, component: ComponentRef, *, force: bool) -> None:
+ def _do_install(
+ self, component: ComponentRef, *, force: bool,
+ ) -> BundledPatchWarning | None:
from .. import get_speckit_version
from .._assets import _locate_bundled_preset
@@ -263,19 +334,15 @@ class _PresetKindManager:
bundled = _locate_bundled_preset(component.id)
if bundled is not None and component.source is None:
- # Enforce the manifest pin against the bundled asset's own version,
- # mirroring the catalog path below (the bundled path previously
- # skipped the pin entirely).
- _assert_pinned_version(
+ warning = _bundled_pin_warning(
"Preset",
- component.id,
- component.version,
+ component,
_bundled_manifest_version(bundled / "preset.yml", "preset"),
)
self._manager.install_from_directory(
bundled, speckit_version, priority, **({"force": True} if force else {})
)
- return
+ return warning
if not self._allow_network:
raise BundlerError(
@@ -341,13 +408,15 @@ class _ExtensionKindManager:
def installed_version(self, component: ComponentRef) -> str | None:
return _registry_version(self._manager.registry, component.id)
- def install(self, component: ComponentRef) -> None:
- self._do_install(component, force=False)
+ def install(self, component: ComponentRef) -> BundledPatchWarning | None:
+ return self._do_install(component, force=False)
- def refresh(self, component: ComponentRef) -> None:
- self._do_install(component, force=True)
+ def refresh(self, component: ComponentRef) -> BundledPatchWarning | None:
+ return self._do_install(component, force=True)
- def _do_install(self, component: ComponentRef, *, force: bool) -> None:
+ def _do_install(
+ self, component: ComponentRef, *, force: bool,
+ ) -> BundledPatchWarning | None:
from .. import get_speckit_version
from .._assets import _locate_bundled_extension
@@ -356,20 +425,16 @@ class _ExtensionKindManager:
bundled = _locate_bundled_extension(component.id)
if bundled is not None and component.source is None:
- # Enforce the manifest pin against the bundled asset's own version,
- # mirroring the catalog path below (the bundled path previously
- # skipped the pin entirely).
- _assert_pinned_version(
+ warning = _bundled_pin_warning(
"Extension",
- component.id,
- component.version,
+ component,
_bundled_manifest_version(bundled / "extension.yml", "extension"),
)
manifest = self._manager.install_from_directory(
bundled, speckit_version, priority=priority, force=force
)
self._manager.scaffold_config(manifest.id)
- return
+ return warning
if not self._allow_network:
raise BundlerError(
@@ -438,7 +503,7 @@ class _WorkflowKindManager:
def installed_version(self, component: ComponentRef) -> str | None:
return _registry_version(self._registry, component.id)
- def install(self, component: ComponentRef) -> None:
+ def install(self, component: ComponentRef) -> BundledPatchWarning | None:
from .._assets import _locate_bundled_workflow
bundled = _locate_bundled_workflow(component.id)
@@ -457,9 +522,15 @@ class _WorkflowKindManager:
f"Bundled workflow at {workflow_file} declares ID "
f"'{definition.id}', expected '{component.id}'."
)
+ from .versioning import is_newer_patch
+
if component.version is None or (
- definition.version and same_version(definition.version, component.version)
+ definition.version and (
+ same_version(definition.version, component.version)
+ or is_newer_patch(definition.version, component.version)
+ )
):
+ warning = _bundled_pin_warning("Workflow", component, definition.version)
from .. import workflow_add
with _chdir(self._root):
@@ -468,7 +539,7 @@ class _WorkflowKindManager:
f"workflow '{component.id}'",
lambda: workflow_add(str(workflow_file), dev=True, from_url=None),
)
- return
+ return warning
if not self._allow_network:
_assert_pinned_version(
"Workflow", component.id, component.version, definition.version
@@ -496,10 +567,10 @@ class _WorkflowKindManager:
),
)
- def refresh(self, component: ComponentRef) -> None:
+ def refresh(self, component: ComponentRef) -> BundledPatchWarning | None:
# workflow_add is idempotent for already-installed workflows; delegate
# to the standard install path which handles version refresh correctly.
- self.install(component)
+ return self.install(component)
def remove(self, component: ComponentRef) -> None:
from .. import workflow_remove
diff --git a/src/specify_cli/bundles/records.py b/src/specify_cli/bundles/records.py
index c3a616cd9..86660f6f0 100644
--- a/src/specify_cli/bundles/records.py
+++ b/src/specify_cli/bundles/records.py
@@ -3,11 +3,13 @@
Records are stored as JSON at ``.specify/bundle-records.json``. Each record
stores every required component for conflict detection and separately records
which components the bundle contributed, so removal never touches independently
-installed components (FR-022, SC-004).
+installed components (FR-022, SC-004). Known installed
+versions are stored separately from requested pins to make patch substitutions
+visible without changing bundle ownership or manifest identity.
"""
from __future__ import annotations
-from dataclasses import dataclass, replace
+from dataclasses import dataclass, field, replace
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
@@ -27,6 +29,7 @@ class InstalledBundleRecord:
contributed_components: tuple[ComponentRef, ...]
required_components: tuple[ComponentRef, ...]
installed_at: str
+ installed_versions: dict[str, str] = field(default_factory=dict)
@classmethod
def create(
@@ -36,6 +39,7 @@ class InstalledBundleRecord:
components: list[ComponentRef],
installed_at: str | None = None,
required_components: list[ComponentRef] | None = None,
+ installed_versions: dict[str, str] | None = None,
) -> "InstalledBundleRecord":
return cls(
bundle_id=bundle_id,
@@ -45,10 +49,13 @@ class InstalledBundleRecord:
components if required_components is None else required_components
),
installed_at=installed_at or _utc_now(),
+ installed_versions=(
+ dict(installed_versions) if installed_versions is not None else {}
+ ),
)
def to_dict(self) -> dict[str, Any]:
- return {
+ data: dict[str, Any] = {
"bundle_id": self.bundle_id,
"version": self.version,
"installed_at": self.installed_at,
@@ -59,6 +66,9 @@ class InstalledBundleRecord:
_component_to_dict(c) for c in self.required_components
],
}
+ if self.installed_versions:
+ data["installed_versions"] = dict(self.installed_versions)
+ return data
@classmethod
def from_dict(cls, data: Any) -> "InstalledBundleRecord":
@@ -108,12 +118,23 @@ class InstalledBundleRecord:
"Corrupt record: 'required_components' must include all "
"'contributed_components'."
)
+ installed_versions = data.get("installed_versions", {})
+ if not isinstance(installed_versions, dict):
+ raise BundlerError("Corrupt record: 'installed_versions' must be a mapping.")
+ keys = {f"{c.kind}:{c.id}" for c in required}
+ for key, actual in installed_versions.items():
+ if key not in keys or not isinstance(actual, str) or not actual.strip():
+ raise BundlerError(
+ "Corrupt record: 'installed_versions' must map required "
+ "component keys (kind:id) to non-empty version strings."
+ )
return cls(
bundle_id=bundle_id,
version=version,
installed_at=_text(data.get("installed_at")),
contributed_components=contributed,
required_components=required,
+ installed_versions=dict(installed_versions),
)
diff --git a/src/specify_cli/bundles/references.py b/src/specify_cli/bundles/references.py
index 5f4eab9f8..69f38ebe4 100644
--- a/src/specify_cli/bundles/references.py
+++ b/src/specify_cli/bundles/references.py
@@ -226,28 +226,24 @@ def make_reference_checker(
if _resolved_locally(project_root, component):
return None
- if component.kind in ("presets", "extensions") and component.source is None:
- from .._assets import _locate_bundled_extension, _locate_bundled_preset
+ if component.kind in ("presets", "extensions", "workflows") and component.source is None:
from . import BundlerError
- from .primitives import _assert_pinned_version, _bundled_manifest_version
+ from .primitives import _bundled_component_version, _bundled_pin_warning
+ from .versioning import is_newer_patch
kind = component.kind[:-1]
- locate = (
- _locate_bundled_preset
- if component.kind == "presets"
- else _locate_bundled_extension
- )
- bundled = locate(component.id)
- if bundled is not None:
+ actual = _bundled_component_version(component)
+ if actual is not None and (
+ component.kind != "workflows"
+ or (component.version and is_newer_patch(actual, component.version))
+ ):
try:
- _assert_pinned_version(
- kind.capitalize(),
- component.id,
- component.version,
- _bundled_manifest_version(bundled / f"{kind}.yml", kind),
- )
+ warning = _bundled_pin_warning(kind.capitalize(), component, actual)
except BundlerError as exc:
return str(exc)
+ if warning:
+ warnings.append(warning.message)
+ return None
if allow_network:
in_catalog = _resolved_in_catalog(project_root, component)
diff --git a/src/specify_cli/bundles/versioning.py b/src/specify_cli/bundles/versioning.py
index c13728c2b..19ea4e72f 100644
--- a/src/specify_cli/bundles/versioning.py
+++ b/src/specify_cli/bundles/versioning.py
@@ -123,3 +123,17 @@ def is_semver(value: str) -> bool:
text = str(value)
core = text[1:] if text[:1] in ("v", "V") else text
return bool(_SEMVER_RE.fullmatch(core))
+
+
+def is_newer_patch(actual: str, pinned: str) -> bool:
+ """Accept only stable SemVer patch upgrades within the same major/minor."""
+ if not is_semver(actual) or not is_semver(pinned):
+ return False
+ cores = []
+ for value in (actual, pinned):
+ core = value.lstrip("vV").split("+", 1)[0]
+ if "-" in core:
+ return False
+ cores.append(tuple(int(part) for part in core.split(".")))
+ resolved, requested = cores
+ return resolved[:2] == requested[:2] and resolved[2] > requested[2]
diff --git a/tests/specify_cli/bundles/test_command_install.py b/tests/specify_cli/bundles/test_command_install.py
index 53c8d773d..2f54f051d 100644
--- a/tests/specify_cli/bundles/test_command_install.py
+++ b/tests/specify_cli/bundles/test_command_install.py
@@ -29,6 +29,79 @@ runner = CliRunner()
REPO_ROOT = Path(__file__).parents[3]
[email protected]("refresh", [False, True])
+def test_bundled_patch_upgrade_warns_and_records_actual_version(
+ project: Path, monkeypatch, refresh: bool,
+):
+ import specify_cli._assets as assets
+ from specify_cli.bundles.records import load_records
+
+ source = project / "packaged-bug"
+ shutil.copytree(REPO_ROOT / "extensions" / "bug", source)
+ source_manifest = source / "extension.yml"
+ data = yaml.safe_load(source_manifest.read_text(encoding="utf-8"))
+ data["extension"]["version"] = "1.0.0" if refresh else "1.0.1"
+ source_manifest.write_text(yaml.safe_dump(data), encoding="utf-8")
+ monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: source)
+ bundle = write_manifest(
+ project / "custom-bundle",
+ valid_manifest_dict(provides={"extensions": [{"id": "bug", "version": "1.0.0"}]}),
+ )
+ args = ["bundle", "install", str(bundle), "--offline"]
+ if refresh:
+ initial = runner.invoke(app, args)
+ assert initial.exit_code == 0, initial.output
+ data["extension"]["version"] = "1.0.1"
+ source_manifest.write_text(yaml.safe_dump(data), encoding="utf-8")
+ args.append("--refresh")
+
+ result = runner.invoke(app, args)
+
+ assert result.exit_code == 0, result.output
+ output = " ".join(result.output.split())
+ assert "Warning:" in output
+ assert "1.0.0" in output and "1.0.1" in output
+ record = load_records(project)[0]
+ assert record.contributed_components[0].version == "1.0.0"
+ assert record.installed_versions == {"extensions:bug": "1.0.1"}
+ installed = yaml.safe_load(
+ (project / ".specify/extensions/bug/extension.yml").read_text(encoding="utf-8")
+ )
+ assert installed["extension"]["version"] == "1.0.1"
+ listed = runner.invoke(app, ["bundle", "list", "--json"])
+ assert listed.exit_code == 0, listed.output
+ assert json.loads(listed.stdout)[0]["installed_versions"] == record.installed_versions
+ repeated = runner.invoke(app, ["bundle", "install", str(bundle), "--offline"])
+ assert repeated.exit_code == 0, repeated.output
+ assert load_records(project)[0].installed_versions == record.installed_versions
+ shared_data = valid_manifest_dict(
+ provides={"extensions": [{"id": "bug", "version": "1.0.0"}]},
+ )
+ shared_data["bundle"]["id"] = "shared-bundle"
+ shared = write_manifest(project / "shared-bundle", shared_data)
+ shared_result = runner.invoke(app, ["bundle", "install", str(shared), "--offline"])
+ assert shared_result.exit_code == 0, shared_result.output
+ shared_refresh = runner.invoke(
+ app, ["bundle", "install", str(bundle), "--offline", "--refresh"],
+ )
+ assert shared_refresh.exit_code == 0, shared_refresh.output
+ shared_data["bundle"]["id"] = "conflicting-bundle"
+ shared_data["provides"]["extensions"][0]["version"] = "1.0.1"
+ conflicting = write_manifest(project / "conflicting-bundle", shared_data)
+ rejected = runner.invoke(
+ app, ["bundle", "install", str(conflicting), "--offline"],
+ )
+ assert rejected.exit_code == 1, rejected.output
+ assert {r.bundle_id for r in load_records(project)} == {"demo-bundle", "shared-bundle"}
+ removed = runner.invoke(app, ["bundle", "remove", "demo-bundle"])
+ assert removed.exit_code == 0, removed.output
+ assert (project / ".specify/extensions/bug").exists()
+ assert load_records(project)[0].installed_versions == record.installed_versions
+ removed_shared = runner.invoke(app, ["bundle", "remove", "shared-bundle"])
+ assert removed_shared.exit_code == 0, removed_shared.output
+ assert not (project / ".specify/extensions/bug").exists()
+
+
def _bundled_workflow_manifest(workflow_id: str, version: str = "1.0.0") -> dict:
return valid_manifest_dict(
provides={"workflows": [{"id": workflow_id, "version": version}]}
diff --git a/tests/specify_cli/bundles/test_command_validate.py b/tests/specify_cli/bundles/test_command_validate.py
index cf4d01524..d09f7a4d6 100644
--- a/tests/specify_cli/bundles/test_command_validate.py
+++ b/tests/specify_cli/bundles/test_command_validate.py
@@ -20,6 +20,69 @@ from tests.specify_cli.bundles.helpers import (
runner = CliRunner()
+ "actual,exit_code,warning",
+ [("1.0.1", 0, True), ("1.0.0", 0, False), ("0.9.9", 1, False),
+ ("1.1.0", 1, False), ("2.0.0", 1, False), ("1.0.1-rc1", 1, False)],
+)
+def test_validate_bundled_patch_compatibility(
+ project: Path, monkeypatch, actual: str, exit_code: int, warning: bool,
+):
+ import specify_cli._assets as assets
+
+ payload = project / "packaged-extension"
+ payload.mkdir()
+ (payload / "extension.yml").write_text(
+ yaml.safe_dump({"extension": {"id": "x", "version": actual}}), encoding="utf-8",
+ )
+ monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: payload)
+ data = valid_manifest_dict(
+ provides={"extensions": [{"id": "x", "version": "1.0.0"}]},
+ )
+ (project / "bundle.yml").write_text(yaml.safe_dump(data), encoding="utf-8")
+
+ result = runner.invoke(app, ["bundle", "validate", "--offline"])
+
+ assert result.exit_code == exit_code, result.output
+ assert ("newer packaged patch" in " ".join(result.output.split())) is warning
+
+
[email protected]("offline", [False, True])
+def test_validate_bundled_workflow_patch_warns_without_catalog_lookup(
+ project: Path, monkeypatch, offline: bool,
+):
+ import specify_cli._assets as assets
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ payload = project / "packaged-workflow"
+ payload.mkdir()
+ (payload / "workflow.yml").write_text(
+ yaml.safe_dump({"workflow": {"id": "x", "version": "1.0.1"}}),
+ encoding="utf-8",
+ )
+ monkeypatch.setattr(assets, "_locate_bundled_workflow", lambda cid: payload)
+ monkeypatch.setattr(
+ WorkflowCatalog, "get_active_catalogs",
+ lambda self: pytest.fail("a compatible packaged patch must not consult catalogs"),
+ )
+ data = valid_manifest_dict(
+ provides={"workflows": [{"id": "x", "version": "1.0.0"}]},
+ )
+ (project / "bundle.yml").write_text(yaml.safe_dump(data), encoding="utf-8")
+ args = ["bundle", "validate"]
+ if offline:
+ args.append("--offline")
+
+ result = runner.invoke(app, args)
+
+ assert result.exit_code == 0, result.output
+ output = " ".join(result.output.split())
+ assert "Workflow 'x' is pinned to version 1.0.0" in output
+ assert "Spec Kit ships 1.0.1" in output
+ assert output.count("newer packaged patch") == 1
+ assert "well-formed and valid" in output
+
+
def test_validate_reports_invalid_manifest(project: Path):
data = valid_manifest_dict()
del data["bundle"]["license"]
diff --git a/tests/specify_cli/bundles/test_commands.py b/tests/specify_cli/bundles/test_commands.py
index e0d054d21..57ae60c72 100644
--- a/tests/specify_cli/bundles/test_commands.py
+++ b/tests/specify_cli/bundles/test_commands.py
@@ -16,6 +16,46 @@ from tests.conftest import strip_ansi # noqa: F401
runner = CliRunner()
[email protected]("command", ["install", "add", "init", "update"])
+def test_install_adapters_render_structured_warnings_once(
+ project: Path, monkeypatch, command: str,
+):
+ from types import SimpleNamespace
+
+ from specify_cli.bundles import command_update, installer
+ from specify_cli.bundles.manifest import BundleManifest, ComponentRef
+ from specify_cli.bundles.primitives import _bundled_pin_warning
+ from specify_cli.bundles.records import InstalledBundleRecord, save_records
+ from tests.specify_cli.bundles.helpers import valid_manifest_dict, write_manifest
+
+ data = valid_manifest_dict()
+ manifest = BundleManifest.from_dict(data)
+ component = ComponentRef(kind="extensions", id="x[/yellow]", version="1.0.0")
+ warning = _bundled_pin_warning("Extension", component, "1.0.1")
+ assert warning is not None
+ outcome = installer.InstallResult(bundle_id=manifest.bundle.id, warnings=[warning])
+ monkeypatch.setattr(installer, "install_bundle", lambda *a, **kw: outcome)
+
+ if command == "update":
+ save_records(project, [
+ InstalledBundleRecord.create(manifest.bundle.id, manifest.bundle.version, []),
+ ])
+ stack = SimpleNamespace(resolve=lambda target: SimpleNamespace(install_allowed=True))
+ monkeypatch.setattr(command_update, "_build_stack", lambda *a, **kw: stack)
+ monkeypatch.setattr(command_update, "_download_manifest", lambda *a, **kw: manifest)
+ target = manifest.bundle.id
+ else:
+ target = str(write_manifest(project / "bundle-source", data))
+
+ result = runner.invoke(app, ["bundle", command, target, "--offline"])
+
+ assert result.exit_code == 0, result.output
+ assert result.stderr.count("Warning:") == 1
+ assert "x[/yellow]" in strip_ansi(result.stderr)
+ assert "newer packaged patch" in " ".join(result.stderr.split())
+ assert "Warning:" not in result.stdout
+
+
def test_bundle_help_lists_all_commands():
result = runner.invoke(app, ["bundle", "--help"])
assert result.exit_code == 0
diff --git a/tests/specify_cli/bundles/test_installer.py b/tests/specify_cli/bundles/test_installer.py
index 6dafa3686..7830f1eda 100644
--- a/tests/specify_cli/bundles/test_installer.py
+++ b/tests/specify_cli/bundles/test_installer.py
@@ -32,6 +32,49 @@ def _plan(manifest):
)
[email protected]("action", ["install", "reuse", "refresh"])
+def test_install_returns_structured_patch_warnings_without_printing(
+ tmp_path: Path, capsys, action: str,
+):
+ from specify_cli.bundles.primitives import _bundled_pin_warning
+
+ class PatchInstaller(FakeInstaller):
+ def install(self, project_root, component):
+ super().install(project_root, component)
+ self.versions[self._key(component)] = "1.0.1"
+ return _bundled_pin_warning("Extension", component, "1.0.1")
+
+ def refresh(self, project_root, component):
+ super().refresh(project_root, component)
+ return _bundled_pin_warning("Extension", component, "1.0.1")
+
+ def bundled_patch_warning(self, component, actual):
+ return _bundled_pin_warning("Extension", component, actual)
+
+ make_project(tmp_path)
+ manifest = BundleManifest.from_dict(valid_manifest_dict(
+ provides={"extensions": [{"id": "x", "version": "1.0.0"}]},
+ ))
+ installer = PatchInstaller()
+ if action != "install":
+ install_bundle(tmp_path, _plan(manifest), installer, manifest=manifest)
+ capsys.readouterr()
+
+ result = install_bundle(
+ tmp_path, _plan(manifest), installer,
+ manifest=manifest, refresh=action == "refresh",
+ )
+
+ assert capsys.readouterr() == ("", "")
+ assert len(result.warnings) == 1
+ warning = result.warnings[0]
+ assert warning.code == "bundled_patch_upgrade"
+ assert warning.details.component_id == "x"
+ assert warning.details.requested_version == "1.0.0"
+ assert warning.details.installed_version == "1.0.1"
+ assert "newer packaged patch" in warning.message
+
+
def test_install_records_and_invokes_primitives(tmp_path: Path):
make_project(tmp_path)
manifest = BundleManifest.from_dict(valid_manifest_dict())
@@ -40,6 +83,7 @@ def test_install_records_and_invokes_primitives(tmp_path: Path):
result = install_bundle(tmp_path, _plan(manifest), installer, manifest=manifest)
assert len(result.installed) == 4
+ assert result.warnings == []
assert len(installer.install_calls) == 4
records = load_records(tmp_path)
assert len(records) == 1
diff --git a/tests/specify_cli/bundles/test_primitives.py b/tests/specify_cli/bundles/test_primitives.py
index 4c62012aa..d92d9a0f9 100644
--- a/tests/specify_cli/bundles/test_primitives.py
+++ b/tests/specify_cli/bundles/test_primitives.py
@@ -603,6 +603,117 @@ def _write_manifest(path: Path, root_key: str, version: str) -> Path:
return path
[email protected]("kind", ["extensions", "presets", "workflows"])
[email protected]("action", ["install", "refresh"])
+def test_bundled_newer_patch_warns(
+ tmp_path: Path, monkeypatch, capsys, kind: str, action: str,
+):
+ import specify_cli
+ import specify_cli._assets as assets
+ from specify_cli.extensions import ExtensionManager
+ from specify_cli.presets import PresetManager
+
+ bundled = _write_manifest(tmp_path / "payload", kind[:-1], "1.0.1")
+ monkeypatch.setattr(assets, f"_locate_bundled_{kind[:-1]}", lambda cid: bundled)
+ calls = []
+ if kind == "workflows":
+ monkeypatch.setattr(specify_cli, "workflow_add", lambda *a, **kw: calls.append(a))
+ else:
+ manager_type = ExtensionManager if kind == "extensions" else PresetManager
+
+ def install(self, *args, **kwargs):
+ calls.append(args)
+ return SimpleNamespace(id="x")
+
+ monkeypatch.setattr(manager_type, "install_from_directory", install)
+ if kind == "extensions":
+ monkeypatch.setattr(manager_type, "scaffold_config", lambda *a: None)
+ manager = primitive_manager(kind, tmp_path, allow_network=False)
+
+ warning = getattr(manager, action)(ComponentRef(kind=kind, id="x", version="1.0.0"))
+
+ assert len(calls) == 1
+ assert warning is not None
+ assert warning.code == "bundled_patch_upgrade"
+ assert warning.details.kind == kind
+ assert warning.details.component_id == "x"
+ assert warning.details.requested_version == "1.0.0"
+ assert warning.details.installed_version == "1.0.1"
+ assert capsys.readouterr() == ("", "")
+
+
[email protected]("actual", [
+ "0.9.9", "1.0.0", "1.1.0", "2.0.0", "1.0.2-rc1", "1.0.2-alpha.1",
+])
+def test_bundled_extension_incompatible_versions_still_refuse(
+ tmp_path: Path, monkeypatch, actual: str,
+):
+ import specify_cli._assets as assets
+ from specify_cli.extensions import ExtensionManager
+
+ bundled = _write_manifest(tmp_path / "payload", "extension", actual)
+ monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
+ calls = []
+ monkeypatch.setattr(
+ ExtensionManager, "install_from_directory", lambda *a, **kw: calls.append(a),
+ )
+ manager = primitive_manager("extensions", tmp_path, allow_network=False)
+
+ with pytest.raises(BundlerError, match="pinned to version 1.0.1"):
+ manager.install(ComponentRef(kind="extensions", id="x", version="1.0.1"))
+ assert calls == []
+
+
+def test_catalog_extension_newer_patch_still_refuses(tmp_path: Path, monkeypatch):
+ import specify_cli._assets as assets
+ from specify_cli.extensions import ExtensionCatalog
+
+ monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: None)
+ _patch_winning_entry(monkeypatch, {"version": "1.0.1"})
+ downloads = []
+ monkeypatch.setattr(
+ ExtensionCatalog, "download_extension_info", lambda *a: downloads.append(a),
+ )
+ manager = primitive_manager("extensions", tmp_path)
+ with pytest.raises(BundlerError, match="pinned to version 1.0.0"):
+ manager.install(ComponentRef(kind="extensions", id="x", version="1.0.0"))
+ assert downloads == []
+
+
+def test_explicit_source_does_not_relax_bundled_pin(tmp_path: Path, monkeypatch):
+ import specify_cli._assets as assets
+
+ bundled = _write_manifest(tmp_path / "payload", "extension", "1.0.1")
+ monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
+ _patch_winning_entry(
+ monkeypatch, {"version": "1.0.1", "_catalog_name": "custom-catalog"},
+ )
+ manager = primitive_manager("extensions", tmp_path)
+
+ with pytest.raises(BundlerError, match="pinned to version 1.0.0"):
+ manager.install(ComponentRef(
+ kind="extensions", id="x", version="1.0.0", source="custom-catalog",
+ ))
+
+
[email protected]("actual,compatible", [
+ ("1.0.1", True), ("1.0.2", False), ("1.0.0", False), ("1.1.0", False),
+])
+def test_installed_patch_must_match_packaged_version(
+ tmp_path: Path, monkeypatch, actual: str, compatible: bool,
+):
+ import specify_cli._assets as assets
+
+ bundled = _write_manifest(tmp_path / "payload", "extension", "1.0.1")
+ monkeypatch.setattr(assets, "_locate_bundled_extension", lambda cid: bundled)
+ installer = DefaultPrimitiveInstaller(allow_network=False)
+
+ warning = installer.bundled_patch_warning(
+ ComponentRef(kind="extensions", id="x", version="1.0.0"), actual,
+ )
+ assert (warning is not None) is compatible
+
+
def test_bundled_extension_pin_mismatch_refuses(tmp_path: Path, monkeypatch):
"""A bundled extension whose version != the manifest pin must be refused
(the bundled path previously skipped the pin the catalog path enforces)."""
diff --git a/tests/specify_cli/bundles/test_records.py b/tests/specify_cli/bundles/test_records.py
index f8caa2c5e..7de2a1450 100644
--- a/tests/specify_cli/bundles/test_records.py
+++ b/tests/specify_cli/bundles/test_records.py
@@ -124,6 +124,42 @@ def test_from_dict_rejects_requirements_missing_contributed_pin(required):
InstalledBundleRecord.from_dict(data)
+def test_record_preserves_requested_and_installed_versions(tmp_path: Path):
+ rec = InstalledBundleRecord.create(
+ bundle_id="demo", version="1.0.0",
+ components=[ComponentRef(kind="extensions", id="bug", version="1.0.0")],
+ installed_versions={"extensions:bug": "1.0.1"},
+ )
+ save_records(tmp_path, [rec])
+
+ loaded = load_records(tmp_path)[0]
+ assert loaded.contributed_components[0].version == "1.0.0"
+ assert loaded.installed_versions == {"extensions:bug": "1.0.1"}
+ assert loaded.to_dict()["installed_versions"] == {"extensions:bug": "1.0.1"}
+
+
+def test_legacy_record_has_no_installed_versions():
+ rec = InstalledBundleRecord.from_dict(
+ {"bundle_id": "demo", "version": "1.0.0", "contributed_components": []},
+ )
+ assert rec.installed_versions == {}
+ assert "installed_versions" not in rec.to_dict()
+
+
[email protected]("versions", [
+ None, [], "1.0.1", False,
+ {"extensions:bug": ""}, {"extensions:bug": " "},
+ {"extensions:bug": 1}, {"extensions:other": "1.0.1"},
+])
+def test_record_rejects_invalid_installed_versions(versions):
+ with pytest.raises(BundlerError, match="installed_versions"):
+ InstalledBundleRecord.from_dict({
+ "bundle_id": "demo", "version": "1.0.0",
+ "contributed_components": [{"kind": "extensions", "id": "bug"}],
+ "installed_versions": versions,
+ })
+
+
def test_load_missing_file_returns_empty(tmp_path: Path):
(tmp_path / ".specify").mkdir()
assert load_records(tmp_path) == []
diff --git a/tests/specify_cli/bundles/test_references.py b/tests/specify_cli/bundles/test_references.py
index 80896f6d9..261e1b266 100644
--- a/tests/specify_cli/bundles/test_references.py
+++ b/tests/specify_cli/bundles/test_references.py
@@ -287,6 +287,65 @@ def test_online_validation_warns_for_extension_http_protocol_error(
assert len(warnings) == 1 and "unreachable" in warnings[0]
[email protected]("packaged_version", ["1.1.0", "2.0.0", "1.0.1-rc1"])
[email protected]("historical_version", ["1.0.0", "1.0.2", None])
+def test_incompatible_bundled_workflow_requires_exact_historical_release(
+ tmp_path: Path, monkeypatch, packaged_version: str, historical_version: str | None,
+):
+ import specify_cli._assets as assets
+ from specify_cli.bundles import component_catalog
+ from specify_cli.workflows.catalog import WorkflowCatalog
+
+ root = make_project(tmp_path)
+ payload = root / "packaged-workflow"
+ payload.mkdir()
+ (payload / "workflow.yml").write_text(
+ yaml.safe_dump({"workflow": {"id": "x", "version": packaged_version}}),
+ encoding="utf-8",
+ )
+ monkeypatch.setattr(assets, "_locate_bundled_workflow", lambda cid: payload)
+ entry = {
+ "version": "3.0.0",
+ "url": "https://example.com/current.yml",
+ "sha256": "b" * 64,
+ "releases": {},
+ }
+ if historical_version is not None:
+ entry["releases"][historical_version] = {
+ "url": "https://example.com/historical.yml",
+ "sha256": "a" * 64,
+ }
+ _mock_catalog(monkeypatch, WorkflowCatalog, "workflows", "x", entry)
+ original_select = component_catalog.select_catalog_release
+ selections = []
+
+ def select(component, current):
+ selected = original_select(component, current)
+ selections.append((component.version, selected))
+ return selected
+
+ monkeypatch.setattr(component_catalog, "select_catalog_release", select)
+ warnings = []
+ check = make_reference_checker(root, allow_network=True, warnings=warnings)
+
+ problem = check(_ref("workflows", "x"))
+
+ assert len(selections) == 1
+ requested, selected = selections[0]
+ assert requested == "1.0.0"
+ if historical_version == "1.0.0":
+ assert problem is None
+ assert selected is not None
+ assert selected["version"] == "1.0.0"
+ assert selected["url"] == "https://example.com/historical.yml"
+ assert selected["sha256"] == "a" * 64
+ else:
+ assert problem is not None
+ assert "workflow 'x' at 1.0.0 is not available" in problem
+ assert selected is None
+ assert warnings == []
+
+
def test_online_validation_checks_winning_exact_release_and_source(tmp_path, monkeypatch):
import specify_cli._assets as assets
from specify_cli.workflows.catalog import WorkflowCatalog
diff --git a/tests/specify_cli/bundles/test_versioning.py b/tests/specify_cli/bundles/test_versioning.py
index 4729a3f75..a5748cdd5 100644
--- a/tests/specify_cli/bundles/test_versioning.py
+++ b/tests/specify_cli/bundles/test_versioning.py
@@ -4,7 +4,29 @@ from __future__ import annotations
import pytest
from specify_cli.bundler import BundlerError
-from specify_cli.bundles.versioning import is_semver, satisfies
+from specify_cli.bundles.versioning import is_newer_patch, is_semver, satisfies
+
+
[email protected]("actual,pinned,expected", [
+ ("1.0.1", "1.0.0", True),
+ ("1.0.10", "1.0.2", True),
+ ("V1.0.1", "v1.0.0", True),
+ ("1.0.1+build-2", "1.0.0+build-1", True),
+ ("0.0.2", "0.0.1", True),
+ ("1.0.0", "1.0.0", False),
+ ("1.0.0+new", "1.0.0+old", False),
+ ("1.0.0", "1.0.1", False),
+ ("1.1.0", "1.0.0", False),
+ ("2.0.0", "1.0.0", False),
+ ("1.0.1-rc1", "1.0.0", False),
+ ("1.0.1", "1.0.0-rc1", False),
+ ("1.0.1-rc2", "1.0.0-rc1", False),
+ ("1.0", "1.0.0", False),
+ ("1.0.1", "invalid", False),
+ ("invalid", "1.0.0", False),
+])
+def test_is_newer_patch(actual: str, pinned: str, expected: bool):
+ assert is_newer_patch(actual, pinned) is expected
@pytest.mark.parametrize("value,expected", [