fix(platform-integrations): preserve merged evolve config entries

Author: visahak

platform-integrations/INSTALL_SPEC.md

@@ -174,10 +174,10 @@ All JSON writes use atomic read-modify-write:
 3. Write to `<path>.evolve.tmp`
 4. `os.replace(tmp, path)` — atomic on POSIX
 
-**Key upsert** (`mcpServers.evolve`, `hooks.UserPromptSubmit` scaffolding): navigate nested keys via `dict.setdefault`, set leaf value.
+**Key upsert** (`mcpServers.evolve`, `hooks.UserPromptSubmit` scaffolding): navigate nested keys via `dict.setdefault`, merge matching dict values in place, and only replace scalar/list leaves.
 
 **Array upsert** (`.roomodes` `customModes`, `marketplace.json` `plugins`): iterate array, find item where the identity key matches,
-replace in-place; append if not found.
+merge matching dict items in place; append if not found.
 
 **Array remove**: filter array by `item["slug"] != target_slug`, write back.
 
@@ -214,7 +214,7 @@ All operations are safe to run multiple times:
 - JSON writes upsert (replace-if-exists, insert-if-not)
 - YAML writes check for sentinel before appending
 - Claude plugin install is idempotent by the Claude CLI itself
-- Codex marketplace and hook writes replace matching Evolve entries and preserve user-owned entries
+- Codex marketplace and hook writes merge matching Evolve entries and preserve user-owned entries
 
 ---
 

platform-integrations/install.sh

@@ -125,6 +125,7 @@ resolve_source
 
 exec python3 - "$SOURCE_DIR" "$@" <<'PYEOF'
 import argparse
+import copy
 import json
 import os
 import re
@@ -259,13 +260,25 @@ def remove_file(path):
 
 # ── JSON config helpers ────────────────────────────────────────────────────────
 
+def merge_json_value(existing, desired):
+    """Recursively merge JSON-like values, preserving unknown keys from existing objects."""
+    if isinstance(existing, dict) and isinstance(desired, dict):
+        merged = copy.deepcopy(existing)
+        for key, desired_value in desired.items():
+            merged[key] = merge_json_value(merged.get(key), desired_value)
+        return merged
+    return copy.deepcopy(desired)
+
+
 def upsert_json_key(path, key_path: list, value):
     """Upsert a nested key into a JSON file. key_path = ['a', 'b', 'c'] → data['a']['b']['c'] = value."""
     data = read_json(path)
     cursor = data
     for key in key_path[:-1]:
-        cursor = cursor.setdefault(key, {})
-    cursor[key_path[-1]] = value
+        if not isinstance(cursor.get(key), dict):
+            cursor[key] = {}
+        cursor = cursor[key]
+    cursor[key_path[-1]] = merge_json_value(cursor.get(key_path[-1]), value)
     atomic_write_json(path, data)
 
 
@@ -289,10 +302,10 @@ def upsert_json_array_item(path, array_key: str, item: dict, id_key: str):
     arr = data.setdefault(array_key, [])
     for i, existing in enumerate(arr):
         if existing.get(id_key) == item.get(id_key):
-            arr[i] = item
+            arr[i] = merge_json_value(existing, item)
             break
     else:
-        arr.append(item)
+        arr.append(copy.deepcopy(item))
     atomic_write_json(path, data)
 
 
@@ -337,10 +350,10 @@ def upsert_codex_marketplace_entry(path, item):
 
     for index, existing in enumerate(plugins):
         if isinstance(existing, dict) and existing.get("name") == item.get("name"):
-            plugins[index] = item
+            plugins[index] = merge_json_value(existing, item)
             break
     else:
-        plugins.append(item)
+        plugins.append(copy.deepcopy(item))
 
     atomic_write_json(path, data)
 
@@ -363,22 +376,82 @@ def _is_codex_recall_command(command):
     return isinstance(command, str) and "plugins/evolve-lite/skills/recall/scripts/retrieve_entities.py" in command
 
 
+def _codex_recall_hook():
+    return {
+        "type": "command",
+        "command": _codex_recall_hook_command(),
+        "statusMessage": "Loading Evolve guidance",
+    }
+
+
 def _codex_recall_hook_group():
     return {
         "matcher": "",
-        "hooks": [
-            {
-                "type": "command",
-                "command": _codex_recall_hook_command(),
-                "statusMessage": "Loading Evolve guidance",
-            }
-        ]
+        "hooks": [_codex_recall_hook()],
     }
 
 
-def _group_contains_codex_recall_command(group):
+def _iter_group_hooks(group):
     hooks = group.get("hooks", [])
