Skip to content

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

feat(extensions): support multiple active catalogs simultaneously (#1720)

Copilotee922cbde96e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 08452ee60..4539e6864 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- feat: add Tabnine CLI agent support
+- **Multi-Catalog Support (#1707)**: Extension catalog system now supports multiple active catalogs simultaneously via a catalog stack
+ - New `specify extension catalog list` command lists all active catalogs with name, URL, priority, and `install_allowed` status
+ - New `specify extension catalog add` and `specify extension catalog remove` commands for project-scoped catalog management
+ - Default built-in stack includes `catalog.json` (default, installable) and `catalog.community.json` (community, discovery only) β€” community extensions are now surfaced in search results out of the box
+ - `specify extension search` aggregates results across all active catalogs, annotating each result with source catalog
+ - `specify extension add` enforces `install_allowed` policy β€” extensions from discovery-only catalogs cannot be installed directly
+ - Project-level `.specify/extension-catalogs.yml` and user-level `~/.specify/extension-catalogs.yml` config files supported, with project-level taking precedence
+ - `SPECKIT_CATALOG_URL` environment variable still works for backward compatibility (replaces full stack with single catalog)
+ - All catalog URLs require HTTPS (HTTP allowed for localhost development)
+ - New `CatalogEntry` dataclass in `extensions.py` for catalog stack representation
+ - Per-URL hash-based caching for non-default catalogs; legacy cache preserved for default catalog
+ - Higher-priority catalogs win on merge conflicts (same extension id in multiple catalogs)
+ - 13 new tests covering catalog stack resolution, merge conflicts, URL validation, and `install_allowed` enforcement
+ - Updated RFC, Extension User Guide, and Extension API Reference documentation
## [0.1.13] - 2026-03-03
diff --git a/extensions/EXTENSION-API-REFERENCE.md b/extensions/EXTENSION-API-REFERENCE.md
index 9764ca831..bd25d4bb4 100644
--- a/extensions/EXTENSION-API-REFERENCE.md
+++ b/extensions/EXTENSION-API-REFERENCE.md
@@ -243,6 +243,34 @@ manager.check_compatibility(
) # Raises: CompatibilityError if incompatible
```
+### CatalogEntry
+
+**Module**: `specify_cli.extensions`
+
+Represents a single catalog in the active catalog stack.
+
+```python
+from specify_cli.extensions import CatalogEntry
+
+entry = CatalogEntry(
+ url="https://example.com/catalog.json",
+ name="default",
+ priority=1,
+ install_allowed=True,
+ description="Built-in catalog of installable extensions",
+)
+```
+
+**Fields**:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `url` | `str` | Catalog URL (must use HTTPS, or HTTP for localhost) |
+| `name` | `str` | Human-readable catalog name |
+| `priority` | `int` | Sort order (lower = higher priority, wins on conflicts) |
+| `install_allowed` | `bool` | Whether extensions from this catalog can be installed |
+| `description` | `str` | Optional human-readable description of the catalog (default: empty) |
+
### ExtensionCatalog
**Module**: `specify_cli.extensions`
@@ -253,30 +281,67 @@ from specify_cli.extensions import ExtensionCatalog
catalog = ExtensionCatalog(project_root)
```
+**Class attributes**:
+
+```python
+ExtensionCatalog.DEFAULT_CATALOG_URL # default catalog URL
+ExtensionCatalog.COMMUNITY_CATALOG_URL # community catalog URL
+```
+
**Methods**:
```python
-# Fetch catalog
+# Get the ordered list of active catalogs
+entries = catalog.get_active_catalogs() # List[CatalogEntry]
+
+# Fetch catalog (primary catalog, backward compat)
catalog_data = catalog.fetch_catalog(force_refresh: bool = False) # Dict
-# Search extensions
+# Search extensions across all active catalogs
+# Each result includes _catalog_name and _install_allowed
results = catalog.search(
query: Optional[str] = None,
tag: Optional[str] = None,
author: Optional[str] = None,
verified_only: bool = False
-) # Returns: List[Dict]
+) # Returns: List[Dict] β€” each dict includes _catalog_name, _install_allowed
-# Get extension info
+# Get extension info (searches all active catalogs)
+# Returns None if not found; includes _catalog_name and _install_allowed
ext_info = catalog.get_extension_info(extension_id: str) # Optional[Dict]
-# Check cache validity
+# Check cache validity (primary catalog)
is_valid = catalog.is_cache_valid() # bool
-# Clear cache
+# Clear all catalog caches
catalog.clear_cache()
```
+**Result annotation fields**:
+
+Each extension dict returned by `search()` and `get_extension_info()` includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `_catalog_name` | `str` | Name of the source catalog |
+| `_install_allowed` | `bool` | Whether installation is allowed from this catalog |
+
+**Catalog config file** (`.specify/extension-catalogs.yml`):
+
+```yaml
+catalogs:
+ - name: "default"
+ url: "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json"
+ priority: 1
+ install_allowed: true
+ description: "Built-in catalog of installable extensions"
+ - name: "community"
+ url: "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json"
+ priority: 2
+ install_allowed: false
+ description: "Community-contributed extensions (discovery only)"
+```
+
### HookExecutor
**Module**: `specify_cli.extensions`
@@ -543,6 +608,39 @@ EXECUTE_COMMAND: {command}
**Output**: List of installed extensions with metadata
+### extension catalog list
+
+**Usage**: `specify extension catalog list`
+
+Lists all active catalogs in the current catalog stack, showing name, description, URL, priority, and `install_allowed` status.
+
+### extension catalog add
+
+**Usage**: `specify extension catalog add URL [OPTIONS]`
+
+**Options**:
+
+- `--name NAME` - Catalog name (required)
+- `--priority INT` - Priority (lower = higher priority, default: 10)
+- `--install-allowed / --no-install-allowed` - Allow installs from this catalog (default: false)
+- `--description TEXT` - Optional description of the catalog
+
+**Arguments**:
+
+- `URL` - Catalog URL (must use HTTPS)
+
+Adds a catalog entry to `.specify/extension-catalogs.yml`.
+
+### extension catalog remove
+
+**Usage**: `specify extension catalog remove NAME`
+
+**Arguments**:
+
+- `NAME` - Catalog name to remove
+
+Removes a catalog entry from `.specify/extension-catalogs.yml`.
+
### extension add
**Usage**: `specify extension add EXTENSION [OPTIONS]`
@@ -551,13 +649,13 @@ EXECUTE_COMMAND: {command}
- `--from URL` - Install from custom URL
- `--dev PATH` - Install from local directory
-- `--version VERSION` - Install specific version
-- `--no-register` - Skip command registration
**Arguments**:
- `EXTENSION` - Extension name or URL
+**Note**: Extensions from catalogs with `install_allowed: false` cannot be installed via this command.
+
### extension remove
**Usage**: `specify extension remove EXTENSION [OPTIONS]`
@@ -575,6 +673,8 @@ EXECUTE_COMMAND: {command}
**Usage**: `specify extension search [QUERY] [OPTIONS]`
+Searches all active catalogs simultaneously. Results include source catalog name and install_allowed status.
+
**Options**:
- `--tag TAG` - Filter by tag
@@ -589,6 +689,8 @@ EXECUTE_COMMAND: {command}
**Usage**: `specify extension info EXTENSION`
+Shows source catalog and install_allowed status.
+
**Arguments**:
- `EXTENSION` - Extension ID
diff --git a/extensions/EXTENSION-USER-GUIDE.md b/extensions/EXTENSION-USER-GUIDE.md
index f5b5befaf..e551809ef 100644
--- a/extensions/EXTENSION-USER-GUIDE.md
+++ b/extensions/EXTENSION-USER-GUIDE.md
@@ -76,7 +76,7 @@ vim .specify/extensions/jira/jira-config.yml
## Finding Extensions
-**Note**: By default, `specify extension search` uses your organization's catalog (`catalog.json`). If the catalog is empty, you won't see any results. See [Extension Catalogs](#extension-catalogs) to learn how to populate your catalog from the community reference catalog.
+`specify extension search` searches **all active catalogs** simultaneously, including the community catalog by default. Results are annotated with their source catalog and install status.
### Browse All Extensions
@@ -84,7 +84,7 @@ vim .specify/extensions/jira/jira-config.yml
specify extension search
```
-Shows all extensions in your organization's catalog.
+Shows all extensions across all active catalogs (default and community by default).
### Search by Keyword
@@ -402,13 +402,13 @@ In addition to extension-specific environment variables (`SPECKIT_{EXT_ID}_*`),
| Variable | Description | Default |
|----------|-------------|---------|
-| `SPECKIT_CATALOG_URL` | Override the extension catalog URL | GitHub-hosted catalog |
+| `SPECKIT_CATALOG_URL` | Override the full catalog stack with a single URL (backward compat) | Built-in default stack |
| `GH_TOKEN` / `GITHUB_TOKEN` | GitHub API token for downloads | None |
#### Example: Using a custom catalog for testing
```bash
-# Point to a local or alternative catalog
+# Point to a local or alternative catalog (replaces the full stack)
export SPECKIT_CATALOG_URL="http://localhost:8000/catalog.json"
# Or use a staging catalog
@@ -419,13 +419,76 @@ export SPECKIT_CATALOG_URL="https://example.com/staging/catalog.json"
## Extension Catalogs
-For information about how Spec Kit's dual-catalog system works (`catalog.json` vs `catalog.community.json`), see the main [Extensions README](README.md#extension-catalogs).
+Spec Kit uses a **catalog stack** β€” an ordered list of catalogs searched simultaneously. By default, two catalogs are active:
+
+| Priority | Catalog | Install Allowed | Purpose |
+|----------|---------|-----------------|---------|
+| 1 | `catalog.json` (default) | βœ… Yes | Curated extensions available for installation |
+| 2 | `catalog.community.json` (community) | ❌ No (discovery only) | Browse community extensions |
+
+### Listing Active Catalogs
+
+```bash
+specify extension catalog list
+```
+
+### Adding a Catalog (Project-scoped)
+
+```bash
+# Add an internal catalog that allows installs
+specify extension catalog add \
+ --name "internal" \
+ --priority 2 \
+ --install-allowed \
+ https://internal.company.com/spec-kit/catalog.json
+
+# Add a discovery-only catalog
+specify extension catalog add \
+ --name "partner" \
+ --priority 5 \
+ https://partner.example.com/spec-kit/catalog.json
+```
+
+This creates or updates `.specify/extension-catalogs.yml`.
+
+### Removing a Catalog
+
+```bash
+specify extension catalog remove internal
+```
+
+### Manual Config File
+
+You can also edit `.specify/extension-catalogs.yml` directly:
+
+```yaml
+catalogs:
+ - name: "default"
+ url: "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json"
+ priority: 1
+ install_allowed: true
+ description: "Built-in catalog of installable extensions"
+
+ - name: "internal"
+ url: "https://internal.company.com/spec-kit/catalog.json"
+ priority: 2
+ install_allowed: true
+ description: "Internal company extensions"
+
+ - name: "community"
+ url: "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json"
+ priority: 3
+ install_allowed: false
+ description: "Community-contributed extensions (discovery only)"
+```
+
+A user-level equivalent lives at `~/.specify/extension-catalogs.yml`. Project-level config takes full precedence when it contains one or more catalog entries. An empty `catalogs: []` list falls back to built-in defaults.
## Organization Catalog Customization
### Why Customize Your Catalog
-Organizations customize their `catalog.json` to:
+Organizations customize their catalogs to:
- **Control available extensions** - Curate which extensions your team can install
- **Host private extensions** - Internal tools that shouldn't be public
@@ -503,24 +566,40 @@ Options for hosting your catalog:
#### 3. Configure Your Environment
-##### Option A: Environment variable (recommended for CI/CD)
+##### Option A: Catalog stack config file (recommended)
-```bash
-# In ~/.bashrc, ~/.zshrc, or CI pipeline
-export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json"
+Add to `.specify/extension-catalogs.yml` in your project:
+
+```yaml
+catalogs:
+ - name: "my-org"
+ url: "https://your-org.com/spec-kit/catalog.json"
+ priority: 1
+ install_allowed: true
```
-##### Option B: Per-project configuration
+Or use the CLI:
+
+```bash
+specify extension catalog add \
+ --name "my-org" \
+ --install-allowed \
+ https://your-org.com/spec-kit/catalog.json
+```
-Create `.env` or set in your shell before running spec-kit commands:
+##### Option B: Environment variable (recommended for CI/CD, single-catalog)
```bash
-SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json" specify extension search
+# In ~/.bashrc, ~/.zshrc, or CI pipeline
+export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json"
```
#### 4. Verify Configuration
```bash
+# List active catalogs
+specify extension catalog list
+
# Search should now show your catalog's extensions
specify extension search
diff --git a/extensions/RFC-EXTENSION-SYSTEM.md b/extensions/RFC-EXTENSION-SYSTEM.md
index 248e6275a..c6469c48d 100644
--- a/extensions/RFC-EXTENSION-SYSTEM.md
+++ b/extensions/RFC-EXTENSION-SYSTEM.md
@@ -868,7 +868,7 @@ Spec Kit uses two catalog files with different purposes:
- **Purpose**: Organization's curated catalog of approved extensions
- **Default State**: Empty by design - users populate with extensions they trust
-- **Usage**: Default catalog used by `specify extension` CLI commands
+- **Usage**: Primary catalog (priority 1, `install_allowed: true`) in the default stack
- **Control**: Organizations maintain their own fork/version for their teams
#### Community Reference Catalog (`catalog.community.json`)
@@ -879,16 +879,16 @@ Spec Kit uses two catalog files with different purposes:
- **Verification**: Community extensions may have `verified: false` initially
- **Status**: Active - open for community contributions
- **Submission**: Via Pull Request following the Extension Publishing Guide
-- **Usage**: Browse to discover extensions, then copy to your `catalog.json`
+- **Usage**: Secondary catalog (priority 2, `install_allowed: false`) in the default stack β€” discovery only
-**How It Works:**
+**How It Works (default stack):**
-1. **Discover**: Browse `catalog.community.json` to find available extensions
-2. **Review**: Evaluate extensions for security, quality, and organizational fit
-3. **Curate**: Copy approved extension entries from community catalog to your `catalog.json`
-4. **Install**: Use `specify extension add <name>` (pulls from your curated catalog)
+1. **Discover**: `specify extension search` searches both catalogs β€” community extensions appear automatically
+2. **Review**: Evaluate community extensions for security, quality, and organizational fit
+3. **Curate**: Copy approved entries from community catalog to your `catalog.json`, or add to `.specify/extension-catalogs.yml` with `install_allowed: true`
+4. **Install**: Use `specify extension add <name>` β€” only allowed from `install_allowed: true` catalogs
-This approach gives organizations full control over which extensions are available to their teams while maintaining a shared community resource for discovery.
+This approach gives organizations full control over which extensions can be installed while still providing community discoverability out of the box.
### Catalog Format
@@ -961,30 +961,92 @@ specify extension info jira
### Custom Catalogs
-**⚠️ FUTURE FEATURE - NOT YET IMPLEMENTED**
+Spec Kit supports a **catalog stack** β€” an ordered list of catalogs that the CLI merges and searches across. This allows organizations to maintain their own org-approved extensions alongside an internal catalog and community discovery, all at once.
-The following catalog management commands are proposed design concepts but are not yet available in the current implementation:
+#### Catalog Stack Resolution
+
+The active catalog stack is resolved in this order (first match wins):
+
+1. **`SPECKIT_CATALOG_URL` environment variable** β€” single catalog replacing all defaults (backward compat)
+2. **Project-level `.specify/extension-catalogs.yml`** β€” full control for the project
+3. **User-level `~/.specify/extension-catalogs.yml`** β€” personal defaults
+4. **Built-in default stack** β€” `catalog.json` (install_allowed: true) + `catalog.community.json` (install_allowed: false)
+
+#### Default Built-in Stack
+
+When no config file exists, the CLI uses:
+
+| Priority | Catalog | install_allowed | Purpose |
+|----------|---------|-----------------|---------|
+| 1 | `catalog.json` (default) | `true` | Curated extensions available for installation |
+| 2 | `catalog.community.json` (community) | `false` | Discovery only β€” browse but not install |
+
+This means `specify extension search` surfaces community extensions out of the box, while `specify extension add` is still restricted to entries from catalogs with `install_allowed: true`.
+
+#### `.specify/extension-catalogs.yml` Config File
+
+```yaml
+catalogs:
+ - name: "default"
+ url: "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json"
+ priority: 1 # Highest β€” only approved entries can be installed
+ install_allowed: true
+ description: "Built-in catalog of installable extensions"
+
+ - name: "internal"
+ url: "https://internal.company.com/spec-kit/catalog.json"
+ priority: 2
+ install_allowed: true
+ description: "Internal company extensions"
+
+ - name: "community"
+ url: "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json"
+ priority: 3 # Lowest β€” discovery only, not installable
+ install_allowed: false
+ description: "Community-contributed extensions (discovery only)"
+```
+
+A user-level equivalent lives at `~/.specify/extension-catalogs.yml`. When a project-level config is present with one or more catalog entries, it takes full control and the built-in defaults are not applied. An empty `catalogs: []` list is treated the same as no config file, falling back to defaults.
+
+#### Catalog CLI Commands
```bash
-# Add custom catalog (FUTURE - NOT AVAILABLE)
-specify extension add-catalog https://internal.company.com/spec-kit/catalog.json
+# List active catalogs with name, URL, priority, and install_allowed
+specify extension catalog list
+
+# Add a catalog (project-scoped)
+specify extension catalog add --name "internal" --install-allowed \
+ https://internal.company.com/spec-kit/catalog.json
+
+# Add a discovery-only catalog
+specify extension catalog add --name "community" \
+ https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json
-# Set as default (FUTURE - NOT AVAILABLE)
-specify extension set-catalog --default https://internal.company.com/spec-kit/catalog.json
+# Remove a catalog
+specify extension catalog remove internal
-# List catalogs (FUTURE - NOT AVAILABLE)
-specify extension catalogs
+# Show which catalog an extension came from
+specify extension info jira
+# β†’ Source catalog: default
```
-**Proposed catalog priority** (future design):
+#### Merge Conflict Resolution
+
+When the same extension `id` appears in multiple catalogs, the higher-priority (lower priority number) catalog wins. Extensions from lower-priority catalogs with the same `id` are ignored.
-1. Project-specific catalog (`.specify/extension-catalogs.yml`) - *not implemented*
-2. User-level catalog (`~/.specify/extension-catalogs.yml`) - *not implemented*
-3. Default GitHub catalog
+#### `install_allowed: false` Behavior
+
+Extensions from discovery-only catalogs are shown in `specify extension search` results but cannot be installed directly:
+
+```
+⚠ 'linear' is available in the 'community' catalog but installation is not allowed from that catalog.
+
+To enable installation, add 'linear' to an approved catalog (install_allowed: true) in .specify/extension-catalogs.yml.
+```
-#### Current Implementation: SPECKIT_CATALOG_URL
+#### `SPECKIT_CATALOG_URL` (Backward Compatibility)
-**The currently available method** for using custom catalogs is the `SPECKIT_CATALOG_URL` environment variable:
+The `SPECKIT_CATALOG_URL` environment variable still works β€” it is treated as a single `install_allowed: true` catalog, **replacing both defaults** for full backward compatibility:
```bash
# Point to your organization's catalog
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
index e76e240d1..209632a70 100644
--- a/src/specify_cli/__init__.py
+++ b/src/specify_cli/__init__.py
@@ -1772,6 +1772,13 @@ extension_app = typer.Typer(
)
app.add_typer(extension_app, name="extension")
+catalog_app = typer.Typer(
+ name="catalog",
+ help="Manage extension catalogs",
+ add_completion=False,
+)
+extension_app.add_typer(catalog_app, name="catalog")
+
def get_speckit_version() -> str:
"""Get current spec-kit version."""
@@ -1837,6 +1844,181 @@ def extension_list(
console.print(" [cyan]specify extension add <name>[/cyan]")
+@catalog_app.command("list")
+def catalog_list():
+ """List all active extension catalogs."""
+ from .extensions import ExtensionCatalog, ValidationError
+
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ catalog = ExtensionCatalog(project_root)
+
+ try:
+ active_catalogs = catalog.get_active_catalogs()
+ except ValidationError as e:
+ console.print(f"[red]Error:[/red] {e}")
+ raise typer.Exit(1)
+
+ console.print("\n[bold cyan]Active Extension Catalogs:[/bold cyan]\n")
+ for entry in active_catalogs:
+ install_str = (
+ "[green]install allowed[/green]"
+ if entry.install_allowed
+ else "[yellow]discovery only[/yellow]"
+ )
+ console.print(f" [bold]{entry.name}[/bold] (priority {entry.priority})")
+ if entry.description:
+ console.print(f" {entry.description}")
+ console.print(f" URL: {entry.url}")
+ console.print(f" Install: {install_str}")
+ console.print()
+
+ config_path = project_root / ".specify" / "extension-catalogs.yml"
+ user_config_path = Path.home() / ".specify" / "extension-catalogs.yml"
+ if os.environ.get("SPECKIT_CATALOG_URL"):
+ console.print("[dim]Catalog configured via SPECKIT_CATALOG_URL environment variable.[/dim]")
+ else:
+ try:
+ proj_loaded = config_path.exists() and catalog._load_catalog_config(config_path) is not None
+ except ValidationError:
+ proj_loaded = False
+ if proj_loaded:
+ console.print(f"[dim]Config: {config_path.relative_to(project_root)}[/dim]")
+ else:
+ try:
+ user_loaded = user_config_path.exists() and catalog._load_catalog_config(user_config_path) is not None
+ except ValidationError:
+ user_loaded = False
+ if user_loaded:
+ console.print("[dim]Config: ~/.specify/extension-catalogs.yml[/dim]")
+ else:
+ console.print("[dim]Using built-in default catalog stack.[/dim]")
+ console.print(
+ "[dim]Add .specify/extension-catalogs.yml to customize.[/dim]"
+ )
+
+
+@catalog_app.command("add")
+def catalog_add(
+ url: str = typer.Argument(help="Catalog URL (must use HTTPS)"),
+ name: str = typer.Option(..., "--name", help="Catalog name"),
+ priority: int = typer.Option(10, "--priority", help="Priority (lower = higher priority)"),
+ install_allowed: bool = typer.Option(
+ False, "--install-allowed/--no-install-allowed",
+ help="Allow extensions from this catalog to be installed",
+ ),
+ description: str = typer.Option("", "--description", help="Description of the catalog"),
+):
+ """Add a catalog to .specify/extension-catalogs.yml."""
+ from .extensions import ExtensionCatalog, ValidationError
+
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ # Validate URL
+ tmp_catalog = ExtensionCatalog(project_root)
+ try:
+ tmp_catalog._validate_catalog_url(url)
+ except ValidationError as e:
+ console.print(f"[red]Error:[/red] {e}")
+ raise typer.Exit(1)
+
+ config_path = specify_dir / "extension-catalogs.yml"
+
+ # Load existing config
+ if config_path.exists():
+ try:
+ config = yaml.safe_load(config_path.read_text()) or {}
+ except Exception as e:
+ console.print(f"[red]Error:[/red] Failed to read {config_path}: {e}")
+ raise typer.Exit(1)
+ else:
+ config = {}
+
+ catalogs = config.get("catalogs", [])
+ if not isinstance(catalogs, list):
+ console.print("[red]Error:[/red] Invalid catalog config: 'catalogs' must be a list.")
+ raise typer.Exit(1)
+
+ # Check for duplicate name
+ for existing in catalogs:
+ if isinstance(existing, dict) and existing.get("name") == name:
+ console.print(f"[yellow]Warning:[/yellow] A catalog named '{name}' already exists.")
+ console.print("Use 'specify extension catalog remove' first, or choose a different name.")
+ raise typer.Exit(1)
+
+ catalogs.append({
+ "name": name,
+ "url": url,
+ "priority": priority,
+ "install_allowed": install_allowed,
+ "description": description,
+ })
+
+ config["catalogs"] = catalogs
+ config_path.write_text(yaml.dump(config, default_flow_style=False, sort_keys=False))
+
+ install_label = "install allowed" if install_allowed else "discovery only"
+ console.print(f"\n[green]βœ“[/green] Added catalog '[bold]{name}[/bold]' ({install_label})")
+ console.print(f" URL: {url}")
+ console.print(f" Priority: {priority}")
+ console.print(f"\nConfig saved to {config_path.relative_to(project_root)}")
+
+
+@catalog_app.command("remove")
+def catalog_remove(
+ name: str = typer.Argument(help="Catalog name to remove"),
+):
+ """Remove a catalog from .specify/extension-catalogs.yml."""
+ project_root = Path.cwd()
+
+ specify_dir = project_root / ".specify"
+ if not specify_dir.exists():
+ console.print("[red]Error:[/red] Not a spec-kit project (no .specify/ directory)")
+ console.print("Run this command from a spec-kit project root")
+ raise typer.Exit(1)
+
+ config_path = specify_dir / "extension-catalogs.yml"
+ if not config_path.exists():
+ console.print("[red]Error:[/red] No catalog config found. Nothing to remove.")
+ raise typer.Exit(1)
+
+ try:
+ config = yaml.safe_load(config_path.read_text()) or {}
+ except Exception:
+ console.print("[red]Error:[/red] Failed to read catalog config.")
+ raise typer.Exit(1)
+
+ catalogs = config.get("catalogs", [])
+ if not isinstance(catalogs, list):
+ console.print("[red]Error:[/red] Invalid catalog config: 'catalogs' must be a list.")
+ raise typer.Exit(1)
+ original_count = len(catalogs)
+ catalogs = [c for c in catalogs if isinstance(c, dict) and c.get("name") != name]
+
+ if len(catalogs) == original_count:
+ console.print(f"[red]Error:[/red] Catalog '{name}' not found.")
+ raise typer.Exit(1)
+
+ config["catalogs"] = catalogs
+ config_path.write_text(yaml.dump(config, default_flow_style=False, sort_keys=False))
+
+ console.print(f"[green]βœ“[/green] Removed catalog '{name}'")
+ if not catalogs:
+ console.print("\n[dim]No catalogs remain in config. Built-in defaults will be used.[/dim]")
+
+
@extension_app.command("add")
def extension_add(
extension: str = typer.Argument(help="Extension name or path"),
@@ -1925,6 +2107,19 @@ def extension_add(
console.print(" specify extension search")
raise typer.Exit(1)
+ # Enforce install_allowed policy
+ if not ext_info.get("_install_allowed", True):
+ catalog_name = ext_info.get("_catalog_name", "community")
+ console.print(
+ f"[red]Error:[/red] '{extension}' is available in the "
+ f"'{catalog_name}' catalog but installation is not allowed from that catalog."
+ )
+ console.print(
+ f"\nTo enable installation, add '{extension}' to an approved catalog "
+ f"(install_allowed: true) in .specify/extension-catalogs.yml."
+ )
+ raise typer.Exit(1)
+
# Download extension ZIP
console.print(f"Downloading {ext_info['name']} v{ext_info.get('version', 'unknown')}...")
zip_path = catalog.download_extension(extension)
@@ -2069,6 +2264,15 @@ def extension_search(
tags_str = ", ".join(ext['tags'])
console.print(f" [dim]Tags:[/dim] {tags_str}")
+ # Source catalog
+ catalog_name = ext.get("_catalog_name", "")
+ install_allowed = ext.get("_install_allowed", True)
+ if catalog_name:
+ if install_allowed:
+ console.print(f" [dim]Catalog:[/dim] {catalog_name}")
+ else:
+ console.print(f" [dim]Catalog:[/dim] {catalog_name} [yellow](discovery only β€” not installable)[/yellow]")
+
# Stats
stats = []
if ext.get('downloads') is not None:
@@ -2082,8 +2286,15 @@ def extension_search(
if ext.get('repository'):
console.print(f" [dim]Repository:[/dim] {ext['repository']}")
- # Install command
- console.print(f"\n [cyan]Install:[/cyan] specify extension add {ext['id']}")
+ # Install command (show warning if not installable)
+ if install_allowed:
+ console.print(f"\n [cyan]Install:[/cyan] specify extension add {ext['id']}")
+ else:
+ console.print(f"\n [yellow]⚠[/yellow] Not directly installable from '{catalog_name}'.")
+ console.print(
+ f" Add to an approved catalog with install_allowed: true, "
+ f"or install from a ZIP URL: specify extension add {ext['id']} --from <zip-url>"
+ )
console.print()
except ExtensionError as e:
@@ -2132,6 +2343,12 @@ def extension_info(
# Author and License
console.print(f"[dim]Author:[/dim] {ext_info.get('author', 'Unknown')}")
console.print(f"[dim]License:[/dim] {ext_info.get('license', 'Unknown')}")
+
+ # Source catalog
+ if ext_info.get("_catalog_name"):
+ install_allowed = ext_info.get("_install_allowed", True)
+ install_note = "" if install_allowed else " [yellow](discovery only)[/yellow]"
+ console.print(f"[dim]Source catalog:[/dim] {ext_info['_catalog_name']}{install_note}")
console.print()
# Requirements
@@ -2188,12 +2405,21 @@ def extension_info(
# Installation status and command
is_installed = manager.registry.is_installed(ext_info['id'])
+ install_allowed = ext_info.get("_install_allowed", True)
if is_installed:
console.print("[green]βœ“ Installed[/green]")
console.print(f"\nTo remove: specify extension remove {ext_info['id']}")
- else:
+ elif install_allowed:
console.print("[yellow]Not installed[/yellow]")
console.print(f"\n[cyan]Install:[/cyan] specify extension add {ext_info['id']}")
+ else:
+ catalog_name = ext_info.get("_catalog_name", "community")
+ console.print("[yellow]Not installed[/yellow]")
+ console.print(
+ f"\n[yellow]⚠[/yellow] '{ext_info['id']}' is available in the '{catalog_name}' catalog "
+ f"but not in your approved catalog. Add it to .specify/extension-catalogs.yml "
+ f"with install_allowed: true to enable installation."
+ )
except ExtensionError as e:
console.print(f"\n[red]Error:[/red] {e}")
diff --git a/src/specify_cli/extensions.py b/src/specify_cli/extensions.py
index ad6b05140..b1045e3ce 100644
--- a/src/specify_cli/extensions.py
+++ b/src/specify_cli/extensions.py
@@ -8,9 +8,11 @@ without bloating the core framework.
import json
import hashlib
+import os
import tempfile
import zipfile
import shutil
+from dataclasses import dataclass
from pathlib import Path
from typing import Optional, Dict, List, Any
from datetime import datetime, timezone
@@ -36,6 +38,16 @@ class CompatibilityError(ExtensionError):
pass
+@dataclass
+class CatalogEntry:
+ """Represents a single catalog entry in the catalog stack."""
+ url: str
+ name: str
+ priority: int
+ install_allowed: bool
+ description: str = ""
+
+
class ExtensionManifest:
"""Represents and validates an extension manifest (extension.yml)."""
@@ -976,6 +988,7 @@ class ExtensionCatalog:
"""Manages extension catalog fetching, caching, and searching."""
DEFAULT_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json"
+ COMMUNITY_CATALOG_URL = "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json"
CACHE_DURATION = 3600 # 1 hour in seconds
def __init__(self, project_root: Path):
@@ -990,43 +1003,109 @@ class ExtensionCatalog:
self.cache_file = self.cache_dir / "catalog.json"
self.cache_metadata_file = self.cache_dir / "catalog-metadata.json"
- def get_catalog_url(self) -> str:
- """Get catalog URL from config or use default.
-
- Checks in order:
- 1. SPECKIT_CATALOG_URL environment variable
- 2. Default catalog URL
+ def _validate_catalog_url(self, url: str) -> None:
+ """Validate that a catalog URL uses HTTPS (localhost HTTP allowed).
- Returns:
- URL to fetch catalog from
+ Args:
+ url: URL to validate
Raises:
- ValidationError: If custom URL is invalid (non-HTTPS)
+ ValidationError: If URL is invalid or uses non-HTTPS scheme
"""
- import os
- import sys
from urllib.parse import urlparse
- # Environment variable override (useful for testing)
- if env_value := os.environ.get("SPECKIT_CATALOG_URL"):
- catalog_url = env_value.strip()
- parsed = urlparse(catalog_url)
+ parsed = urlparse(url)
+ is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
+ if parsed.scheme != "https" and not (parsed.scheme == "http" and is_localhost):
+ raise ValidationError(
+ f"Catalog URL must use HTTPS (got {parsed.scheme}://). "
+ "HTTP is only allowed for localhost."
+ )
+ if not parsed.netloc:
+ raise ValidationError("Catalog URL must be a valid URL with a host.")
+
+ def _load_catalog_config(self, config_path: Path) -> Optional[List[CatalogEntry]]:
+ """Load catalog stack configuration from a YAML file.
+
+ Args:
+ config_path: Path to extension-catalogs.yml
- # Require HTTPS for security (prevent man-in-the-middle attacks)
- # Allow http://localhost for local development/testing
- is_localhost = parsed.hostname in ("localhost", "127.0.0.1", "::1")
- if parsed.scheme != "https" and not (parsed.scheme == "http" and is_localhost):
+ Returns:
+ Ordered list of CatalogEntry objects, or None if file doesn't exist
+ or contains no valid catalog entries.
+
+ Raises:
+ ValidationError: If any catalog entry has an invalid URL,
+ the file cannot be parsed, or a priority value is invalid.
+ """
+ if not config_path.exists():
+ return None
+ try:
+ data = yaml.safe_load(config_path.read_text()) or {}
+ except (yaml.YAMLError, OSError) as e:
+ raise ValidationError(
+ f"Failed to read catalog config {config_path}: {e}"
+ )
+ catalogs_data = data.get("catalogs", [])
+ if not catalogs_data:
+ return None
+ if not isinstance(catalogs_data, list):
+ raise ValidationError(
+ f"Invalid catalog config: 'catalogs' must be a list, got {type(catalogs_data).__name__}"
+ )
+ entries: List[CatalogEntry] = []
+ for idx, item in enumerate(catalogs_data):
+ if not isinstance(item, dict):
raise ValidationError(
- f"Invalid SPECKIT_CATALOG_URL: must use HTTPS (got {parsed.scheme}://). "
- "HTTP is only allowed for localhost."
+ f"Invalid catalog entry at index {idx}: expected a mapping, got {type(item).__name__}"
)
-
- if not parsed.netloc:
+ url = str(item.get("url", "")).strip()
+ if not url:
+ continue
+ self._validate_catalog_url(url)
+ try:
+ priority = int(item.get("priority", idx + 1))
+ except (TypeError, ValueError):
raise ValidationError(
- "Invalid SPECKIT_CATALOG_URL: must be a valid URL with a host."
+ f"Invalid priority for catalog '{item.get('name', idx + 1)}': "
+ f"expected integer, got {item.get('priority')!r}"
)
+ raw_install = item.get("install_allowed", False)
+ if isinstance(raw_install, str):
+ install_allowed = raw_install.strip().lower() in ("true", "yes", "1")
+ else:
+ install_allowed = bool(raw_install)
+ entries.append(CatalogEntry(
+ url=url,
+ name=str(item.get("name", f"catalog-{idx + 1}")),
+ priority=priority,
+ install_allowed=install_allowed,
+ description=str(item.get("description", "")),
+ ))
+ entries.sort(key=lambda e: e.priority)
+ return entries if entries else None
+
+ def get_active_catalogs(self) -> List[CatalogEntry]:
+ """Get the ordered list of active catalogs.
+
+ Resolution order:
+ 1. SPECKIT_CATALOG_URL env var β€” single catalog replacing all defaults
+ 2. Project-level .specify/extension-catalogs.yml
+ 3. User-level ~/.specify/extension-catalogs.yml
+ 4. Built-in default stack (default + community)
- # Warn users when using a non-default catalog (once per instance)
+ Returns:
+ List of CatalogEntry objects sorted by priority (ascending)
+
+ Raises:
+ ValidationError: If a catalog URL is invalid
+ """
+ import sys
+
+ # 1. SPECKIT_CATALOG_URL env var replaces all defaults for backward compat
+ if env_value := os.environ.get("SPECKIT_CATALOG_URL"):
+ catalog_url = env_value.strip()
+ self._validate_catalog_url(catalog_url)
if catalog_url != self.DEFAULT_CATALOG_URL:
if not getattr(self, "_non_default_catalog_warning_shown", False):
print(
@@ -1035,11 +1114,163 @@ class ExtensionCatalog:
file=sys.stderr,
)
self._non_default_catalog_warning_shown = True
+ return [CatalogEntry(url=catalog_url, name="custom", priority=1, install_allowed=True, description="Custom catalog via SPECKIT_CATALOG_URL")]
+
+ # 2. Project-level config overrides all defaults
+ project_config_path = self.project_root / ".specify" / "extension-catalogs.yml"
+ catalogs = self._load_catalog_config(project_config_path)
+ if catalogs is not None:
+ return catalogs
+
+ # 3. User-level config
+ user_config_path = Path.home() / ".specify" / "extension-catalogs.yml"
+ catalogs = self._load_catalog_config(user_config_path)
+ if catalogs is not None:
+ return catalogs
+
+ # 4. Built-in default stack
+ return [
+ CatalogEntry(url=self.DEFAULT_CATALOG_URL, name="default", priority=1, install_allowed=True, description="Built-in catalog of installable extensions"),
+ CatalogEntry(url=self.COMMUNITY_CATALOG_URL, name="community", priority=2, install_allowed=False, description="Community-contributed extensions (discovery only)"),
+ ]
+
+ def get_catalog_url(self) -> str:
+ """Get the primary catalog URL.
+
+ Returns the URL of the highest-priority catalog. Kept for backward
+ compatibility. Use get_active_catalogs() for full multi-catalog support.
+
+ Returns:
+ URL of the primary catalog
+
+ Raises:
+ ValidationError: If a catalog URL is invalid
+ """
+ active = self.get_active_catalogs()
+ return active[0].url if active else self.DEFAULT_CATALOG_URL
+
+ def _fetch_single_catalog(self, entry: CatalogEntry, force_refresh: bool = False) -> Dict[str, Any]:
+ """Fetch a single catalog with per-URL caching.
+
+ For the DEFAULT_CATALOG_URL, uses legacy cache files (self.cache_file /
+ self.cache_metadata_file) for backward compatibility. For all other URLs,
+ uses URL-hash-based cache files in self.cache_dir.
+
+ Args:
+ entry: CatalogEntry describing the catalog to fetch
+ force_refresh: If True, bypass cache
+
+ Returns:
+ Catalog data dictionary
+
+ Raises:
+ ExtensionError: If catalog cannot be fetched or has invalid format
+ """
+ import urllib.request
+ import urllib.error
+
+ # Determine cache file paths (backward compat for default catalog)
+ if entry.url == self.DEFAULT_CATALOG_URL:
+ cache_file = self.cache_file
+ cache_meta_file = self.cache_metadata_file
+ is_valid = not force_refresh and self.is_cache_valid()
+ else:
+ url_hash = hashlib.sha256(entry.url.encode()).hexdigest()[:16]
+ cache_file = self.cache_dir / f"catalog-{url_hash}.json"
+ cache_meta_file = self.cache_dir / f"catalog-{url_hash}-metadata.json"
+ is_valid = False
+ if not force_refresh and cache_file.exists() and cache_meta_file.exists():
+ try:
+ metadata = json.loads(cache_meta_file.read_text())
+ cached_at = datetime.fromisoformat(metadata.get("cached_at", ""))
+ if cached_at.tzinfo is None:
+ cached_at = cached_at.replace(tzinfo=timezone.utc)
+ age = (datetime.now(timezone.utc) - cached_at).total_seconds()
+ is_valid = age < self.CACHE_DURATION
+ except (json.JSONDecodeError, ValueError, KeyError, TypeError):
+ # If metadata is invalid or missing expected fields, treat cache as invalid
+ pass
+
+ # Use cache if valid
+ if is_valid:
+ try:
+ return json.loads(cache_file.read_text())
+ except json.JSONDecodeError:
+ pass
- return catalog_url
+ # Fetch from network
+ try:
+ with urllib.request.urlopen(entry.url, timeout=10) as response:
+ catalog_data = json.loads(response.read())
- # TODO: Support custom catalogs from .specify/extension-catalogs.yml
- return self.DEFAULT_CATALOG_URL
+ if "schema_version" not in catalog_data or "extensions" not in catalog_data:
+ raise ExtensionError(f"Invalid catalog format from {entry.url}")
+
+ # Save to cache
+ self.cache_dir.mkdir(parents=True, exist_ok=True)
+ cache_file.write_text(json.dumps(catalog_data, indent=2))
+ cache_meta_file.write_text(json.dumps({
+ "cached_at": datetime.now(timezone.utc).isoformat(),
+ "catalog_url": entry.url,
+ }, indent=2))
+
+ return catalog_data
+
+ except urllib.error.URLError as e:
+ raise ExtensionError(f"Failed to fetch catalog from {entry.url}: {e}")
+ except json.JSONDecodeError as e:
+ raise ExtensionError(f"Invalid JSON in catalog from {entry.url}: {e}")
+
+ def _get_merged_extensions(self, force_refresh: bool = False) -> List[Dict[str, Any]]:
+ """Fetch and merge extensions from all active catalogs.
+
+ Higher-priority (lower priority number) catalogs win on conflicts
+ (same extension id in two catalogs). Each extension dict is annotated with:
+ - _catalog_name: name of the source catalog
+ - _install_allowed: whether installation is allowed from this catalog
+
+ Catalogs that fail to fetch are skipped. Raises ExtensionError only if
+ ALL catalogs fail.
+
+ Args:
+ force_refresh: If True, bypass all caches
+
+ Returns:
+ List of merged extension dicts
+
+ Raises:
+ ExtensionError: If all catalogs fail to fetch
+ """
+ import sys
+
+ active_catalogs = self.get_active_catalogs()
+ merged: Dict[str, Dict[str, Any]] = {}
+ any_success = False
+
+ for catalog_entry in active_catalogs:
+ try:
+ catalog_data = self._fetch_single_catalog(catalog_entry, force_refresh)
+ any_success = True
+ except ExtensionError as e:
+ print(
+ f"Warning: Could not fetch catalog '{catalog_entry.name}': {e}",
+ file=sys.stderr,
+ )
+ continue
+
+ for ext_id, ext_data in catalog_data.get("extensions", {}).items():
+ if ext_id not in merged: # Higher-priority catalog wins
+ merged[ext_id] = {
+ **ext_data,
+ "id": ext_id,
+ "_catalog_name": catalog_entry.name,
+ "_install_allowed": catalog_entry.install_allowed,
+ }
+
+ if not any_success and active_catalogs:
+ raise ExtensionError("Failed to fetch any extension catalog")
+
+ return list(merged.values())
def is_cache_valid(self) -> bool:
"""Check if cached catalog is still valid.
@@ -1053,9 +1284,11 @@ class ExtensionCatalog:
try:
metadata = json.loads(self.cache_metadata_file.read_text())
cached_at = datetime.fromisoformat(metadata.get("cached_at", ""))
+ if cached_at.tzinfo is None:
+ cached_at = cached_at.replace(tzinfo=timezone.utc)
age_seconds = (datetime.now(timezone.utc) - cached_at).total_seconds()
return age_seconds < self.CACHE_DURATION
- except (json.JSONDecodeError, ValueError, KeyError):
+ except (json.JSONDecodeError, ValueError, KeyError, TypeError):
return False
def fetch_catalog(self, force_refresh: bool = False) -> Dict[str, Any]:
@@ -1116,7 +1349,7 @@ class ExtensionCatalog:
author: Optional[str] = None,
verified_only: bool = False,
) -> List[Dict[str, Any]]:
- """Search catalog for extensions.
+ """Search catalog for extensions across all active catalogs.
Args:
query: Search query (searches name, description, tags)
@@ -1125,14 +1358,16 @@ class ExtensionCatalog:
verified_only: If True, show only verified extensions
Returns:
- List of matching extension metadata
+ List of matching extension metadata, each annotated with
+ ``_catalog_name`` and ``_install_allowed`` from its source catalog.
"""
- catalog = self.fetch_catalog()
- extensions = catalog.get("extensions", {})
+ all_extensions = self._get_merged_extensions()
results = []
- for ext_id, ext_data in extensions.items():
+ for ext_data in all_extensions:
+ ext_id = ext_data["id"]
+
# Apply filters
if verified_only and not ext_data.get("verified", False):
continue
@@ -1158,25 +1393,26 @@ class ExtensionCatalog:
if query_lower not in searchable_text:
continue
- results.append({"id": ext_id, **ext_data})
+ results.append(ext_data)
return results
def get_extension_info(self, extension_id: str) -> Optional[Dict[str, Any]]:
"""Get detailed information about a specific extension.
+ Searches all active catalogs in priority order.
+
Args:
extension_id: ID of the extension
Returns:
- Extension metadata or None if not found
+ Extension metadata (annotated with ``_catalog_name`` and
+ ``_install_allowed``) or None if not found.
"""
- catalog = self.fetch_catalog()
- extensions = catalog.get("extensions", {})
-
- if extension_id in extensions:
- return {"id": extension_id, **extensions[extension_id]}
-
+ all_extensions = self._get_merged_extensions()
+ for ext_data in all_extensions:
+ if ext_data["id"] == extension_id:
+ return ext_data
return None
def download_extension(self, extension_id: str, target_dir: Optional[Path] = None) -> Path:
@@ -1236,11 +1472,18 @@ class ExtensionCatalog:
raise ExtensionError(f"Failed to save extension ZIP: {e}")
def clear_cache(self):
- """Clear the catalog cache."""
+ """Clear the catalog cache (both legacy and URL-hash-based files)."""
if self.cache_file.exists():
self.cache_file.unlink()
if self.cache_metadata_file.exists():
self.cache_metadata_file.unlink()
+ # Also clear any per-URL hash-based cache files
+ if self.cache_dir.exists():
+ for extra_cache in self.cache_dir.glob("catalog-*.json"):
+ if extra_cache != self.cache_file:
+ extra_cache.unlink(missing_ok=True)
+ for extra_meta in self.cache_dir.glob("catalog-*-metadata.json"):
+ extra_meta.unlink(missing_ok=True)
class ConfigManager:
diff --git a/tests/test_extensions.py b/tests/test_extensions.py
index 062250b63..9ef9cb739 100644
--- a/tests/test_extensions.py
+++ b/tests/test_extensions.py
@@ -6,6 +6,7 @@ Tests cover:
- Extension registry operations
- Extension manager installation/removal
- Command registration
+- Catalog stack (multi-catalog support)
"""
import pytest
@@ -16,6 +17,7 @@ from pathlib import Path
from datetime import datetime, timezone
from specify_cli.extensions import (
+ CatalogEntry,
ExtensionManifest,
ExtensionRegistry,
ExtensionManager,
@@ -880,10 +882,29 @@ class TestExtensionCatalog:
def test_search_all_extensions(self, temp_dir):
"""Test searching all extensions without filters."""
+ import yaml as yaml_module
+
project_dir = temp_dir / "project"
project_dir.mkdir()
(project_dir / ".specify").mkdir()
+ # Use a single-catalog config so community extensions don't interfere
+ config_path = project_dir / ".specify" / "extension-catalogs.yml"
+ with open(config_path, "w") as f:
+ yaml_module.dump(
+ {
+ "catalogs": [
+ {
+ "name": "test-catalog",
+ "url": ExtensionCatalog.DEFAULT_CATALOG_URL,
+ "priority": 1,
+ "install_allowed": True,
+ }
+ ]
+ },
+ f,
+ )
+
catalog = ExtensionCatalog(project_dir)
# Create mock catalog
@@ -929,10 +950,29 @@ class TestExtensionCatalog:
def test_search_by_query(self, temp_dir):
"""Test searching by query text."""
+ import yaml as yaml_module
+
project_dir = temp_dir / "project"
project_dir.mkdir()
(project_dir / ".specify").mkdir()
+ # Use a single-catalog config so community extensions don't interfere
+ config_path = project_dir / ".specify" / "extension-catalogs.yml"
+ with open(config_path, "w") as f:
+ yaml_module.dump(
+ {
+ "catalogs": [
+ {
+ "name": "test-catalog",
+ "url": ExtensionCatalog.DEFAULT_CATALOG_URL,
+ "priority": 1,
+ "install_allowed": True,
+ }
+ ]
+ },
+ f,
+ )
+
catalog = ExtensionCatalog(project_dir)
# Create mock catalog
@@ -974,10 +1014,29 @@ class TestExtensionCatalog:
def test_search_by_tag(self, temp_dir):
"""Test searching by tag."""
+ import yaml as yaml_module
+
project_dir = temp_dir / "project"
project_dir.mkdir()
(project_dir / ".specify").mkdir()
+ # Use a single-catalog config so community extensions don't interfere
+ config_path = project_dir / ".specify" / "extension-catalogs.yml"
+ with open(config_path, "w") as f:
+ yaml_module.dump(
+ {
+ "catalogs": [
+ {
+ "name": "test-catalog",
+ "url": ExtensionCatalog.DEFAULT_CATALOG_URL,
+ "priority": 1,
+ "install_allowed": True,
+ }
+ ]
+ },
+ f,
+ )
+
catalog = ExtensionCatalog(project_dir)
# Create mock catalog
@@ -1026,10 +1085,29 @@ class TestExtensionCatalog:
def test_search_verified_only(self, temp_dir):
"""Test searching verified extensions only."""
+ import yaml as yaml_module
+
project_dir = temp_dir / "project"
project_dir.mkdir()
(project_dir / ".specify").mkdir()
+ # Use a single-catalog config so community extensions don't interfere
+ config_path = project_dir / ".specify" / "extension-catalogs.yml"
+ with open(config_path, "w") as f:
+ yaml_module.dump(
+ {
+ "catalogs": [
+ {
+ "name": "test-catalog",
+ "url": ExtensionCatalog.DEFAULT_CATALOG_URL,
+ "priority": 1,
+ "install_allowed": True,
+ }
+ ]
+ },
+ f,
+ )
+
catalog = ExtensionCatalog(project_dir)
# Create mock catalog
@@ -1071,10 +1149,29 @@ class TestExtensionCatalog:
def test_get_extension_info(self, temp_dir):
"""Test getting specific extension info."""
+ import yaml as yaml_module
+
project_dir = temp_dir / "project"
project_dir.mkdir()
(project_dir / ".specify").mkdir()
+ # Use a single-catalog config so community extensions don't interfere
+ config_path = project_dir / ".specify" / "extension-catalogs.yml"
+ with open(config_path, "w") as f:
+ yaml_module.dump(
+ {
+ "catalogs": [
+ {
+ "name": "test-catalog",
+ "url": ExtensionCatalog.DEFAULT_CATALOG_URL,
+ "priority": 1,
+ "install_allowed": True,
+ }
+ ]
+ },
+ f,
+ )
+
catalog = ExtensionCatalog(project_dir)
# Create mock catalog
@@ -1133,3 +1230,371 @@ class TestExtensionCatalog:
assert not catalog.cache_file.exists()
assert not catalog.cache_metadata_file.exists()
+
+
+# ===== CatalogEntry Tests =====
+
+class TestCatalogEntry:
+ """Test CatalogEntry dataclass."""
+
+ def test_catalog_entry_creation(self):
+ """Test creating a CatalogEntry."""
+ entry = CatalogEntry(
+ url="https://example.com/catalog.json",
+ name="test",
+ priority=1,
+ install_allowed=True,
+ )
+ assert entry.url == "https://example.com/catalog.json"
+ assert entry.name == "test"
+ assert entry.priority == 1
+ assert entry.install_allowed is True
+
+
+# ===== Catalog Stack Tests =====
+
+class TestCatalogStack:
+ """Test multi-catalog stack support."""
+
+ def _make_project(self, temp_dir: Path) -> Path:
+ """Create a minimal spec-kit project directory."""
+ project_dir = temp_dir / "project"
+ project_dir.mkdir()
+ (project_dir / ".specify").mkdir()
+ return project_dir
+
+ def _write_catalog_config(self, project_dir: Path, catalogs: list) -> None:
+ """Write extension-catalogs.yml to project .specify dir."""
+ import yaml as yaml_module
+
+ config_path = project_dir / ".specify" / "extension-catalogs.yml"
+ with open(config_path, "w") as f:
+ yaml_module.dump({"catalogs": catalogs}, f)
+
+ def _write_valid_cache(
+ self, catalog: ExtensionCatalog, extensions: dict, url: str = "http://test.com"
+ ) -> None:
+ """Populate the primary cache file with mock extension data."""
+ catalog_data = {"schema_version": "1.0", "extensions": extensions}
+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+ catalog.cache_file.write_text(json.dumps(catalog_data))
+ catalog.cache_metadata_file.write_text(
+ json.dumps(
+ {
+ "cached_at": datetime.now(timezone.utc).isoformat(),
+ "catalog_url": url,
+ }
+ )
+ )
+
+ # --- get_active_catalogs ---
+
+ def test_default_stack(self, temp_dir):
+ """Default stack includes default and community catalogs."""
+ project_dir = self._make_project(temp_dir)
+ catalog = ExtensionCatalog(project_dir)
+
+ entries = catalog.get_active_catalogs()
+
+ assert len(entries) == 2
+ assert entries[0].url == ExtensionCatalog.DEFAULT_CATALOG_URL
+ assert entries[0].name == "default"
+ assert entries[0].priority == 1
+ assert entries[0].install_allowed is True
+ assert entries[1].url == ExtensionCatalog.COMMUNITY_CATALOG_URL
+ assert entries[1].name == "community"
+ assert entries[1].priority == 2
+ assert entries[1].install_allowed is False
+
+ def test_env_var_overrides_default_stack(self, temp_dir, monkeypatch):
+ """SPECKIT_CATALOG_URL replaces the entire default stack."""
+ project_dir = self._make_project(temp_dir)
+ custom_url = "https://example.com/catalog.json"
+ monkeypatch.setenv("SPECKIT_CATALOG_URL", custom_url)
+
+ catalog = ExtensionCatalog(project_dir)
+ entries = catalog.get_active_catalogs()
+
+ assert len(entries) == 1
+ assert entries[0].url == custom_url
+ assert entries[0].install_allowed is True
+
+ def test_env_var_invalid_url_raises(self, temp_dir, monkeypatch):
+ """SPECKIT_CATALOG_URL with http:// (non-localhost) raises ValidationError."""
+ project_dir = self._make_project(temp_dir)
+ monkeypatch.setenv("SPECKIT_CATALOG_URL", "http://example.com/catalog.json")
+
+ catalog = ExtensionCatalog(project_dir)
+ with pytest.raises(ValidationError, match="HTTPS"):
+ catalog.get_active_catalogs()
+
+ def test_project_config_overrides_defaults(self, temp_dir):
+ """Project-level extension-catalogs.yml overrides default stack."""
+ project_dir = self._make_project(temp_dir)
+ self._write_catalog_config(
+ project_dir,
+ [
+ {
+ "name": "custom",
+ "url": "https://example.com/catalog.json",
+ "priority": 1,
+ "install_allowed": True,
+ }
+ ],
+ )
+
+ catalog = ExtensionCatalog(project_dir)
+ entries = catalog.get_active_catalogs()
+
+ assert len(entries) == 1
+ assert entries[0].url == "https://example.com/catalog.json"
+ assert entries[0].name == "custom"
+
+ def test_project_config_sorted_by_priority(self, temp_dir):
+ """Catalog entries are sorted by priority (ascending)."""
+ project_dir = self._make_project(temp_dir)
+ self._write_catalog_config(
+ project_dir,
+ [
+ {
+ "name": "secondary",
+ "url": "https://example.com/secondary.json",
+ "priority": 5,
+ "install_allowed": False,
+ },
+ {
+ "name": "primary",
+ "url": "https://example.com/primary.json",
+ "priority": 1,
+ "install_allowed": True,
+ },
+ ],
+ )
+
+ catalog = ExtensionCatalog(project_dir)
+ entries = catalog.get_active_catalogs()
+
+ assert len(entries) == 2
+ assert entries[0].name == "primary"
+ assert entries[1].name == "secondary"
+
+ def test_project_config_invalid_url_raises(self, temp_dir):
+ """Project config with HTTP (non-localhost) URL raises ValidationError."""
+ project_dir = self._make_project(temp_dir)
+ self._write_catalog_config(
+ project_dir,
+ [
+ {
+ "name": "bad",
+ "url": "http://example.com/catalog.json",
+ "priority": 1,
+ "install_allowed": True,
+ }
+ ],
+ )
+
+ catalog = ExtensionCatalog(project_dir)
+ with pytest.raises(ValidationError, match="HTTPS"):
+ catalog.get_active_catalogs()
+
+ def test_empty_project_config_falls_back_to_defaults(self, temp_dir):
+ """Empty catalogs list in config falls back to default stack."""
+ import yaml as yaml_module
+
+ project_dir = self._make_project(temp_dir)
+ config_path = project_dir / ".specify" / "extension-catalogs.yml"
+ with open(config_path, "w") as f:
+ yaml_module.dump({"catalogs": []}, f)
+
+ catalog = ExtensionCatalog(project_dir)
+ entries = catalog.get_active_catalogs()
+
+ # Falls back to default stack
+ assert len(entries) == 2
+ assert entries[0].url == ExtensionCatalog.DEFAULT_CATALOG_URL
+
+ # --- _load_catalog_config ---
+
+ def test_load_catalog_config_missing_file(self, temp_dir):
+ """Returns None when config file doesn't exist."""
+ project_dir = self._make_project(temp_dir)
+ catalog = ExtensionCatalog(project_dir)
+
+ result = catalog._load_catalog_config(project_dir / ".specify" / "nonexistent.yml")
+ assert result is None
+
+ def test_load_catalog_config_localhost_allowed(self, temp_dir):
+ """Localhost HTTP URLs are allowed in config."""
+ project_dir = self._make_project(temp_dir)
+ self._write_catalog_config(
+ project_dir,
+ [
+ {
+ "name": "local",
+ "url": "http://localhost:8000/catalog.json",
+ "priority": 1,
+ "install_allowed": True,
+ }
+ ],
+ )
+
+ catalog = ExtensionCatalog(project_dir)
+ entries = catalog.get_active_catalogs()
+
+ assert len(entries) == 1
+ assert entries[0].url == "http://localhost:8000/catalog.json"
+
+ # --- Merge conflict resolution ---
+
+ def test_merge_conflict_higher_priority_wins(self, temp_dir):
+ """When same extension id is in two catalogs, higher priority wins."""
+ project_dir = self._make_project(temp_dir)
+
+ # Write project config with two catalogs
+ self._write_catalog_config(
+ project_dir,
+ [
+ {
+ "name": "primary",
+ "url": ExtensionCatalog.DEFAULT_CATALOG_URL,
+ "priority": 1,
+ "install_allowed": True,
+ },
+ {
+ "name": "secondary",
+ "url": ExtensionCatalog.COMMUNITY_CATALOG_URL,
+ "priority": 2,
+ "install_allowed": False,
+ },
+ ],
+ )
+
+ catalog = ExtensionCatalog(project_dir)
+
+ # Write primary cache with jira v2.0.0
+ primary_data = {
+ "schema_version": "1.0",
+ "extensions": {
+ "jira": {
+ "name": "Jira Integration",
+ "id": "jira",
+ "version": "2.0.0",
+ "description": "Primary Jira",
+ }
+ },
+ }
+ catalog.cache_dir.mkdir(parents=True, exist_ok=True)
+ catalog.cache_file.write_text(json.dumps(primary_data))
+ catalog.cache_metadata_file.write_text(
+ json.dumps({"cached_at": datetime.now(timezone.utc).isoformat(), "catalog_url": "http://test.com"})
+ )
+
+ # Write secondary cache (URL-hash-based) with jira v1.0.0 (should lose)
+ import hashlib
+
+ url_hash = hashlib.sha256(ExtensionCatalog.COMMUNITY_CATALOG_URL.encode()).hexdigest()[:16]
+ secondary_cache = catalog.cache_dir / f"catalog-{url_hash}.json"
+ secondary_meta = catalog.cache_dir / f"catalog-{url_hash}-metadata.json"
+ secondary_data = {
+ "schema_version": "1.0",
+ "extensions": {
+ "jira": {
+ "name": "Jira Integration Community",
+ "id": "jira",
+ "version": "1.0.0",
+ "description": "Community Jira",
+ },
+ "linear": {
+ "name": "Linear",
+ "id": "linear",
+ "version": "0.9.0",
+ "description": "Linear from secondary",
+ },
+ },
+ }
+ secondary_cache.write_text(json.dumps(secondary_data))
+ secondary_meta.write_text(
+ json.dumps({"cached_at": datetime.now(timezone.utc).isoformat(), "catalog_url": ExtensionCatalog.COMMUNITY_CATALOG_URL})
+ )
+
+ results = catalog.search()
+ jira_results = [r for r in results if r["id"] == "jira"]
+ assert len(jira_results) == 1
+ # Primary catalog wins
+ assert jira_results[0]["version"] == "2.0.0"
+ assert jira_results[0]["_catalog_name"] == "primary"
+ assert jira_results[0]["_install_allowed"] is True
+
+ # linear comes from secondary
+ linear_results = [r for r in results if r["id"] == "linear"]
+ assert len(linear_results) == 1
+ assert linear_results[0]["_catalog_name"] == "secondary"
+ assert linear_results[0]["_install_allowed"] is False
+
+ def test_install_allowed_false_from_get_extension_info(self, temp_dir):
+ """get_extension_info includes _install_allowed from source catalog."""
+ project_dir = self._make_project(temp_dir)
+
+ # Single catalog that is install_allowed=False
+ self._write_catalog_config(
+ project_dir,
+ [
+ {
+ "name": "discovery",
+ "url": ExtensionCatalog.DEFAULT_CATALOG_URL,
+ "priority": 1,
+ "install_allowed": False,
+ }
+ ],
+ )
+
+ catalog = ExtensionCatalog(project_dir)
+ self._write_valid_cache(
+ catalog,
+ {
+ "jira": {
+ "name": "Jira Integration",
+ "id": "jira",
+ "version": "1.0.0",
+ "description": "Jira integration",
+ }
+ },
+ )
+
+ info = catalog.get_extension_info("jira")
+ assert info is not None
+ assert info["_install_allowed"] is False
+ assert info["_catalog_name"] == "discovery"
+
+ def test_search_results_include_catalog_metadata(self, temp_dir):
+ """Search results include _catalog_name and _install_allowed."""
+ project_dir = self._make_project(temp_dir)
+ self._write_catalog_config(
+ project_dir,
+ [
+ {
+ "name": "org",
+ "url": ExtensionCatalog.DEFAULT_CATALOG_URL,
+ "priority": 1,
+ "install_allowed": True,
+ }
+ ],
+ )
+
+ catalog = ExtensionCatalog(project_dir)
+ self._write_valid_cache(
+ catalog,
+ {
+ "jira": {
+ "name": "Jira Integration",
+ "id": "jira",
+ "version": "1.0.0",
+ "description": "Jira integration",
+ }
+ },
+ )
+
+ results = catalog.search()
+ assert len(results) == 1
+ assert results[0]["_catalog_name"] == "org"
+ assert results[0]["_install_allowed"] is True