fix(opencode): do not rewrite an OpenCode config that fails to parse (#4424)

## Description

`_parse_json_loose` returned `{}` for any parse failure, and
`inject_opencode_provider_config` / `apply_provider_scope` then wrote
the whole file back with only the Headroom provider, dropping every user
key. A leading UTF-8 BOM was one trigger, a syntax error another. This
PR ignores a leading BOM when parsing, and raises a `ClickException` for
a non-empty config that still cannot be parsed instead of overwriting
it. A file holding only a BOM (or a BOM and whitespace) counts as empty.

Fixes #4415

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/providers/opencode/config.py`: new `_try_parse_json_loose`
(strips a leading U+FEFF, returns `None` on failure);
`_parse_json_loose` keeps its `{}` contract on top of it; new
`load_user_opencode_config` raises `click.ClickException` for non-empty
unparseable text; `inject_opencode_provider_config` uses it for both
parse sites.
- `headroom/providers/opencode/install.py`: `apply_provider_scope` uses
`load_user_opencode_config`.
- Tests: BOM config keeps user keys, BOM-only and BOM-plus-whitespace
configs are treated as empty, unparseable config is left byte-identical
(config and install paths).
- Second commit (`ffef07a7`) addresses a review comment: the emptiness
check in `load_user_opencode_config` now runs after the BOM is removed.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

With only the source change reverted (new tests kept),
`tests/test_providers_opencode_config.py
tests/test_providers_opencode_install.py`:

```text
FAILED tests/test_providers_opencode_config.py::test_inject_provider_config_keeps_user_keys_with_bom
FAILED tests/test_providers_opencode_config.py::test_inject_provider_config_leaves_unparseable_config_untouched
FAILED tests/test_providers_opencode_install.py::test_apply_provider_scope_leaves_unparseable_config_untouched
======================== 3 failed, 102 passed in 1.81s ========================
```

With only the second commit's source change reverted
(`tests/test_providers_opencode_config.py`):

```text
FAILED tests/test_providers_opencode_config.py::test_inject_provider_config_treats_bom_only_config_as_empty[]
FAILED tests/test_providers_opencode_config.py::test_inject_provider_config_treats_bom_only_config_as_empty[ 
]
========================= 2 failed, 68 passed in 1.15s =========================
```

With the fix, plus the neighbouring files
(`tests/test_providers_opencode_config.py
tests/test_providers_opencode_install.py
tests/test_providers_opencode_plugin_path.py
tests/test_mcp_registry_opencode.py`):

```text
============================= 155 passed in 1.94s ==============================
```

```text
$ ruff check headroom/providers/opencode tests/test_providers_opencode_config.py tests/test_providers_opencode_install.py
All checks passed!
$ ruff format --check headroom/providers/opencode tests/test_providers_opencode_config.py tests/test_providers_opencode_install.py
6 files already formatted
```

`mypy headroom/providers/opencode` reports one error, in
`headroom/providers/model_metadata.py:79`, which this PR does not touch;
nothing in the changed files.

## Real Behavior Proof

- Environment: WSL2 Ubuntu on Windows 11, Python 3.12.15, branch based
on upstream/main `e995eb9f`; `headroom/_core.abi3.so` taken from the
official headroom-ai 0.41.0 wheel (untracked, not committed). Throwaway
HOME under `/var/tmp`, never a real user config.
- Exact command / steps: write `opencode.json` into the throwaway HOME,
then run the real CLI `headroom wrap opencode --prepare-only --no-mcp
--no-serena --port 18900` (entry `from headroom.cli import main`), then
read the file. Case A: BOM + `{"model": "gpt-4o", "keybinds": {"leader":
"ctrl+x"}}`. Case B: `{"model": "gpt-4o" "oops": 1}`. Case C: the file
holds only the three BOM bytes `ef bb bf`. Each run on the code without
the fix, then with it (case C: without the second commit's change, then
with it).
- Observed result: Case A without the fix: exit 0, file holds only
`provider.headroom`; `model` and `keybinds` are gone. Case A with the
fix: exit 0, `model` and `keybinds` kept, `provider.headroom` added (the
file is written without the BOM). Case B without the fix: exit 0, file
replaced by the Headroom-only block. Case C without the second commit:
exit 1, `Error: could not parse OpenCode config at <path>; leaving it
unchanged.`, file still the three BOM bytes. Case C with it: exit 0,
`provider.headroom` written (same as a zero-byte file). Case B with the
fix: exit 1, `Error: could not parse OpenCode config at <path>; leaving
it unchanged. Fix the JSON/JSONC syntax and retry.`, file still
`{"model": "gpt-4o" "oops": 1}`.
- Not tested: the MCP registrar (`mcp_registry/opencode.py`), which has
its own parser and still reports a BOM config as not valid JSON (it
refuses to write and leaves the file unchanged; checked by calling
`register_server` directly, so the default `wrap opencode` run without
`--no-mcp` was not run); a real `opencode` binary reading the result;
Windows paths or a real Windows editor producing the BOM; JSONC comments
combined with a BOM (comment stripping runs after the BOM strip, only
unit-level reasoning); the `headroom install` flow end to end (only
`apply_provider_scope` via a unit test); the MCP registry parser in
`mcp_registry/opencode.py` (unchanged).

Output, case A (stderr line about the retired MCP cleanup is from the
unchanged registry code):

```text
without the fix:
  "provider": { "headroom": { ... } }          # only key in the file
with the fix:
  "model": "gpt-4o", "keybinds": { "leader": "ctrl+x" }, "provider": { "headroom": { ... } }
```

Output, case B with the fix:

```text
exit: 1
Error: could not parse OpenCode config at .../.config/opencode/opencode.json; leaving it unchanged. Fix the JSON/JSONC syntax and retry.
--- after wrap
{"model": "gpt-4o" "oops": 1}
```

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: yes, narrowly: `wrap opencode` and
the OpenCode provider-scope install now stop with an error on an
unparseable non-empty config instead of overwriting it; a BOM config is
now merged instead of replaced
- Kill switch / disable path: none; fix the config file syntax, or
remove the file
- Unsafe override required: no
- Qualification impact: none expected
- Rollback path: revert this commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

N/A items: documentation (no user-facing doc describes this failure
mode), mypy (one existing error elsewhere, see above). Behavior change
to review: refusing to write is stricter than before; a file that was
silently replaced earlier now needs a manual syntax fix.

Produced with AI assistance (Claude Code) operated by me (HetCreep); the
reproduction was run on my machine on a clone of the repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
HetCreep
2026-10-24 08:38:33 -07:00
committed by GitHub
co-authored by Claude Opus 5.5 JerrettDavis
parent 7b6cb77905
commit 0fe0a597c1
4 changed files with 140 additions and 6 deletions
+30 -5
View File
@@ -196,23 +196,48 @@ def _strip_jsonc_trailing_commas(text: str) -> str:
return "".join(output)
def _parse_json_loose(text: str) -> dict[str, Any]:
def _try_parse_json_loose(text: str) -> dict[str, Any] | None:
"""Parse JSON text and JSONC comments/trailing commas.
Standard JSON is tried first so URLs containing ``//`` remain untouched.
A leading UTF-8 BOM (written by some Windows editors) is ignored.
Returns ``None`` when the text is not a JSON object.
"""
text = text.lstrip("\ufeff")
try:
parsed = json.loads(text)
return parsed if isinstance(parsed, dict) else {}
return parsed if isinstance(parsed, dict) else None
except json.JSONDecodeError:
pass
cleaned = _strip_jsonc_comments(text)
cleaned = _strip_jsonc_trailing_commas(cleaned)
try:
parsed = json.loads(cleaned)
return parsed if isinstance(parsed, dict) else {}
return parsed if isinstance(parsed, dict) else None
except json.JSONDecodeError:
return None
def _parse_json_loose(text: str) -> dict[str, Any]:
"""Like :func:`_try_parse_json_loose`, but returns ``{}`` on failure."""
return _try_parse_json_loose(text) or {}
def load_user_opencode_config(content: str, config_file: Path) -> dict[str, Any]:
"""Parse the user's OpenCode config, refusing to treat unparseable text as empty.
Callers rewrite the whole file from the result, so ``{}`` for a non-empty
file we could not read would delete every user setting.
"""
data = _try_parse_json_loose(content)
if data is None:
if content.lstrip("\ufeff").strip():
raise click.ClickException(
f"could not parse OpenCode config at {config_file}; "
"leaving it unchanged. Fix the JSON/JSONC syntax and retry."
)
return {}
return data
def _inject_key_into_json(data: dict[str, Any], key: str, value: Any) -> dict[str, Any]:
@@ -248,7 +273,7 @@ def inject_opencode_provider_config(port: int, *, keep_user_entries: bool = Fals
if config_file.exists():
content = fsutil.read_text(config_file)
data = _parse_json_loose(content)
data = load_user_opencode_config(content, config_file)
else:
content = ""
data = {}
@@ -256,7 +281,7 @@ def inject_opencode_provider_config(port: int, *, keep_user_entries: bool = Fals
# Strip any prior Headroom-managed blocks before re-injecting.
if _PROVIDER_MARKER_START in content or _MCP_MARKER_START in content:
content = strip_opencode_headroom_blocks(content)
data = _parse_json_loose(content)
data = load_user_opencode_config(content, config_file)
# Merge provider into the JSON data structure.
entry = headroom_provider_entry(port)
+2 -1
View File
@@ -13,6 +13,7 @@ from headroom.install.paths import opencode_config_path
from .config import (
_inject_key_into_json,
_parse_json_loose,
load_user_opencode_config,
migrate_legacy_opencode_jsonc_backup,
snapshot_opencode_config_if_unwrapped,
strip_opencode_headroom_blocks,
@@ -40,7 +41,7 @@ def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None
if config_file.exists():
content = fsutil.read_text(config_file)
data = _parse_json_loose(content)
data = load_user_opencode_config(content, config_file)
else:
data = {}
+88
View File
@@ -5,6 +5,7 @@ from __future__ import annotations
import json
from pathlib import Path
import click
import pytest
from headroom.providers.opencode.config import (
@@ -748,3 +749,90 @@ def test_jsonc_migration_treats_dangling_conflict_as_ambiguous(
migrate_legacy_opencode_jsonc_backup(config, canonical)
assert not canonical.exists()
assert legacy.read_bytes() == original
# ---------------------------------------------------------------------------
# Unparseable user config must not be rewritten
# ---------------------------------------------------------------------------
def test_inject_provider_config_keeps_user_keys_with_bom(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A config saved with a UTF-8 BOM keeps its user keys when the provider is injected."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
bom = chr(0xFEFF)
config_file.write_text(bom + '{"model": "gpt-4o", "mcp": {"x": {}}}', encoding="utf-8")
inject_opencode_provider_config(port=8787)
config = json.loads(config_file.read_text(encoding="utf-8"))
assert config["model"] == "gpt-4o"
assert config["mcp"] == {"x": {}}
assert "headroom" in config["provider"]
def test_inject_provider_config_leaves_unparseable_config_untouched(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A non-empty config that cannot be parsed is reported, not replaced."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
original = '{"model": "gpt-4o" "oops": 1}'
config_file.write_text(original, encoding="utf-8")
with pytest.raises(click.ClickException, match="could not parse"):
inject_opencode_provider_config(port=8787)
assert config_file.read_text(encoding="utf-8") == original
@pytest.mark.parametrize("suffix", ["", " \n"])
def test_inject_provider_config_treats_bom_only_config_as_empty(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, suffix: str
) -> None:
"""A config holding only a BOM (and whitespace) is empty, not unparseable."""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
config_file.write_text(chr(0xFEFF) + suffix, encoding="utf-8")
inject_opencode_provider_config(port=8787)
config = json.loads(config_file.read_text(encoding="utf-8"))
assert "headroom" in config["provider"]
def test_inject_provider_config_reparses_config_with_legacy_marker_block(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A config holding a comment-marked Headroom block is re-parsed after the strip.
The marker comments are what older writers left in the file; the strip runs
before the provider is merged, and the user's keys outside the block survive.
"""
_set_test_home(monkeypatch, tmp_path)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
config_file.write_text(
"{\n"
' "model": "gpt-4o",\n'
" // --- Headroom proxy provider ---\n"
' "provider": {"headroom": {"options": {"baseURL": "http://127.0.0.1:1"}}},\n'
" // --- end Headroom proxy provider ---\n"
' "theme": "dark"\n'
"}\n",
encoding="utf-8",
)
inject_opencode_provider_config(port=8787)
config = json.loads(config_file.read_text(encoding="utf-8"))
assert config["model"] == "gpt-4o"
assert config["theme"] == "dark"
headroom = config["provider"]["headroom"]
assert "8787" in json.dumps(headroom)
assert headroom.get("options", {}).get("baseURL") != "http://127.0.0.1:1"
+20
View File
@@ -5,6 +5,7 @@ from __future__ import annotations
import json
from pathlib import Path
import click
import pytest
from headroom.install.models import ConfigScope, DeploymentManifest
@@ -762,3 +763,22 @@ def test_unambiguous_legacy_backup_still_migrates_and_restores(
revert_provider_scope(mutation, manifest)
assert config.read_bytes() == original
assert not canonical.exists()
def test_apply_provider_scope_leaves_unparseable_config_untouched(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""apply_provider_scope reports an unparseable config instead of replacing it."""
monkeypatch.setenv("HOME", str(tmp_path))
monkeypatch.setenv("USERPROFILE", str(tmp_path))
monkeypatch.delenv("OPENCODE_HOME", raising=False)
monkeypatch.delenv("OPENCODE_CONFIG", raising=False)
config_file = tmp_path / ".config" / "opencode" / "opencode.json"
config_file.parent.mkdir(parents=True)
original = '{"model": "gpt-4o" "oops": 1}'
config_file.write_text(original, encoding="utf-8")
with pytest.raises(click.ClickException, match="could not parse"):
apply_provider_scope(_manifest())
assert config_file.read_text(encoding="utf-8") == original