-    return any(isinstance(hook, dict) and _is_codex_recall_command(hook.get("command")) for hook in hooks)
+    if isinstance(hooks, list):
+        return hooks
+    if isinstance(hooks, dict):
+        return hooks.values()
+    return []
+
+
+def _group_contains_codex_recall_command(group):
+    return any(isinstance(hook, dict) and _is_codex_recall_command(hook.get("command")) for hook in _iter_group_hooks(group))
+
+
+def _upsert_codex_recall_hook_into_group(group):
+    updated_group = copy.deepcopy(group)
+    recall_hook = _codex_recall_hook()
+    hooks = updated_group.get("hooks")
+
+    if isinstance(hooks, list):
+        for index, existing_hook in enumerate(hooks):
+            if isinstance(existing_hook, dict) and _is_codex_recall_command(existing_hook.get("command")):
+                hooks[index] = merge_json_value(existing_hook, recall_hook)
+                break
+        else:
+            hooks.append(copy.deepcopy(recall_hook))
+        return updated_group
+
+    if isinstance(hooks, dict):
+        for key, existing_hook in hooks.items():
+            if isinstance(existing_hook, dict) and _is_codex_recall_command(existing_hook.get("command")):
+                hooks[key] = merge_json_value(existing_hook, recall_hook)
+                break
+        else:
+            hooks["evolve-lite"] = copy.deepcopy(recall_hook)
+        return updated_group
+
+    updated_group["hooks"] = [copy.deepcopy(recall_hook)]
+    return updated_group
+
+
+def _remove_codex_recall_hook_from_group(group):
+    updated_group = copy.deepcopy(group)
+    hooks = updated_group.get("hooks")
+
+    if isinstance(hooks, list):
+        updated_group["hooks"] = [
+            hook
+            for hook in hooks
+            if not (isinstance(hook, dict) and _is_codex_recall_command(hook.get("command")))
+        ]
+        return updated_group
+
+    if isinstance(hooks, dict):
+        updated_group["hooks"] = {
+            key: hook
+            for key, hook in hooks.items()
+            if not (isinstance(hook, dict) and _is_codex_recall_command(hook.get("command")))
+        }
+        return updated_group
+
+    return updated_group
 
 
 def upsert_codex_user_prompt_hook(path, group):
@@ -401,10 +474,10 @@ def upsert_codex_user_prompt_hook(path, group):
 
     for index, existing in enumerate(groups):
         if isinstance(existing, dict) and _group_contains_codex_recall_command(existing):
-            groups[index] = group
+            groups[index] = _upsert_codex_recall_hook_into_group(existing)
             break
     else:
-        groups.append(group)
+        groups.append(copy.deepcopy(group))
 
     atomic_write_json(path, data)
 
@@ -424,7 +497,10 @@ def remove_codex_user_prompt_hook(path):
         return
 
     hooks["UserPromptSubmit"] = [
-        group for group in groups if not (isinstance(group, dict) and _group_contains_codex_recall_command(group))
+        _remove_codex_recall_hook_from_group(group)
+        if isinstance(group, dict) and _group_contains_codex_recall_command(group)
+        else group
+        for group in groups
     ]
     if not hooks["UserPromptSubmit"]:
         hooks.pop("UserPromptSubmit", None)

tests/platform_integrations/conftest.py

@@ -314,6 +314,28 @@ def create_existing_mcp_config(project_dir: Path):
         mcp_file.write_text(json.dumps(data, indent=2) + "\n")
         return mcp_file
 
+    @staticmethod
+    def create_existing_mcp_config_with_evolve(project_dir: Path):
+        """Create an mcp.json with a user-customized evolve server entry."""
+        mcp_file = project_dir / ".bob" / "mcp.json"
+        mcp_file.parent.mkdir(parents=True, exist_ok=True)
+
+        data = {
+            "mcpServers": {
+                "my-server": {"command": "node", "args": ["server.js"], "disabled": False},
+                "evolve": {
+                    "command": "python3",
+                    "args": ["old_evolve.py"],
+                    "disabled": True,
+                    "env": {"EVOLVE_PROFILE": "local"},
+                    "metadata": {"managedBy": "user"},
+                },
+            }
+        }
+
+        mcp_file.write_text(json.dumps(data, indent=2) + "\n")
+        return mcp_file
+
 
 class RooFixtures:
     """Helper class to create Roo platform test fixtures."""
@@ -352,6 +374,35 @@ def create_existing_roomodes_json(project_dir: Path):
         roomodes_file.write_text(json.dumps(data, indent=2) + "\n")
         return roomodes_file
 
