feat(extensions): select exact catalog releases by Doribelove · Pull Request #4726 · github/spec-kit

Doribelove · 2026-09-24T09:06:10Z

Description

An extension catalog currently keeps only its advertised release. Once that entry advances, users cannot select a still-available older archive from the same trusted catalog. In the #4712 reproduction, a bundle pin for 0.4.12 is rejected after the catalog advances to 0.5.1, although the old ZIP still returns HTTP 200. This PR implements the extension-catalog slice of the maintainer's separate-area plan in #4719; bundle pin resolution remains a separate follow-up.

Versioned entries keep the existing top-level version/URL/digest as the current release and may add historical records under releases. specify extension info <id> --versions shows the available versions, and specify extension add <id> --version 0.4.12 selects the exact record from the winning catalog. PEP 440-equivalent version spellings select the same record while preserving its advertised spelling. Ordinary unqualified installs retain their current behavior. Missing versions do not fall through to lower-priority catalogs; discovery-only catalogs remain non-installable. Historical records need their own URL and SHA-256. The selected record is downloaded directly, then the archive's manifest ID and version are checked before installation. Catalog lookup failures are reported distinctly from missing versions. The reference documentation describes the format and this PR's bundle limitation.

Testing

Tested locally with uv run specify --help.
Ran existing tests from this working tree's .venv (full results below).
Tested with a sample project: a localhost catalog advertised 0.5.1 plus a 0.4.12 historical release; extension add --version 0.4.12 requested the old ZIP and installed version 0.4.12.
Focused extension tests after the review-round regressions: 174 passed.
Full test suite with LC_ALL=C: 8,365 passed, 207 skipped (53 warnings). Without the English locale, six unrelated workflow tests compare localized sha256sum output against English strings.
Ruff lint and format checks passed for the version-selection module and regression tests. The touched command modules passed lint with three pre-existing rules (UP045, I001, B018) excluded. git diff --check passed.
A direct markdownlint-cli2 run on the edited reference page reports eight existing violations; the same eight appear on the unmodified main version of that page.

AI Disclosure

I did not use AI assistance for this contribution
I did use AI assistance (fill in the disclosure below)

