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

Author: mnriem

integrations/CONTRIBUTING.md

@@ -17,18 +17,21 @@ Built-in integrations are maintained by the Spec Kit core team and ship with the
 
 ### Catalog Entry Format
 
-Add your integration to `integrations/catalog.json`:
+Add your integration under the top-level `integrations` key in `integrations/catalog.json`:
 
 ```json
 {
-  "my-agent": {
-    "id": "my-agent",
-    "name": "My Agent",
-    "version": "1.0.0",
-    "description": "Integration for My Agent",
-    "author": "spec-kit-core",
-    "repository": "https://github.com/github/spec-kit",
-    "tags": ["cli"]
+  "schema_version": "1.0",
+  "integrations": {
+    "my-agent": {
+      "id": "my-agent",
+      "name": "My Agent",
+      "version": "1.0.0",
+      "description": "Integration for My Agent",
+      "author": "spec-kit-core",
+      "repository": "https://github.com/github/spec-kit",
+      "tags": ["cli"]
+    }
   }
 }
 ```
@@ -88,18 +91,21 @@ provides:
 ### Submitting to the Community Catalog
 
 1. **Fork** the [spec-kit repository](https://github.com/github/spec-kit)
-2. **Add your entry** to `integrations/catalog.community.json`:
+2. **Add your entry** under the `integrations` key in `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"]
+  "schema_version": "1.0",
+  "integrations": {
+    "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"]
+    }
   }
 }
 ```

src/specify_cli/__init__.py

@@ -2316,12 +2316,19 @@ def integration_upgrade(
         raise typer.Exit(1)
 
     # Phase 2: Remove stale files from old manifest that are not in the new one
+    resolved_project_root = project_root.resolve()
     old_files = set(old_manifest.files.keys())
     new_files = set(new_manifest.files.keys())
     stale_files = old_files - new_files
     stale_removed = 0
     for rel in stale_files:
         path = project_root / rel
+        # Validate containment to prevent path traversal from tampered manifests
+        try:
+            normed = Path(os.path.normpath(path))
+            normed.relative_to(resolved_project_root)
+        except (ValueError, OSError):
+            continue
         if path.exists() and path.is_file():
             try:
                 path.unlink()

src/specify_cli/integrations/catalog.py

@@ -105,6 +105,10 @@ def _load_catalog_config(
             raise IntegrationCatalogError(
                 f"Failed to read catalog config {config_path}: {exc}"
             )
+        if not isinstance(data, dict):
+            raise IntegrationCatalogError(
+                f"Invalid catalog config {config_path}: expected a YAML mapping at the root"
+            )
         catalogs_data = data.get("catalogs", [])
         if not catalogs_data:
             raise IntegrationCatalogError(
@@ -267,17 +271,20 @@ def _fetch_single_catalog(
                     f"Invalid catalog format from {entry.url}: 'integrations' must be a JSON object"
                 )
 
-            self.cache_dir.mkdir(parents=True, exist_ok=True)
-            cache_file.write_text(json.dumps(catalog_data, indent=2))
-            cache_meta.write_text(
-                json.dumps(
-                    {
-                        "cached_at": datetime.now(timezone.utc).isoformat(),
-                        "catalog_url": entry.url,
-                    },
-                    indent=2,
+            try:
+                self.cache_dir.mkdir(parents=True, exist_ok=True)
+                cache_file.write_text(json.dumps(catalog_data, indent=2))
+                cache_meta.write_text(
+                    json.dumps(
+                        {
+                            "cached_at": datetime.now(timezone.utc).isoformat(),
+                            "catalog_url": entry.url,
+                        },
+                        indent=2,
+                    )
                 )
-            )
+            except OSError:
+                pass  # Cache is best-effort; proceed with fetched data
             return catalog_data
 
         except urllib.error.URLError as exc:
@@ -294,8 +301,10 @@ def _get_merged_integrations(
     ) -> List[Dict[str, Any]]:
         """Fetch and merge integrations from all active catalogs.
 
-        Higher-priority catalogs win on conflicts.  Each dict is annotated
-        with ``_catalog_name`` and ``_install_allowed``.
+        Catalogs are processed in the order returned by
+        :meth:`get_active_catalogs`.  On conflicts, the first catalog in that
+        order wins (lower numeric priority = higher precedence).  Each dict is
+        annotated with ``_catalog_name`` and ``_install_allowed``.
         """
         import sys
 
@@ -315,6 +324,8 @@ def _get_merged_integrations(
                 continue
 
             for integ_id, integ_data in data.get("integrations", {}).items():
+                if not isinstance(integ_data, dict):
+                    continue
                 if integ_id not in merged:
                     merged[integ_id] = {
                         **integ_data,
@@ -343,18 +354,21 @@ def search(
         for item in self._get_merged_integrations():
             if author and item.get("author", "").lower() != author.lower():
                 continue
-            if tag and tag.lower() not in [
-                t.lower() for t in item.get("tags", [])
-            ]:
-                continue
+            if tag:
+                raw_tags = item.get("tags", [])
+                tags_list = raw_tags if isinstance(raw_tags, list) else []
+                if tag.lower() not in [t.lower() for t in tags_list if isinstance(t, str)]:
+                    continue
             if query:
+                raw_tags = item.get("tags", [])
+                tags_list = raw_tags if isinstance(raw_tags, list) else []
                 haystack = " ".join(
                     [
                         item.get("name", ""),
                         item.get("description", ""),
                         item.get("id", ""),
                     ]
-                    + item.get("tags", [])
+                    + [t for t in tags_list if isinstance(t, str)]
                 ).lower()
                 if query.lower() not in haystack:
                     continue