fix: address PR review feedback for multi-catalog support

- Rename 'org-approved' catalog to 'default' - Move 'catalogs' command to 'catalog list' for consistency - Add 'description' field to CatalogEntry dataclass - Add --description option to 'catalog add' CLI command - Align install_allowed default to False in _load_catalog_config - Add user-level config detection in catalog list footer - Fix _load_catalog_config docstring (document ValidationError) - Fix test isolation for test_search_by_tag, test_search_by_query, test_search_verified_only, test_get_extension_info - Update version to 0.1.14 and CHANGELOG - Update all docs (RFC, User Guide, API Reference)
2026-03-17 02:43:08 +00:00 · 2026-03-09 13:04:55 -05:00
parent 9a82f098e8
commit 990a1513c2
7 changed files with 204 additions and 59 deletions
--- a/extensions/EXTENSION-API-REFERENCE.md
+++ b/extensions/EXTENSION-API-REFERENCE.md
@@ -254,9 +254,10 @@ from specify_cli.extensions import CatalogEntry

 entry = CatalogEntry(
    url="https://example.com/catalog.json",
-    name="org-approved",
+    name="default",
    priority=1,
    install_allowed=True,
+    description="Built-in catalog of installable extensions",
 )
 ```

@@ -268,6 +269,7 @@ entry = CatalogEntry(
 | `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

@@ -282,7 +284,7 @@ catalog = ExtensionCatalog(project_root)
 **Class attributes**:

 ```python
-ExtensionCatalog.DEFAULT_CATALOG_URL    # org-approved catalog URL
+ExtensionCatalog.DEFAULT_CATALOG_URL    # default catalog URL
 ExtensionCatalog.COMMUNITY_CATALOG_URL  # community catalog URL
 ```

@@ -328,14 +330,16 @@ Each extension dict returned by `search()` and `get_extension_info()` includes:

 ```yaml
 catalogs:
-  - name: "org-approved"
-    url: "https://example.com/catalog.json"
+  - 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
@@ -604,11 +608,11 @@ EXECUTE_COMMAND: {command}

 **Output**: List of installed extensions with metadata

-### extension catalogs
+### extension catalog list

-**Usage**: `specify extension catalogs`
+**Usage**: `specify extension catalog list`

-Lists all active catalogs in the current catalog stack, showing name, URL, priority, and `install_allowed` status.
+Lists all active catalogs in the current catalog stack, showing name, description, URL, priority, and `install_allowed` status.

 ### extension catalog add

@@ -619,6 +623,7 @@ Lists all active catalogs in the current catalog stack, showing name, URL, prior
 - `--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**:

--- a/extensions/EXTENSION-USER-GUIDE.md
+++ b/extensions/EXTENSION-USER-GUIDE.md
@@ -84,7 +84,7 @@ vim .specify/extensions/jira/jira-config.yml
 specify extension search
 ```

-Shows all extensions across all active catalogs (org-approved and community by default).
+Shows all extensions across all active catalogs (default and community by default).

 ### Search by Keyword

@@ -423,13 +423,13 @@ Spec Kit uses a **catalog stack** — an ordered list of catalogs searched simul

 | Priority | Catalog | Install Allowed | Purpose |
 |----------|---------|-----------------|---------|
-| 1 | `catalog.json` (org-approved) | ✅ Yes | Extensions your org approves for installation |
+| 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 catalogs
+specify extension catalog list
 ```

 ### Adding a Catalog (Project-scoped)
@@ -463,23 +463,26 @@ You can also edit `.specify/extension-catalogs.yml` directly:

 ```yaml
 catalogs:
-  - name: "org-approved"
+  - 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 present.
+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

@@ -569,7 +572,7 @@ Add to `.specify/extension-catalogs.yml` in your project:

 ```yaml
 catalogs:
-  - name: "org-approved"
+  - name: "my-org"
    url: "https://your-org.com/spec-kit/catalog.json"
    priority: 1
    install_allowed: true
@@ -579,7 +582,7 @@ Or use the CLI:

 ```bash
 specify extension catalog add \
-  --name "org-approved" \
+  --name "my-org" \
  --install-allowed \
  https://your-org.com/spec-kit/catalog.json
 ```
@@ -595,7 +598,7 @@ export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json"

 ```bash
 # List active catalogs
-specify extension catalogs
+specify extension catalog list

 # Search should now show your catalog's extensions
 specify extension search
--- a/extensions/RFC-EXTENSION-SYSTEM.md
+++ b/extensions/RFC-EXTENSION-SYSTEM.md
@@ -961,7 +961,7 @@ specify extension info jira

 ### Custom Catalogs

-Spec Kit supports a **catalog stack** — an ordered list of catalogs that the CLI merges and searches across. This allows organizations to benefit from org-approved extensions, an internal catalog, and community discovery all at once.
+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.

 #### Catalog Stack Resolution

@@ -978,38 +978,41 @@ When no config file exists, the CLI uses:

 | Priority | Catalog | install_allowed | Purpose |
 |----------|---------|-----------------|---------|
-| 1 | `catalog.json` (org-approved) | `true` | Extensions your org approves for installation |
+| 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 org-approved entries.
+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: "org-approved"
+  - 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, it takes full control and the built-in defaults are not applied.
+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
 # List active catalogs with name, URL, priority, and install_allowed
-specify extension catalogs
+specify extension catalog list

 # Add a catalog (project-scoped)
 specify extension catalog add --name "internal" --install-allowed \
@@ -1024,7 +1027,7 @@ specify extension catalog remove internal

 # Show which catalog an extension came from
 specify extension info jira
-# → Source catalog: org-approved
+# → Source catalog: default
 ```

 #### Merge Conflict Resolution