Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(agent-targets): stop re-rendering .mcp.json when the merge refuses (#1836)
Nehal kanak kuniyil thottathil77ea4eac4869
diff --git a/packages/cli/src/repowise/cli/agent_targets/formats/json_merge.py b/packages/cli/src/repowise/cli/agent_targets/formats/json_merge.pyindex 6fd01d5a5..7dac67e1c 100644--- a/packages/cli/src/repowise/cli/agent_targets/formats/json_merge.py+++ b/packages/cli/src/repowise/cli/agent_targets/formats/json_merge.py@@ -224,6 +224,270 @@ def write_json_config(path: Path, data: dict) -> FileAction:return action+# ---------------------------------------------------------------------------+# Surgical (minimal-edit) JSON merge+#+# ``write_json_config`` renders the whole document from a dict, which is the+# right call for config we own. It is the wrong call for a tracked, repo-shared+# file such as the root ``.mcp.json`` that other tools also write into: the+# file is parsed to a dict and re-serialised end to end, so pre-existing,+# unrelated server entries come back reformatted (issue #1603). The function+# below performs a *minimal edit*: only the bytes of the entry we own are+# touched, everything else in the file stays byte-identical.+# ---------------------------------------------------------------------------+++def _skip_ws(text: str, i: int, end: int) -> int:+ while i < end and text[i] in " \t\r\n":+ i += 1+ return i+++def _find_object_member(+ text: str, obj_start: int, obj_end: int, key_target: str+) -> tuple[int, int, int, int] | None:+ """Locate a ``"key": value`` member inside the object spanning *text*.++ *obj_start* points at the ``{`` and *obj_end* just past its ``}``. Returns+ ``(key_start, key_end, value_start, value_end)`` for the member whose key+ equals *key_target*, or ``None`` when the key is not present. Strict JSON+ only — this is only ever called after :func:`load_json_object` has already+ validated the document, so the scan is free to be lax about errors.+ """+ decoder = json.JSONDecoder()+ i = obj_start + 1+ while True:+ i = _skip_ws(text, i, obj_end)+ if i >= obj_end or text[i] == "}":+ return None+ if text[i] == ",":+ i += 1+ continue+ key_start = i+ try:+ key, kend = decoder.raw_decode(text, i)+ except json.JSONDecodeError:+ return None+ i = _skip_ws(text, kend, obj_end)+ if i >= obj_end or text[i] != ":":+ return None+ i = _skip_ws(text, i + 1, obj_end)+ try:+ _, vend = decoder.raw_decode(text, i)+ except json.JSONDecodeError:+ return None+ if key == key_target:+ return key_start, kend, i, vend+ i = _skip_ws(text, vend, obj_end)+++def _container_indent(text: str, obj_start: int, obj_end: int) -> str:+ """Return the whitespace prefix indenting the object's members.++ Derived from the whitespace preceding the matching closing brace, so a+ member inserted into the object is indented to sit with its siblings no+ matter the file's formatting. Falls back to ``" "`` for one-line objects.+ """+ i = obj_end - 1+ j = i+ while j > obj_start and text[j] in " \t\r\n":+ j -= 1+ if j != i:+ _, after_newline = text[j:obj_end].rsplit("\n", 1)+ if after_newline.strip() == "":+ return after_newline+ return " "+++def _render_indented(value_text: str, base_indent: str) -> str:+ """Re-indent a ``json.dumps(..., indent=2)`` block so its lines sit at+ *base_indent* relative to the opening brace.++ ``json.dumps`` emits ``{``, then keys indented by two spaces each level,+ then a closing ``}`` at column 0 — all relative to the opening brace. To+ embed that block mid-document so the keys sit at *base_indent* and the+ closing brace at *close_indent*, every line after the first gets that+ amount of leading whitespace prepended.+ """+ lines = value_text.split("\n")+ if len(lines) <= 1:+ return value_text+ return lines[0] + "\n" + "\n".join(base_indent + line for line in lines[1:])+++def _render_value_block(value: dict, member_indent: str) -> str:+ """Render a ``{ ... }`` value block whose members sit at *member_indent*.++ Produces ``{``, then each key at *member_indent* (two spaces past the+ member's own indent), then a closing ``}`` at *member_indent* — matching+ how the rest of the document lays out nested objects.+ """+ return _render_indented(json.dumps(value, indent=2), member_indent)+++def _render_member(member: str, value: dict, member_indent: str) -> str:+ """Render a ``"key": { ... }`` member at *member_indent*.++ Deterministic — the same *member*/*value*/*member_indent* always yields the+ same bytes — which is what makes the upsert idempotent: replacing an+ existing value re-produces exactly what an insert produced, so a re-run+ reports ``UNCHANGED`` instead of churning the file.+ """+ return f"{member_indent}{json.dumps(member)}: {_render_value_block(value, member_indent)}"+++def _insert_member(text: str, obj_start: int, obj_end: int, member_snippet: str) -> str | None:+ """Return *text* with *member_snippet* (a ``"key": value`` snippet)+ inserted into the object spanning *obj_start:obj_end*.++ Preserves every byte of the original object apart from the inserted member.+ Returns ``None`` when the object shape cannot be handled safely, so the+ caller leaves the file alone rather than risk corrupting it.+ """+ body = _skip_ws(text, obj_start + 1, obj_end)+ if body >= obj_end:+ return None+ if text[body] == "}":+ # Empty object ``{}`` → ``{ "key": value }``, closing brace indented+ # to match the container's members.+ return (+ text[:body]+ + "\n"+ + member_snippet+ + "\n"+ + _container_indent(text, obj_start, obj_end)+ + text[body:]+ )+ # Non-empty: walk to the end of the last member's value, then insert after+ # it, adding a comma separator unless a trailing comma is already present.+ decoder = json.JSONDecoder()+ i = obj_start + 1+ last_value_end: int | None = None+ trailing_comma = False+ while True:+ i = _skip_ws(text, i, obj_end)+ if i >= obj_end or text[i] == "}":+ break+ if text[i] == ",":+ i += 1+ continue+ try:+ _, kend = decoder.raw_decode(text, i)+ except json.JSONDecodeError:+ return None+ i = _skip_ws(text, kend, obj_end)+ if i >= obj_end or text[i] != ":":+ return None+ i = _skip_ws(text, i + 1, obj_end)+ try:+ _, vend = decoder.raw_decode(text, i)+ except json.JSONDecodeError:+ return None+ last_value_end = vend+ i = _skip_ws(text, vend, obj_end)+ trailing_comma = i < obj_end and text[i] == ","+ if trailing_comma:+ i += 1+ if last_value_end is None:+ return None+ insert_at = _skip_ws(text, last_value_end, obj_end)+ sep = "" if trailing_comma else ","+ # Append the separator immediately after the last value, then the new+ # member on its own line, then reuse the original whitespace that preceded+ # the closing brace so the brace keeps its existing indent.+ return (+ text[:last_value_end]+ + sep+ + "\n"+ + member_snippet+ + text[last_value_end:insert_at]+ + text[insert_at:]+ )+++def merge_json_object_member(+ config_path: Path,+ container_key: str,+ member: str,+ new_value: dict,+) -> FileAction:+ """Surgically upsert one ``member`` into the ``container_key`` object of a+ strict-JSON file, preserving every byte outside that member.++ This is the minimal-edit writer for tracked, repo-shared files. Unlike+ :func:`write_json_config`, which re-renders the whole document from a dict+ (reformatting unrelated content on every run), this touches only the+ ``container_key.member`` value and its surrounding separator. Other servers+ a user configured, and the file's own formatting, are left byte-for-byte+ identical (issue #1603).++ Returns the :class:`FileAction` performed. Raises ``click.ClickException``+ (via :func:`load_json_object`) when the file exists but is not strict+ JSON, so JSONC/JSON5 files are left untouched. When ``container_key`` is+ absent it is created holding just the new member; when the file itself is+ absent it is created with only ``container_key``.+ """+ if not config_path.exists():+ return write_json_config(config_path, {container_key: {member: new_value}})++ original = config_path.read_text(encoding="utf-8")+ load_json_object(config_path) # validate; raises on non-strict JSON++ root_start = _skip_ws(original, 0, len(original))+ if root_start >= len(original) or original[root_start] != "{":+ return FileAction.KEPT++ span = _find_object_member(original, root_start, len(original), container_key)++ if span is not None:+ _, _, cval_start, cval_end = span+ if original[cval_start] != "{":+ # container_key is present but not an object; leave the file alone+ # rather than guessing what a rewrite would mean.+ return FileAction.KEPT+ inner = _find_object_member(original, cval_start, cval_end, member)+ if inner is not None:+ _, _, vstart, vend = inner+ # Preserve user-added keys on the existing entry (e.g. an ``env``+ # block) while generated keys take the new values. Parse the stored+ # entry and shallow-merge the generated keys over it, so a user's+ # BYOK env survives re-registration (mirrors merge_server_entries,+ # issue #307). Then re-indent to the container's member indent and+ # re-render, which is byte-identical to what an insert produces.+ existing_entry = json.loads(original[vstart:vend])+ merged_entry = dict(existing_entry)+ merged_entry.update(new_value)+ member_indent = _container_indent(original, cval_start, cval_end) + " "+ rendered = _render_member(member, merged_entry, member_indent)+ _, value_with_indent = rendered.split(": ", 1)+ edited = original[:vstart] + value_with_indent + original[vend:]+ else:+ member_indent = _container_indent(original, cval_start, cval_end) + " "+ rendered_member = _render_member(member, new_value, member_indent)+ inserted = _insert_member(original, cval_start, cval_end, rendered_member)+ if inserted is None:+ return FileAction.KEPT+ edited = inserted+ else:+ # container_key is absent: create it holding just our member. The+ # container's closing brace sits at the root member indent, and its+ # (single) member at one level deeper, matching the document's layout.+ member_indent = _container_indent(original, root_start, len(original)) + " "+ rendered_container = (+ f"{member_indent}{json.dumps(container_key)}: "+ f"{_render_value_block({member: new_value}, member_indent)}"+ )+ inserted = _insert_member(original, root_start, len(original), rendered_container)+ if inserted is None:+ return FileAction.KEPT+ edited = inserted++ if edited == original:+ return FileAction.UNCHANGED+ atomic_write_text(config_path, edited)+ return FileAction.UPDATED++def merge_server_entries(servers: dict, new_entry: dict) -> dict:"""Deep-merge *new_entry* server definitions into *servers* in place.diff --git a/packages/cli/src/repowise/cli/agent_targets/targets/claude_code.py b/packages/cli/src/repowise/cli/agent_targets/targets/claude_code.pyindex ca59d3db5..83fcca2f4 100644--- a/packages/cli/src/repowise/cli/agent_targets/targets/claude_code.py+++ b/packages/cli/src/repowise/cli/agent_targets/targets/claude_code.py@@ -118,28 +118,46 @@ def write_project_mcp_config(repo_path: Path) -> FileWrite:Repo-shared and frequently committed, so it keeps the bare ``repowise``command: one contributor's absolute path would break every other checkout.Other servers the user configured are preserved.++ The merge is a *minimal edit* (``merge_json_object_member``): only the+ ``mcpServers.repowise`` value is touched, so unrelated servers and the+ file's own formatting stay byte-identical. Re-rendering the whole document+ from a dict would reformat pre-existing entries (issue #1603)."""from repowise.cli.mcp_config import generate_mcp_configfrom ..formats.json_merge import (- load_json_object,- merge_server_entries,+ merge_json_object_member,write_json_config,)config_path = project_mcp_config_path(repo_path)- new_entry = generate_mcp_config(repo_path)["mcpServers"]+ new_entry = generate_mcp_config(repo_path)["mcpServers"]["repowise"]if config_path.exists():- existing = load_json_object(config_path)- servers = dict(existing.get("mcpServers", {}))- merge_server_entries(servers, new_entry)- existing["mcpServers"] = servers- merged = existing+ # Surgical, minimal-edit write. ``KEPT`` means the file's shape is one we+ # cannot edit safely (``mcpServers`` present but not an object, or the+ # insertion point unresolvable), and it is not a licence to re-render.+ # Re-rendering from a dict would replace the whole document, dropping+ # every other server the user configured: a ``.mcp.json`` holding+ # ``"mcpServers": null`` or ``[]`` is exactly the case ``KEPT`` exists+ # for, and the old fallback here destroyed it instead of reporting it.+ action = merge_json_object_member(config_path, "mcpServers", "repowise", new_entry)else:- merged = {"mcpServers": new_entry}+ action = write_json_config(config_path, {"mcpServers": {"repowise": new_entry}})++ if action is FileAction.KEPT:+ return FileWrite(+ path=config_path,+ action=FileAction.KEPT,+ reason=(+ "the existing mcpServers entry is not an object, so adding "+ "repowise would rewrite the file and drop the other servers in "+ "it; make mcpServers an object or add the repowise entry by hand"+ ),+ )- return FileWrite(path=config_path, action=write_json_config(config_path, merged))+ return FileWrite(path=config_path, action=action)def _remove_project_mcp_entry(config_path: Path) -> tuple[Path, FileAction, str | None]:@@ -393,7 +411,7 @@ class ClaudeCodeTarget:if repo_path is None:raise ValueError("project-scope install needs a repo_path")written = write_project_mcp_config(repo_path)- result.record(written.path, written.action)+ result.record(written.path, written.action, written.reason)return resultif repo_path is None:diff --git a/tests/unit/cli/test_agent_targets.py b/tests/unit/cli/test_agent_targets.pyindex ef10c3aa7..905a24867 100644--- a/tests/unit/cli/test_agent_targets.py+++ b/tests/unit/cli/test_agent_targets.py@@ -1621,6 +1621,169 @@ def test_write_json_config_compares_the_bytes_it_would_land(tmp_path: Path) -> Nassert path.read_bytes() == settled+# ---------------------------------------------------------------------------+# merge_json_object_member — minimal-edit upsert (issue #1603)+# ---------------------------------------------------------------------------+++def test_merge_member_preserves_unrelated_entries_byte_identical(tmp_path: Path) -> None:+ """The core #1603 regression: unrelated servers must not be reformatted.++ The old writer re-serialised the whole ``.mcp.json`` from a dict, so a+ pre-existing entry whose formatting ``json.dumps(indent=2)`` does not+ reproduce (e.g. compact ``["-e", "VAR"]`` args) came back expanded one+ element per line. The surgical writer touches only the entry it owns.+ """+ config = tmp_path / ".mcp.json"+ original = (+ '{\n'+ ' "mcpServers": {\n'+ ' "sonarqube": {\n'+ ' "command": "sonar",\n'+ ' "args": ["-e", "SONARQUBE_TOKEN"]\n'+ ' }\n'+ ' }\n'+ '}\n'+ )+ config.write_text(original, encoding="utf-8")++ json_merge.merge_json_object_member(+ config, "mcpServers", "repowise", {"command": "repowise", "args": ["mcp"]}+ )++ # The sonarqube block is byte-for-byte what it was.+ assert (+ '"sonarqube": {\n'+ ' "command": "sonar",\n'+ ' "args": ["-e", "SONARQUBE_TOKEN"]\n'+ " }" in config.read_text(encoding="utf-8")+ )+ # And the whole file is still one valid JSON document.+ saved = json.loads(config.read_text(encoding="utf-8"))+ assert saved["mcpServers"]["sonarqube"]["args"] == ["-e", "SONARQUBE_TOKEN"]+ assert "repowise" in saved["mcpServers"]+++def test_merge_member_reports_unchanged_on_rerun(tmp_path: Path) -> None:+ """The minimal edit is idempotent: re-running writes nothing."""+ config = tmp_path / ".mcp.json"+ config.write_text(+ '{\n "mcpServers": {\n "other": {"command": "x"}\n }\n}\n',+ encoding="utf-8",+ )+ new_entry = {"command": "repowise", "args": ["mcp"]}++ assert json_merge.merge_json_object_member(+ config, "mcpServers", "repowise", new_entry+ ) is FileAction.UPDATED+ settled = config.read_bytes()+ assert json_merge.merge_json_object_member(+ config, "mcpServers", "repowise", new_entry+ ) is FileAction.UNCHANGED+ assert config.read_bytes() == settled+++def test_merge_member_preserves_user_env_on_existing_entry(tmp_path: Path) -> None:+ """User-added keys on the repowise entry survive (mirrors #307)."""+ config = tmp_path / ".mcp.json"+ config.write_text(+ json.dumps(+ {+ "mcpServers": {+ "repowise": {+ "command": "old",+ "args": ["stale"],+ "env": {"DEEPSEEK_API_KEY": "dk-secret"},+ }+ }+ },+ indent=2,+ )+ + "\n",+ encoding="utf-8",+ )++ json_merge.merge_json_object_member(+ config, "mcpServers", "repowise", {"command": "repowise", "args": ["mcp"]}+ )++ repowise = json.loads(config.read_text(encoding="utf-8"))["mcpServers"]["repowise"]+ assert repowise["env"] == {"DEEPSEEK_API_KEY": "dk-secret"}+ assert repowise["command"] == "repowise"+++def test_merge_member_creates_container_when_key_absent(tmp_path: Path) -> None:+ """A missing ``mcpServers`` container is created holding our member."""+ config = tmp_path / ".mcp.json"+ config.write_text('{\n "other": 1\n}\n', encoding="utf-8")++ json_merge.merge_json_object_member(+ config, "mcpServers", "repowise", {"command": "repowise"}+ )++ saved = json.loads(config.read_text(encoding="utf-8"))+ assert saved["other"] == 1+ assert saved["mcpServers"]["repowise"]["command"] == "repowise"+++def test_merge_member_creates_missing_file(tmp_path: Path) -> None:+ """A missing file is created with just the container and member."""+ config = tmp_path / ".mcp.json"++ assert json_merge.merge_json_object_member(+ config, "mcpServers", "repowise", {"command": "repowise"}+ ) is FileAction.CREATED++ saved = json.loads(config.read_text(encoding="utf-8"))+ assert saved["mcpServers"]["repowise"]["command"] == "repowise"+++def test_project_install_keeps_a_non_object_mcp_servers_entry(tmp_path: Path) -> None:+ """``KEPT`` must be reported, not answered with a destructive re-render.++ ``.mcp.json`` is repo-shared, so a full re-render drops every other server in+ it. A file holding ``"mcpServers": null`` is exactly what ``KEPT`` exists for,+ and the caller here used to treat that refusal as a licence to rewrite the+ document from a dict. The other server is the thing that proves it.+ """+ from repowise.cli.agent_targets.targets import claude_code as claude_target++ repo = tmp_path / "repo"+ repo.mkdir()+ config = repo / ".mcp.json"+ original = '{\n "mcpServers": null,\n "otherTopLevel": {"kept": true}\n}\n'+ config.write_text(original, encoding="utf-8")++ result = claude_target.TARGET.install(Scope.PROJECT, repo_path=repo) # type: ignore[attr-defined]++ # The file is byte-identical: we refused rather than reformatting it.+ assert config.read_text(encoding="utf-8") == original+ kept = [f for f in result.files if f.path == config]+ assert kept and kept[0].action is FileAction.KEPT+ assert kept[0].reason, "a KEPT row with no reason reads as a silent failure"+++def test_project_install_does_not_drop_other_servers(tmp_path: Path) -> None:+ """The destructive case: a sibling server must survive an array-shaped container.++ ``"mcpServers": []`` is the partially-migrated shape the review named. The old+ fallback wrote ``{"mcpServers": {"repowise": ...}}`` over the file, so any+ server a user had configured elsewhere in the document was gone.+ """+ from repowise.cli.agent_targets.targets import claude_code as claude_target++ repo = tmp_path / "repo"+ repo.mkdir()+ config = repo / ".mcp.json"+ original = '{\n "mcpServers": [],\n "sibling": "must survive"\n}\n'+ config.write_text(original, encoding="utf-8")++ claude_target.TARGET.install(Scope.PROJECT, repo_path=repo) # type: ignore[attr-defined]++ saved = json.loads(config.read_text(encoding="utf-8"))+ assert saved.get("sibling") == "must survive"++def test_codex_reinstall_reports_unchanged_and_leaves_config_alone(tmp_path: Path) -> None:"""The ``.codex/config.toml`` non-idempotency, closed.