+    @staticmethod
+    def create_existing_roomodes_json_with_evolve(project_dir: Path):
+        """Create a JSON .roomodes file that already contains a customized evolve-lite mode."""
+        roomodes_file = project_dir / ".roomodes"
+
+        data = {
+            "customModes": [
+                {
+                    "slug": "my-roo-mode",
+                    "name": "My Roo Mode",
+                    "roleDefinition": "This is my custom Roo mode.",
+                    "customInstructions": "Follow my Roo instructions.",
+                    "groups": ["read", "edit"],
+                },
+                {
+                    "slug": "evolve-lite",
+                    "name": "My Evolve Lite",
+                    "roleDefinition": "Old evolve role definition.",
+                    "customInstructions": "Old evolve instructions.",
+                    "groups": ["read"],
+                    "metadata": {"accent": "teal"},
+                    "shortcuts": ["recall-first"],
+                },
+            ]
+        }
+
+        roomodes_file.write_text(json.dumps(data, indent=2) + "\n")
+        return roomodes_file
+
     @staticmethod
     def create_existing_roomodes_yaml(project_dir: Path):
         """Create a .roomodes file in YAML format with a custom mode."""
@@ -467,6 +518,96 @@ def create_existing_hooks(project_dir: Path):
         )
         return hooks_file
 
+    @staticmethod
+    def create_existing_hooks_with_shared_evolve_group(project_dir: Path):
+        """Create a list-based UserPromptSubmit group containing both user hooks and the evolve hook."""
+        hooks_file = project_dir / ".codex" / "hooks.json"
+        hooks_file.parent.mkdir(parents=True, exist_ok=True)
+        hooks_file.write_text(
+            json.dumps(
+                {
+                    "hooks": {
+                        "UserPromptSubmit": [
+                            {
+                                "matcher": "src/.*",
+                                "hooks": [
+                                    {
+                                        "type": "command",
+                                        "command": "python3 ~/.codex/hooks/custom_prompt_memory.py",
+                                        "statusMessage": "Loading custom memory",
+                                    },
+                                    {
+                                        "type": "command",
+                                        "command": (
+                                            "sh -lc '"
+                                            'd="$PWD"; '
+                                            "while :; do "
+                                            'candidate="$d/plugins/evolve-lite/skills/recall/scripts/retrieve_entities.py"; '
+                                            'if [ -f "$candidate" ]; then exec python3 "$candidate"; fi; '
+                                            '[ "$d" = "/" ] && break; '
+                                            'd="$(dirname "$d")"; '
+                                            "done; "
+                                            "exit 1'"
+                                        ),
+                                        "statusMessage": "Old evolve guidance",
+                                        "delayMs": 250,
+                                    },
+                                ],
+                            }
+                        ]
+                    }
+                },
+                indent=2,
+            )
+            + "\n"
+        )
+        return hooks_file
+
+    @staticmethod
+    def create_existing_hooks_with_dict_evolve_group(project_dir: Path):
+        """Create a dict-based UserPromptSubmit group containing user hooks and the evolve hook."""
+        hooks_file = project_dir / ".codex" / "hooks.json"
+        hooks_file.parent.mkdir(parents=True, exist_ok=True)
+        hooks_file.write_text(
+            json.dumps(
+                {
+                    "hooks": {
+                        "UserPromptSubmit": [
+                            {
+                                "matcher": "src/.*",
+                                "hooks": {
+                                    "memory": {
+                                        "type": "command",
+                                        "command": "python3 ~/.codex/hooks/custom_prompt_memory.py",
+                                        "statusMessage": "Loading custom memory",
+                                    },
+                                    "evolve-lite": {
+                                        "type": "command",
+                                        "command": (
+                                            "sh -lc '"
+                                            'd="$PWD"; '
+                                            "while :; do "
+                                            'candidate="$d/plugins/evolve-lite/skills/recall/scripts/retrieve_entities.py"; '
+                                            'if [ -f "$candidate" ]; then exec python3 "$candidate"; fi; '
+                                            '[ "$d" = "/" ] && break; '
+                                            'd="$(dirname "$d")"; '
+                                            "done; "
+                                            "exit 1'"
+                                        ),
+                                        "statusMessage": "Old evolve guidance",
+                                        "delayMs": 250,
+                                    },
+                                },
+                            }
+                        ]
+                    }
+                },
+                indent=2,
+            )
+            + "\n"
+        )
+        return hooks_file
+
 
 @pytest.fixture
 def bob_fixtures():