feat: Integration catalog — discovery, versioning, and community distribution#2130
Merged
feat: Integration catalog — discovery, versioning, and community distribution#2130
Conversation
8 tasks
…atalog class, list --catalog flag, upgrade command, integration.yml descriptor, and tests Agent-Logs-Url: https://github.com/github/spec-kit/sessions/bbcd44e8-c69c-4735-adc1-bdf1ce109184 Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
Copilot
AI
changed the title
[WIP] Add integration catalog for built-in and community integrations
feat: Integration catalog — discovery, versioning, and community distribution
Apr 8, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Introduces an integration catalog system (built-in + community) to enable discovery and upgrades of Spec Kit integrations, mirroring existing extension/preset catalog patterns.
Changes:
- Added
IntegrationCatalog+IntegrationDescriptorfor catalog fetching/search andintegration.ymlvalidation. - Extended the CLI with
specify integration list --catalogand a newspecify integration upgradecommand. - Added integration catalog JSON files, documentation, and a comprehensive new test suite for the catalog/CLI behavior.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/integrations/catalog.py |
Implements catalog resolution/fetch/cache/search and descriptor loading/validation. |
src/specify_cli/__init__.py |
Adds integration list --catalog and integration upgrade CLI commands. |
tests/integrations/test_integration_catalog.py |
Adds tests for URL validation, active catalogs, fetch/search, descriptor validation, and CLI flows. |
integrations/catalog.json |
Adds built-in integration catalog entries. |
integrations/catalog.community.json |
Adds community catalog starter file. |
integrations/README.md |
Documents catalog files, CLI usage, and schemas. |
integrations/CONTRIBUTING.md |
Adds contribution and upgrade workflow guidance. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (1)
src/specify_cli/integrations/catalog.py:315
integ_datais assumed to be a mapping and is expanded with**integ_data. If a catalog contains a non-object entry (e.g., string/null), this will raiseTypeErrorand break catalog search. Add a type check for eachinteg_data(and optionally for the overallintegrationsfield) and skip/raise a structuredIntegrationCatalogError.
for integ_id, integ_data in data.get("integrations", {}).items():
if integ_id not in merged:
merged[integ_id] = {
**integ_data,
"id": integ_id,
"_catalog_name": entry.name,
"_install_allowed": entry.install_allowed,
}
- Files reviewed: 7/7 changed files
- Comments generated: 7
- Replace empty except with cache cleanup in _fetch_single_catalog - Log teardown failure warning instead of silent pass in upgrade - Validate catalog_data and integrations are dicts before use - Catch OSError/UnicodeError in IntegrationDescriptor._load - Add isinstance checks for integration/requires/provides/commands - Enforce semver (X.Y.Z) instead of PEP 440 for descriptor versions - Fix docstring and CONTRIBUTING.md to match actual block-on-modified behavior - Restore old manifest on upgrade failure for transactional safety
Contributor
There was a problem hiding this comment.
Pull request overview
Introduces an integrations catalog system (built-in + community) that mirrors existing catalog patterns, and adds CLI support for catalog browsing and integration upgrades.
Changes:
- Added
IntegrationCatalog+IntegrationDescriptorfor catalog discovery/caching/search andintegration.ymlvalidation. - Added CLI enhancements:
specify integration list --catalogandspecify integration upgrade [--force]. - Added initial built-in/community catalog JSON files plus documentation and a comprehensive new test suite.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/integrations/catalog.py |
New catalog/discovery + descriptor validation implementation. |
src/specify_cli/__init__.py |
Adds --catalog listing mode and new integration upgrade command. |
tests/integrations/test_integration_catalog.py |
New tests covering catalog resolution/fetch/search, descriptor validation, list --catalog, and upgrade flows. |
integrations/catalog.json |
Seeds built-in integrations catalog metadata. |
integrations/catalog.community.json |
Adds empty community catalog starter. |
integrations/README.md |
Documents catalog files, schema, and CLI usage. |
integrations/CONTRIBUTING.md |
Contributor checklist and submission guidance for built-in/community entries. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (2)
src/specify_cli/integrations/catalog.py:380
- clear_cache() only deletes
catalog-*.jsonbut leaves the correspondingcatalog-*-metadata.jsonfiles behind, which can accumulate and makes cache cleanup incomplete. Consider removing both the cached payload and metadata files (and optionally the legacy cache files if you keep them).
def clear_cache(self) -> None:
"""Remove all cached catalog files."""
if self.cache_dir.exists():
for f in self.cache_dir.glob("catalog-*.json"):
f.unlink(missing_ok=True)
src/specify_cli/integrations/catalog.py:476
- IntegrationDescriptor requires
requires.speckit_versionto exist but does not validate that it’s a valid version specifier. Since the docs describe this as a PEP 440 specifier, consider validating it withpackaging.specifiers.SpecifierSet(raising IntegrationDescriptorError on InvalidSpecifier) to ensure bad descriptors fail fast.
requires = self.data["requires"]
if not isinstance(requires, dict):
raise IntegrationDescriptorError(
"'requires' must be a mapping"
)
if "speckit_version" not in requires:
raise IntegrationDescriptorError(
"Missing requires.speckit_version"
)
- Files reviewed: 7/7 changed files
- Comments generated: 6
- Remove dead cache_file/cache_metadata_file attributes from IntegrationCatalog - Deduplicate non-default catalog warning (show once per process) - Anchor version regex to reject partial matches like 1.0.0beta - Fix 'Preserved modified' message to 'Skipped' for accuracy - Make upgrade transactional: install new files first, then remove stale old-only files, so a failed setup leaves old integration intact - Update CONTRIBUTING.md: speckit_version validates presence only
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an integration catalog system (built-in + community) to enable discovery/versioning, and extends the CLI with catalog browsing and diff-aware integration upgrades.
Changes:
- Introduces
IntegrationCatalog/IntegrationDescriptorfor fetching, caching, searching catalogs and validatingintegration.yml. - Adds CLI support for
specify integration list --catalogand a newspecify integration upgradecommand. - Adds initial catalog JSON files plus integration catalog documentation and tests.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/integrations/catalog.py |
New catalog/descriptor implementation: config resolution, fetch/cache, search, and descriptor validation. |
src/specify_cli/__init__.py |
CLI wiring for integration list --catalog and new integration upgrade command. |
tests/integrations/test_integration_catalog.py |
New test coverage for catalog stack resolution, fetch/search, descriptor validation, and CLI behavior. |
integrations/catalog.json |
Adds the built-in integration catalog metadata. |
integrations/catalog.community.json |
Adds the community catalog “starter” file (empty integrations map). |
integrations/README.md |
Documents catalog purpose, CLI usage, and schema/descriptor examples. |
integrations/CONTRIBUTING.md |
Contributing guide for built-in/community integration catalog entries and upgrade workflow. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (2)
src/specify_cli/integrations/catalog.py:420
_load()can return a non-dict YAML root (e.g., a list). In that case_validate()will later raise aTypeError/KeyErrorinstead of a clearIntegrationDescriptorError. Add an explicitisinstance(data, dict)check aftersafe_loadand raise a friendly validation error when the root is not a mapping.
try:
with open(path, "r", encoding="utf-8") as fh:
return yaml.safe_load(fh) or {}
integrations/CONTRIBUTING.md:105
- Similarly, the community submission example omits the required top-level fields (
schema_version,updated_at, andintegrations). This can lead to invalid PRs againstintegrations/catalog.community.json. Update the example to show the full structure or explicitly note it’s the contents of theintegrationsobject.
1. **Fork** the [spec-kit repository](https://github.com/github/spec-kit)
2. **Add your entry** to `integrations/catalog.community.json`:
```json
{
"my-agent": {
"id": "my-agent",
"name": "My Agent",
"version": "1.0.0",
"description": "Integration for My Agent",
"author": "your-name",
"repository": "https://github.com/your-name/speckit-my-agent",
"tags": ["cli"]
}
}
</details>
- **Files reviewed:** 7/7 changed files
- **Comments generated:** 7
- Fix CONTRIBUTING.md JSON examples to show full catalog structure with schema_version and integrations wrapper - Wrap cache writes in try/except OSError for read-only project dirs - Validate _load_catalog_config YAML root is a dict - Skip non-dict integ_data entries in merged catalog - Normalize tags to list-of-strings before filtering/searching - Add path traversal containment check for stale file deletion - Clarify docstring: lower numeric priority = higher precedence
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an integration catalog system (mirroring existing extension/preset catalog patterns) to support discovery, metadata validation, and a diff-aware upgrade flow for installed integrations.
Changes:
- Introduces
IntegrationCatalog+IntegrationDescriptorfor resolving catalog stacks, fetching/caching catalogs, searching, and validatingintegration.yml. - Extends CLI with
specify integration list --catalogand a newspecify integration upgradecommand (blocks on modified files unless--force). - Adds built-in/community catalog JSON files plus documentation and a comprehensive new test suite.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/integrations/catalog.py |
New catalog resolution/fetch/search logic and integration.yml descriptor validation. |
src/specify_cli/__init__.py |
Adds integration list --catalog output and implements integration upgrade command. |
tests/integrations/test_integration_catalog.py |
New tests covering catalog resolution, fetch/search, descriptor validation, and CLI commands. |
integrations/catalog.json |
Built-in integration catalog metadata. |
integrations/catalog.community.json |
Starter community catalog file (empty). |
integrations/README.md |
User-facing docs for catalog configuration, CLI usage, and schemas. |
integrations/CONTRIBUTING.md |
Contributor guide for adding built-in/community catalog entries and descriptor requirements. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 7/7 changed files
- Comments generated: 2
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an integration catalog subsystem to the Specify CLI, aligning integrations with the existing catalog/discovery patterns used elsewhere in the codebase and introducing CLI support for catalog browsing and integration upgrades.
Changes:
- Introduces
IntegrationCatalog(URL validation, catalog stack resolution, per-URL caching, search) andIntegrationDescriptor(integration.ymlvalidation + hashing). - Extends the CLI with
specify integration list --catalogand a newspecify integration upgrade [key] [--force]. - Adds built-in/community catalog JSON files, documentation, and a comprehensive test suite for the new behavior.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/integrations/catalog.py |
Implements integration catalog discovery/caching/search and integration.yml descriptor validation. |
src/specify_cli/__init__.py |
Adds --catalog mode to integration listing and introduces integration upgrade command. |
tests/integrations/test_integration_catalog.py |
Adds unit/integration tests for catalog resolution, fetch/search, descriptor validation, list --catalog, and upgrade flows. |
integrations/catalog.json |
Adds built-in catalog metadata for shipped integrations. |
integrations/catalog.community.json |
Adds a starter (empty) community catalog file. |
integrations/README.md |
Documents catalog usage, configuration, CLI commands, and schemas. |
integrations/CONTRIBUTING.md |
Documents contribution workflow for built-in/community integration catalog entries and integration.yml expectations. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 7/7 changed files
- Comments generated: 1
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an integration catalog system (mirroring the existing extension/preset catalog patterns) to enable integration discovery, basic descriptor validation, and a diff-aware upgrade flow via the CLI.
Changes:
- Introduces
IntegrationCatalog(+ config resolution, URL validation, fetch/cache, merged search) andIntegrationDescriptorvalidation forintegration.yml. - Extends the CLI with
specify integration list --catalogand a newspecify integration upgrade [key] [--force]command. - Adds built-in/community catalog JSON files plus documentation and a comprehensive new test suite.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/integrations/catalog.py |
Implements integration catalog stack resolution, fetch+cache, search, and integration.yml descriptor validation. |
src/specify_cli/__init__.py |
Adds --catalog listing mode and a new diff-aware integration upgrade command. |
tests/integrations/test_integration_catalog.py |
New tests covering catalog resolution/validation, fetch/search, descriptor validation, list --catalog, and upgrade behavior. |
integrations/catalog.json |
Adds the built-in integration catalog entries shipped with Spec Kit. |
integrations/catalog.community.json |
Adds the community catalog starter (discovery-only). |
integrations/README.md |
Documents catalog config, CLI usage, and schema. |
integrations/CONTRIBUTING.md |
Documents contribution workflow for built-in/community catalogs and upgrade behavior expectations. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 7/7 changed files
- Comments generated: 2
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an integration catalog system (mirroring existing extension/preset catalog patterns) to enable discovery and version tracking of integrations, plus CLI support for browsing the catalog and upgrading installed integrations safely.
Changes:
- Introduces
IntegrationCatalog/IntegrationDescriptorwith URL validation, catalog resolution, caching, search, and descriptor validation. - Adds CLI support for
specify integration list --catalogand a diff-awarespecify integration upgrade [--force]. - Adds built-in/community catalog JSON files, documentation, and a comprehensive test suite for the new behavior.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/integrations/catalog.py |
Implements integration catalog resolution/fetch/cache/search and integration.yml descriptor validation. |
src/specify_cli/__init__.py |
Adds integration list --catalog output and new integration upgrade command workflow. |
tests/integrations/test_integration_catalog.py |
Adds coverage for catalog URL validation, active catalog resolution, fetch/search behavior, descriptor validation, list --catalog, and upgrade flows. |
integrations/catalog.json |
Adds the built-in integrations catalog metadata. |
integrations/catalog.community.json |
Adds starter empty community catalog. |
integrations/README.md |
Documents catalog behavior, CLI usage, and schema expectations. |
integrations/CONTRIBUTING.md |
Adds contributor guidance for built-in/community catalog entries and descriptor requirements. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 7/7 changed files
- Comments generated: 1
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an integration catalog system (mirroring existing extension/preset catalogs) plus CLI support to browse catalogs and upgrade integrations with manifest-based modified-file protection.
Changes:
- Introduces
IntegrationCatalog/IntegrationDescriptorwith URL validation, catalog source resolution, per-URL caching, and search. - Adds
specify integration list --catalogandspecify integration upgrade [key] [--force]. - Adds built-in/community catalog JSON files, documentation, and a comprehensive new test suite.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/integrations/catalog.py |
Implements integration catalog resolution/fetch/search and integration.yml descriptor validation. |
src/specify_cli/__init__.py |
Extends integration CLI with list --catalog and adds integration upgrade workflow. |
tests/integrations/test_integration_catalog.py |
Adds tests covering catalog resolution, fetch/search, descriptor validation, and new CLI behaviors. |
integrations/catalog.json |
Adds built-in integration catalog entries. |
integrations/catalog.community.json |
Adds starter community catalog file. |
integrations/README.md |
Documents catalog configuration, CLI usage, and schema/descriptor references. |
integrations/CONTRIBUTING.md |
Provides contribution guidance for built-in/community catalog entries and upgrade workflow notes. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 7/7 changed files
- Comments generated: 1
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an integration catalog system to the Spec Kit CLI, enabling discovery of built-in/community integrations and supporting diff-aware upgrades via manifest comparison.
Changes:
- Introduces
IntegrationCatalog+IntegrationDescriptorfor catalog resolution/fetch/cache/search andintegration.ymlvalidation. - Extends the CLI with
specify integration list --catalogand a newspecify integration upgradecommand. - Adds built-in/community catalog JSON files, documentation, and a comprehensive new test suite for the catalog + CLI flows.
Show a summary per file
| File | Description |
|---|---|
tests/integrations/test_integration_catalog.py |
New test suite covering catalog URL validation, stack resolution, fetch/search behavior, descriptor validation, and CLI list/upgrade paths. |
src/specify_cli/integrations/catalog.py |
Implements catalog config resolution, URL validation, fetch/caching, search/info, and integration.yml descriptor validation + hashing. |
src/specify_cli/__init__.py |
Adds --catalog flag to integration list and implements the new integration upgrade command with modified-file blocking and stale-file cleanup. |
integrations/catalog.json |
Adds the built-in integrations catalog metadata. |
integrations/catalog.community.json |
Adds a starter community catalog file (empty integrations map). |
integrations/README.md |
Documents catalog files, configuration precedence, CLI usage, and descriptor/schema reference. |
integrations/CONTRIBUTING.md |
Provides contribution guidance for built-in/community catalogs and describes descriptor/upgrade workflow. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 7/7 changed files
- Comments generated: 1
Contributor
There was a problem hiding this comment.
Pull request overview
Introduces an integration catalog system (built-in + community) and new CLI capabilities to browse catalog entries and perform diff-aware integration upgrades, aligning integrations with the existing catalog patterns used elsewhere in the CLI.
Changes:
- Added
IntegrationCatalog/IntegrationDescriptorfor catalog resolution, caching, search, andintegration.ymlvalidation. - Added CLI support for
specify integration list --catalogandspecify integration upgrade [--force]. - Added integration catalog JSON files plus documentation and test coverage for catalog + upgrade flows.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/integrations/catalog.py |
Implements catalog stack resolution, URL validation, caching, merged search, and descriptor validation. |
src/specify_cli/__init__.py |
Adds integration list --catalog and new integration upgrade command flow. |
tests/integrations/test_integration_catalog.py |
Adds tests for catalog URL/config resolution, fetch/search, descriptor validation, list --catalog, and upgrade behavior. |
integrations/catalog.json |
Adds built-in integration catalog entries. |
integrations/catalog.community.json |
Adds starter community catalog file (empty). |
integrations/README.md |
Documents catalog configuration, CLI usage, and schema. |
integrations/CONTRIBUTING.md |
Documents how to add built-in/community integrations and descriptor rules. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 7/7 changed files
- Comments generated: 0 new
mnriem
approved these changes
Apr 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a catalog system for integrations mirroring the established extension and preset catalog patterns, enabling discovery and community-contributed integrations.
Catalog files
integrations/catalog.json— 27 built-in integrations metadataintegrations/catalog.community.json— empty community catalog starterIntegrationCatalogclass (src/specify_cli/integrations/catalog.py)IntegrationDescriptorforintegration.ymlvalidation — schema version, ID format, semver, required fields, SHA-256 hashingCLI commands
specify integration list --catalog— browse merged catalog (built-in + community) with source and install statusspecify integration upgrade [key] [--force]— diff-aware reinstall via manifest hash comparison; blocks on modified files unless--forceDocumentation
integrations/README.md— schema reference, CLI usageintegrations/CONTRIBUTING.md— checklist for adding built-in and community integrationsTests
40 tests covering catalog entries, URL validation, active catalogs, fetch/search, descriptor validation,
list --catalog, and upgrade (including modified-file blocking and--forceoverride).