AI disclosure: OpenAI Codex (GPT-6, autonomous mode at the contributor's request; default task settings, with the precise reasoning level not exposed) generated the reproduction, implementation, tests, documentation, and this PR text, then ran the checks listed above. The contributor reports having independently reviewed and tested the initial patch before marking this PR ready for review. The additional review-round changes in 4615cac and 7fb0973 were generated and validated autonomously by Codex. Subsequent agent-generated review responses will also disclose AI use.

Keep current release metadata compatible with existing catalogs while allowing trusted catalogs to publish historical release URLs and digests. Add exact version selection, archive identity and discovery-policy checks, tests, and documentation. Refs github#4719; follows up github#4712. Assisted-by: OpenAI Codex (model: GPT-6, autonomous) Signed-off-by: 李永祺 <doribelove@gmail.com>

mnriem · 2026-09-24T12:58:43Z

Thanks — this looks like the right first slice of github/spec-kit#4719. The extension-catalog scope is focused and reviewable.

Before approval, could you add tests for the remaining new paths: reject a historical archive with the wrong extension ID or SHA-256 before installation; confirm an unqualified install still selects the advertised current release when releases is present; and cover both a matching and a mismatched packaged version in the bundled exact-version path. The existing tests already cover missing versions, precedence, discovery-only policy, and a wrong archive version.

Posted on behalf of @mnriem by GitHub Copilot (model: GPT-6 Sol, autonomous); comment fully AI-drafted.

Assisted-by: OpenAI Codex (model: GPT-6 Sol, autonomous) Signed-off-by: 李永祺 <doribelove@gmail.com>

Doribelove · 2026-09-24T23:27:00Z

I added the review-round regressions in 4615cac: the exact-release CLI now has tests for rejecting a historical archive with the wrong ID or digest before installation, while the ordinary install test confirms it still uses the advertised current release when history is present. The bundled exact-version tests cover both a packaged-version match and mismatch. This commit changes tests only.

Validation: 169 extension tests passed; the full suite passed with LC_ALL=C (8,360 passed, 207 skipped). Ruff lint/format checks and git diff --check passed. I updated the PR description with the current results. The existing review request to @mnriem remains open.

Posted on behalf of @Doribelove by OpenAI Codex (model: GPT-6 Sol, autonomous); comment fully AI-drafted.

Copilot

Copilot review overview

🟡 Changes recommended

Version comparison inconsistencies and a misleading catalog-failure message need correction.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 3

Open (3)

Normalize catalog version lookup and preserve advertised spelling · New
Compare normalized versions in bundled-install checks · New
Preserve catalog errors when listing extension versions · New

What changed in this PR

Adds exact historical extension release selection while preserving current-release behavior and catalog precedence.

Changes:

Adds versioned catalog parsing, selection, and secure installation.
Adds --version and --versions CLI options.
Documents the release-history format and adds regression coverage.

File	Description
`src/specify_cli/extensions/_catalog_versions.py`	Validates and selects catalog releases.
`src/specify_cli/extensions/__init__.py`	Downloads selected releases and verifies archive identity.
`src/specify_cli/extensions/command_add.py`	Adds exact-version installation.
`src/specify_cli/extensions/command_info.py`	Lists catalog versions.
`tests/specify_cli/extensions/test_catalog_versions.py`	Covers lookup, policy, integrity, and installation behavior.
`docs/reference/extensions.md`	Documents version history and bundle limitations.

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

+    if version is None or version == entry.get("version"):
+        return entry
+    record = releases.get(version)
+    if record is None:
+        return None
+    common = {key: value for key, value in entry.items() if key not in _CURRENT_ONLY}
+    return {**common, **record, "version": version}


+                        from . import ExtensionManifest
+
+                        candidate = _commands._locate_bundled_extension(resolved_id)
+                        if candidate is not None:
+                            bundled_manifest = ExtensionManifest(candidate / "extension.yml")
+                            if bundled_manifest.version == version:


+    if show_versions:
+        _commands.console.print(
+            f"[red]Error:[/red] No catalog versions found for {_escape_markup(extension)}."
+        )
+        raise typer.Exit(1)


Assisted-by: OpenAI Codex (model: GPT-6 Sol, autonomous) Signed-off-by: 李永祺 <doribelove@gmail.com>

Doribelove · 2026-09-25T15:27:05Z

The follow-up in 7fb0973 addresses the new review findings. Catalog lookup now compares PEP 440 versions while retaining each release's advertised spelling, and bundled installs use the same comparison. extension info --versions now reports a catalog-fetch error instead of saying that no versions exist. The commit also adds CLI and catalog regressions for these cases and updates the reference page.

Validation: 174 extension tests passed; the full suite passed with LC_ALL=C (8,365 passed, 207 skipped). Ruff lint/format checks passed for the version-selection module and tests; the touched command modules passed lint with only three pre-existing rules excluded. git diff --check passed. The new fork-PR workflows are action_required and have not run yet; they await repository approval. The PR description has the current local results. The existing review request to @mnriem remains open.

Posted on behalf of @Doribelove by OpenAI Codex (model: GPT-6 Sol, autonomous); comment fully AI-drafted.

Doribelove force-pushed the feat/4719-extension-version-lookup branch from a557a7d to b21d936 Compare September 24, 2026 09:13

Doribelove marked this pull request as ready for review September 24, 2026 09:17

Doribelove requested a review from mnriem as a code owner September 24, 2026 09:17

mnriem added the triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review label Sep 24, 2026

mnriem mentioned this pull request Sep 24, 2026

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

Open

test(extensions): cover historical and bundled version validation

4615cac

Assisted-by: OpenAI Codex (model: GPT-6 Sol, autonomous) Signed-off-by: 李永祺 <doribelove@gmail.com>

mnriem requested a balanced review from Copilot September 25, 2026 14:14

Copilot started reviewing on behalf of mnriem September 25, 2026 14:14 View session

Copilot AI reviewed Sep 25, 2026

View reviewed changes

fix(extensions): compare equivalent catalog release versions

7fb0973

Assisted-by: OpenAI Codex (model: GPT-6 Sol, autonomous) Signed-off-by: 李永祺 <doribelove@gmail.com>

Navigation Menu

feat(extensions): select exact catalog releases - #4726

feat(extensions): select exact catalog releases#4726
Doribelove wants to merge 3 commits into
github:mainfrom
Doribelove:feat/4719-extension-version-lookup

Doribelove commented Sep 24, 2026 •

edited

Loading

Uh oh!

mnriem commented Sep 24, 2026 •

edited

Loading

Uh oh!

Doribelove commented Sep 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Doribelove commented Sep 25, 2026 •

edited

Loading

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Doribelove commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

AI Disclosure

Uh oh!

mnriem commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Doribelove commented Sep 24, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Doribelove commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Doribelove commented Sep 24, 2026 •

edited

Loading

mnriem commented Sep 24, 2026 •

edited

Loading

Doribelove commented Sep 25, 2026 •

edited

Loading