mirror of
https://github.com/github/spec-kit.git
synced 2026-07-08 07:04:44 +08:00
feat: Integration catalog — discovery, versioning, and community distribution (#2130)
* Initial plan * feat: add integration catalog system with catalog files, IntegrationCatalog 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> * fix: address PR review feedback - 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 * refactor: address second round of PR review feedback - 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 * Potential fix for pull request finding 'Empty except' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com> * fix: address third round of PR review feedback - 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 * fix: address fourth round of PR review feedback - Remove unused _write_catalog helper from test file - Fix comment: tests use monkeypatched urlopen, not file:// URLs - Wrap cache unlink calls in OSError handler - Add explicit encoding='utf-8' to all cache read_text/write_text calls - Restore packaging.version.Version for descriptor version validation to align with extension/preset validators - Add missing goose entry to integrations/catalog.json * fix: remove unused Path import, add comment to empty except * fix: validate descriptor root is dict, add shared infra to upgrade - Add isinstance(self.data, dict) check at start of _validate() so non-mapping YAML roots raise IntegrationDescriptorError - Run _install_shared_infra() and ensure_executable_scripts() in upgrade command to match install/switch behavior * fix: address sixth round of PR review feedback - Validate integration.id/name/version/description are strings - Catch TypeError in pkg_version.Version() for non-string versions - Swap validation order: check catalogs type before emptiness - Isolate TestActiveCatalogs from user ~/.specify/ via monkeypatch * fix: address seventh round of PR review feedback - Update docs: version field uses PEP 440, not semver - Harden search() against non-string author/name/description fields - Validate requires.speckit_version is a non-empty string - Validate command name/file are non-empty strings, file is safe relative path - Handle stale symlinks in upgrade cleanup - Document catalog configuration stack in README.md * fix: validate script entries, remove destructive teardown from upgrade rollback - Validate provides.scripts entries are non-empty strings with safe relative paths - Remove teardown from upgrade rollback since setup overwrites in-place — teardown would delete files that were working before the upgrade * fix: use consistent resolved root for stale-file cleanup paths * fix: validate redirect URL and reject drive-qualified paths - Validate final URL after redirects with _validate_catalog_url() - Reject paths with Path.drive or Path.anchor for Windows safety - Update FakeResponse mocks with geturl() method * fix: fix docstring backticks, assert file modification in upgrade tests * docs: clarify directory naming convention for hyphenated integration keys * fix: correct key type hint, isolate all catalog tests from env - Fix key parameter type to str | None (defaults to None) - Add HOME/USERPROFILE monkeypatch and clear SPECKIT_INTEGRATION_CATALOG_URL in all TestCatalogFetch tests for full environment isolation * fix: neutralize catalog table title, handle non-dict cache metadata * fix: validate requires.tools entries in descriptor * fix: show discovery-only status, clear metadata files in clear_cache * fix: catch OSError/UnicodeError in cache read path * refactor: reuse IntegrationManifest.uninstall for stale-file cleanup * fix: normalize null tools to empty list in descriptor accessor --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
This commit is contained in:
Copilot
129
integrations/README.md
Normal file
129
integrations/README.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# Spec Kit Integration Catalog
|
||||
|
||||
The integration catalog enables discovery, versioning, and distribution of AI agent integrations for Spec Kit.
|
||||
|
||||
## Catalog Files
|
||||
|
||||
### Built-In Catalog (`catalog.json`)
|
||||
|
||||
Contains integrations that ship with Spec Kit. These are maintained by the core team and always installable.
|
||||
|
||||
### Community Catalog (`catalog.community.json`)
|
||||
|
||||
Community-contributed integrations. Listed for discovery only — users install from the source repositories.
|
||||
|
||||
## Catalog Configuration
|
||||
|
||||
The catalog stack is resolved in this order (first match wins):
|
||||
|
||||
1. **Environment variable** — `SPECKIT_INTEGRATION_CATALOG_URL` overrides all catalogs with a single URL
|
||||
2. **Project config** — `.specify/integration-catalogs.yml` in the project root
|
||||
3. **User config** — `~/.specify/integration-catalogs.yml` in the user home directory
|
||||
4. **Built-in defaults** — `catalog.json` + `catalog.community.json`
|
||||
|
||||
Example `integration-catalogs.yml`:
|
||||
|
||||
```yaml
|
||||
catalogs:
|
||||
- url: "https://example.com/my-catalog.json"
|
||||
name: "my-catalog"
|
||||
priority: 1
|
||||
install_allowed: true
|
||||
```
|
||||
|
||||
## CLI Commands
|
||||
|
||||
```bash
|
||||
# List built-in integrations (default)
|
||||
specify integration list
|
||||
|
||||
# Browse full catalog (built-in + community)
|
||||
specify integration list --catalog
|
||||
|
||||
# Install an integration
|
||||
specify integration install copilot
|
||||
|
||||
# Upgrade the current integration (diff-aware)
|
||||
specify integration upgrade
|
||||
|
||||
# Upgrade with force (overwrite modified files)
|
||||
specify integration upgrade --force
|
||||
```
|
||||
|
||||
## Integration Descriptor (`integration.yml`)
|
||||
|
||||
Each integration can include an `integration.yml` descriptor that documents its metadata, requirements, and provided commands/scripts:
|
||||
|
||||
```yaml
|
||||
schema_version: "1.0"
|
||||
integration:
|
||||
id: "my-agent"
|
||||
name: "My Agent"
|
||||
version: "1.0.0"
|
||||
description: "Integration for My Agent"
|
||||
author: "my-org"
|
||||
repository: "https://github.com/my-org/speckit-my-agent"
|
||||
license: "MIT"
|
||||
requires:
|
||||
speckit_version: ">=0.6.0"
|
||||
tools:
|
||||
- name: "my-agent"
|
||||
version: ">=1.0.0"
|
||||
required: true
|
||||
provides:
|
||||
commands:
|
||||
- name: "speckit.specify"
|
||||
file: "templates/speckit.specify.md"
|
||||
- name: "speckit.plan"
|
||||
file: "templates/speckit.plan.md"
|
||||
scripts:
|
||||
- update-context.sh
|
||||
- update-context.ps1
|
||||
```
|
||||
|
||||
## Catalog Schema
|
||||
|
||||
Both catalog files follow the same JSON schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"updated_at": "2026-04-08T00:00:00Z",
|
||||
"catalog_url": "https://...",
|
||||
"integrations": {
|
||||
"my-agent": {
|
||||
"id": "my-agent",
|
||||
"name": "My Agent",
|
||||
"version": "1.0.0",
|
||||
"description": "Integration for My Agent",
|
||||
"author": "my-org",
|
||||
"repository": "https://github.com/my-org/speckit-my-agent",
|
||||
"tags": ["cli"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Required Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `schema_version` | string | Must be `"1.0"` |
|
||||
| `updated_at` | string | ISO 8601 timestamp |
|
||||
| `integrations` | object | Map of integration ID → metadata |
|
||||
|
||||
### Integration Entry Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `id` | string | Yes | Unique ID (lowercase alphanumeric + hyphens) |
|
||||
| `name` | string | Yes | Human-readable display name |
|
||||
| `version` | string | Yes | PEP 440 version (e.g., `1.0.0`, `1.0.0a1`) |
|
||||
| `description` | string | Yes | One-line description |
|
||||
| `author` | string | No | Author name or organization |
|
||||
| `repository` | string | No | Source repository URL |
|
||||
| `tags` | array | No | Searchable tags (e.g., `["cli", "ide"]`) |
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add integrations to the community catalog.
|
||||
Reference in New Issue
Block a user