feat(bundles): select exact bundle catalog releases by markuswondrak · Pull Request #4849 · github/spec-kit

markuswondrak · 2026-10-06T13:41:34Z

Description

Part of #4719. This is the Bundle catalog slice: a bundle catalog entry can advertise historical releases under one catalog ID.

What changes

specify bundle install|add <id> --version <v> selects the exact release from the winning catalog source. Historical artifacts use their own download URL and SHA-256 digest through the existing secure download path.
specify bundle info <id> --versions lists current and historical releases without downloading a manifest.
Release history is validated when its catalog source loads, together with other entry fields. Duplicate JSON keys anywhere in a catalog are rejected at parse time. A malformed releases mapping makes the consulted source fail for install, info, update, and search. Resolution stops at the first source listing an ID, while search loads every source.
The historical artifact manifest must declare the same bundle ID and same semantic version as the selected release. same_version accepts equivalent spellings such as v1.1.0/1.1.0 and 1.0.0-rc.1/1.0.0-rc1; the catalog key spelling is display-only.
Version lookup does not fall through to a lower-priority source. Discovery-only sources remain non-installable. bundle update continues to select the current release.

Non-goal: component version pins inside bundle manifests (#4712, handled by #4753).

Testing

Added raw-JSON duplicate-key coverage for bare paths, file:// URLs, HTTP responses, and packaged snapshots.
Added eager release-history validation, ID-error ordering, resolve/search shadowing, semantic manifest-version, and parser-agreement coverage.
Replaced timestamp-sensitive installed-record byte comparison with semantic record comparison.
Passed uv sync --extra test.
Passed .venv/bin/python -m pytest tests/specify_cli/bundles tests/contract/test_firstparty_bundle_catalog_consistency.py -q: 578 passed.
Passed uvx ruff@0.15.0 check src tests.
The full suite was started but exceeded the 120-second execution limit after 47%. It exposed an unrelated existing failure in tests/integration/test_preset_update_workflow.py::test_preset_update_cli_contract, whose expected Typer/Click missing-argument text differs from the installed dependency output; the isolated file result was 1 failed, 3 passed.

AI Disclosure

Initial implementation: GitHub Copilot CLI with GPT-5.6 Terra, autonomous, generated the original code, tests, and docs.
Prior review and fixes: GitHub Copilot CLI with Claude Opus 5.5, autonomous under the contributor's direction.
This review-fix commit and PR update: OpenCode with github-copilot/gpt-5.6-terra, autonomous, implemented the duplicate-key, eager-validation, normalized-version, test, documentation, and PR-description updates.
The commit carries its own Assisted-by: trailer.

Add the bundle catalog slice of github#4719. A bundle catalog entry may now advertise historical releases in an optional `releases` mapping, following the extension, preset, workflow and step slices. - `bundle install/add <id> --version <v>` installs an exact catalog release from the winning source; the historical download URL, digest and manifest ID/version checks flow through the existing download path. - `bundle info <id> --versions` lists the current and historical releases (text and JSON) without downloading a manifest. - Release history is validated lazily; `requires`, `provides` and `verified` are never inherited by historical releases. - Lookup never falls through to a lower-priority source, and discovery-only sources stay non-installable. Assisted-by: GitHub Copilot CLI (model: GPT-5.6 Terra, autonomous) Assisted-by: GitHub Copilot CLI (model: Claude Opus 5.5, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot review overview

🟡 Changes recommended

Catalog validation and manifest version matching still have unresolved correctness issues.

Review effort: Balanced
Findings: 1 · 1

Open (2)

Preserve and reject duplicate release keys in catalogs · New
Normalize catalog and manifest versions before comparison · New

What changed in this PR

Adds exact bundle-release selection to Specify CLI’s catalog support for #4719, without changing bundle component pins.

Changes:

Adds --version to bundle install/add.
Adds release-history validation and info --versions.
Documents the format and adds focused regression coverage.

AI disclosure: GitHub Copilot (model unknown, autonomous review) prepared this review for the requester.

File	Description
`tests/specify_cli/bundles/test_command_install.py`	Tests invalid option combinations.
`tests/specify_cli/bundles/test_command_install_version.py`	Covers historical installs and verification failures.
`tests/specify_cli/bundles/test_command_info.py`	Tests version listings and errors.
`tests/specify_cli/bundles/test_command_add.py`	Checks version-option forwarding.
`tests/specify_cli/bundles/test_catalog_versions.py`	Tests release validation and selection.
`tests/specify_cli/bundles/test_catalog_stack.py`	Covers precedence and lazy validation.
`src/specify_cli/bundles/command_install.py`	Supports exact-release installation.
`src/specify_cli/bundles/command_info.py`	Displays available releases.
`src/specify_cli/bundles/command_add.py`	Forwards exact-version requests.
`src/specify_cli/bundles/catalogs.py`	Preserves raw release metadata.
`src/specify_cli/bundles/catalog_versions.py`	Validates, selects, and lists releases.
`src/specify_cli/bundles/catalog_stack.py`	Resolves versions from the winning source.
`docs/reference/bundles.md`	Documents release history and CLI options.

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

Copilot review overview

🔵 Needs a closer look

Standard test and lint runs remain unverified, so the catalog installation changes need maintainer validation.

Review effort: Balanced
Findings: 1 · 1

Open (2)

Preserve and reject duplicate release keys in catalogs
Normalize catalog and manifest versions before comparison

mnriem · 2026-10-06T14:04:46Z

Please address Copilot feedback and fix test & lint errors

Reject duplicate JSON keys before decoding bundle catalogs, validate release history as catalog entries load, and compare catalog and manifest versions semantically. Assisted-by: OpenCode (model: github-copilot/gpt-5.6-terra, autonomous)

markuswondrak · 2026-10-06T16:13:13Z

Review-fix round for @markuswondrak: pushed 22ae59f9 (fix(bundles): validate catalog releases on load).

The change rejects duplicate JSON keys before bundle catalog decoding, validates releases when each source loads, compares selected catalog and manifest versions with same_version, updates documentation and the PR description, and replaces the timestamp-sensitive record assertion. It also adds coverage for all catalog decoding paths, eager load failures, shadowed-source behavior, and equivalent version spellings.

Verification: uv sync --extra test; .venv/bin/python -m pytest tests/specify_cli/bundles tests/contract/test_firstparty_bundle_catalog_consistency.py -q (578 passed); uvx ruff@0.15.0 check src tests (passed). The full suite exceeded the 120-second tool limit at 47% and exposed an unrelated pre-existing assertion mismatch in tests/integration/test_preset_update_workflow.py::test_preset_update_cli_contract; isolated result: 1 failed, 3 passed.

AI disclosure: posted on behalf of Markus Wondrak by OpenCode using github-copilot/gpt-5.6-terra in autonomous mode. Extent: implemented the review fixes, ran verification, updated the PR description, and drafted this comment.

markuswondrak · 2026-10-06T16:14:05Z

Follow-up context for the review findings: the two issues came from inconsistent behavior across catalog slices.

Presets and workflow steps reject duplicate JSON object keys during decoding with object_pairs_hook, while the bundle implementation originally checked parsed mappings after json.loads() had already collapsed duplicates. This fix matches the preset/step behavior for bundle catalogs: duplicate keys anywhere in the JSON document now fail at parse time. Extensions, integrations, and workflow catalogs still use plain JSON decoding; bringing them into line is outside this bundle-catalog PR and should be handled separately.

For manifest identity, extensions and presets compare parsed versions, while the original bundle release selection used parsed equality but compared the selected catalog version and manifest version as raw strings. This fix uses bundles.versioning.same_version, so equivalent SemVer spellings such as v1.1.0/1.1.0 and 1.0.0-rc.1/1.0.0-rc1 install consistently.

AI disclosure: posted on behalf of Markus Wondrak by OpenCode using github-copilot/gpt-5.6-terra in autonomous mode. Extent: verified the cross-slice implementation details and drafted this follow-up explanation.

Copilot

Copilot review overview

🟢 Approval recommended

Static inspection found no blocking defects, and the supplied regression coverage addresses release selection, integrity, and source policy.

Review effort: Balanced
Findings: None

Resolved since last review (2)

Preserve and reject duplicate release keys in catalogs
Normalize catalog and manifest versions before comparison

Copilot

Copilot review overview

🟡 Changes recommended

Catalog validation still accepts release metadata that violates the documented validation and download contracts.

Review effort: Balanced
Findings: 2

Open (2)

Reject trailing whitespace in semantic version keys · New
Align URL validation with download HTTPS policy · New

mnriem · 2026-10-06T19:09:10Z

Please address Copilot feedback. If not applicable, please explain why

- is_semver() now uses fullmatch(), so a trailing newline in a release key or version is rejected instead of passing the `$`-anchored regex. - Bundle _require_https() delegates to is_https_or_localhost_http(), so catalog validation and download enforce the same URL policy (e.g. http://127.0.0.2 and expanded IPv6 loopback are accepted consistently). Assisted-by: OpenCode (model: github-copilot/claude-sonnet-5.5, autonomous)

markuswondrak · 2026-10-07T05:32:46Z

AI-generated comment, posted on behalf of @markuswondrak by OpenCode (model: github-copilot/claude-sonnet-5.5, supervised by the contributor; code generation and test updates).

Addressed both findings in 069ef3f:

is_semver() now uses fullmatch(), so a release key like "1.1.0\n" is rejected in all bundle callers. Regression cases added in test_versioning.py and test_catalog_versions.py.
Bundle _require_https() now delegates to is_https_or_localhost_http(), matching the policy that catalog validation and the other download paths already use. Regression tests cover http://127.0.0.2 and expanded IPv6 loopback (accepted) and remote HTTP (rejected).

The new tests fail without the source changes and pass with them; tests/specify_cli/bundles passes (580 passed).

Copilot

Copilot review overview

🟢 Approval recommended

No blocking defects remain, and focused regression coverage addresses selection, precedence, integrity, and validation failures.

Review effort: Balanced
Findings: None

Resolved since last review (2)

Align URL validation with download HTTPS policy
Reject trailing whitespace in semantic version keys

Copilot

🟢 Approval recommended

Targeted inspection found no blocking defects, and focused regression coverage addresses selection, precedence, validation, and artifact integrity.

0 open findings

🧠 Review effort: Balanced

mnriem · 2026-10-07T18:31:40Z

Thank you!

markuswondrak requested a review from mnriem as a code owner October 6, 2026 13:41

Copilot AI balanced review requested due to automatic review settings October 6, 2026 13:41

Copilot started reviewing on behalf of markuswondrak October 6, 2026 13:42 View session

Copilot AI reviewed Oct 6, 2026

View reviewed changes

Comment thread src/specify_cli/bundles/catalog_versions.py

Comment thread src/specify_cli/bundles/catalog_versions.py

mnriem requested a balanced review from Copilot October 6, 2026 13:52

Copilot started reviewing on behalf of mnriem October 6, 2026 13:53 View session

Copilot AI reviewed Oct 6, 2026

View reviewed changes

fix(bundles): validate catalog releases on load

22ae59f

Reject duplicate JSON keys before decoding bundle catalogs, validate release history as catalog entries load, and compare catalog and manifest versions semantically. Assisted-by: OpenCode (model: github-copilot/gpt-5.6-terra, autonomous)

Copilot AI balanced review requested due to automatic review settings October 6, 2026 16:13

Copilot started reviewing on behalf of markuswondrak October 6, 2026 16:13 View session

Copilot AI reviewed Oct 6, 2026

View reviewed changes

mnriem requested a balanced review from Copilot October 6, 2026 18:20

Copilot started reviewing on behalf of mnriem October 6, 2026 18:20 View session

Copilot AI reviewed Oct 6, 2026

View reviewed changes

Comment thread src/specify_cli/bundles/catalog_versions.py

Comment thread src/specify_cli/bundles/catalog_versions.py

Copilot AI balanced review requested due to automatic review settings October 7, 2026 05:32

Copilot started reviewing on behalf of markuswondrak October 7, 2026 05:33 View session

Copilot AI reviewed Oct 7, 2026

View reviewed changes

mnriem requested a balanced review from Copilot October 7, 2026 15:28

Copilot started reviewing on behalf of mnriem October 7, 2026 15:29 View session

Copilot AI reviewed Oct 7, 2026

View reviewed changes

mnriem merged commit 6f00b1f into github:main Oct 7, 2026
15 checks passed

mnriem mentioned this pull request Oct 9, 2026

[Feature]: Support multiple versions per ID across catalog types #4719

Closed

Conversation

markuswondrak commented Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

AI Disclosure

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🔵 Needs a closer look

Uh oh!

mnriem commented Oct 6, 2026

Uh oh!

markuswondrak commented Oct 6, 2026

Uh oh!

markuswondrak commented Oct 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

mnriem commented Oct 6, 2026

Uh oh!

markuswondrak commented Oct 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟢 Approval recommended

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

mnriem commented Oct 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

markuswondrak commented Oct 6, 2026 •

edited

Loading