Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

32.4 KB
Raw Blame
"""Tests for OpenCode config file helpers."""

from __future__ import annotations

import json
from pathlib import Path

import click
import pytest

from headroom.providers.opencode.config import (
    HEADROOM_OPENCODE_PLUGIN,
    _inject_key_into_json,
    _parse_json_loose,
    inject_opencode_provider_config,
    opencode_config_paths,
    snapshot_opencode_config_if_unwrapped,
    strip_opencode_headroom_blocks,
)


def _set_test_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
    home = str(tmp_path)
    monkeypatch.setenv("HOME", home)
    monkeypatch.setenv("USERPROFILE", home)
    monkeypatch.delenv("OPENCODE_HOME", raising=False)
    monkeypatch.delenv("OPENCODE_CONFIG", raising=False)


# ---------------------------------------------------------------------------
# Config paths
# ---------------------------------------------------------------------------


def test_opencode_config_paths_default(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
    """Default config path resolves to ~/.config/opencode/opencode.json."""
    _set_test_home(monkeypatch, tmp_path)
    config_file, backup_file = opencode_config_paths()
    assert config_file == tmp_path / ".config" / "opencode" / "opencode.json"
    assert backup_file == tmp_path / ".config" / "opencode" / "opencode.json.headroom-backup"


def test_opencode_config_paths_from_env(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
    """OPENCODE_CONFIG env var overrides the default path."""
    custom_path = tmp_path / "custom" / "opencode.json"
    monkeypatch.setenv("OPENCODE_CONFIG", str(custom_path))
    config_file, backup_file = opencode_config_paths()
    assert config_file == custom_path
    assert backup_file == tmp_path / "custom" / "opencode.json.headroom-backup"


def test_opencode_config_paths_default_jsonc(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """Default config path resolves to opencode.jsonc when it exists."""
    _set_test_home(monkeypatch, tmp_path)
    base_dir = tmp_path / ".config" / "opencode"
    base_dir.mkdir(parents=True, exist_ok=True)
    jsonc_path = base_dir / "opencode.jsonc"
    jsonc_path.write_text("{}")

    config_file, backup_file = opencode_config_paths()
    assert config_file == jsonc_path
    assert backup_file == base_dir / "opencode.jsonc.headroom-backup"


def test_opencode_config_paths_env_overrides_jsonc(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """OPENCODE_CONFIG takes precedence even if opencode.jsonc exists."""
    _set_test_home(monkeypatch, tmp_path)
    base_dir = tmp_path / ".config" / "opencode"
    base_dir.mkdir(parents=True, exist_ok=True)
    jsonc_path = base_dir / "opencode.jsonc"
    jsonc_path.write_text("{}")

    custom_path = tmp_path / "custom" / "opencode.json"
    monkeypatch.setenv("OPENCODE_CONFIG", str(custom_path))

    config_file, backup_file = opencode_config_paths()
    assert config_file == custom_path
    assert backup_file == tmp_path / "custom" / "opencode.json.headroom-backup"


# ---------------------------------------------------------------------------
# Snapshot
# ---------------------------------------------------------------------------


def test_snapshot_creates_backup(tmp_path: Path) -> None:
    """snapshot creates a backup copy of the config file."""
    config_file = tmp_path / "opencode.json"
    backup_file = tmp_path / "opencode.json.headroom-backup"
    config_file.write_text('{"model": "openai/gpt-4o"}')
    snapshot_opencode_config_if_unwrapped(config_file, backup_file)
    assert backup_file.exists()
    assert backup_file.read_text() == config_file.read_text()


def test_snapshot_skips_if_backup_exists(tmp_path: Path) -> None:
    """snapshot is a no-op when the backup already exists."""
    config_file = tmp_path / "opencode.json"
    backup_file = tmp_path / "opencode.json.headroom-backup"
    config_file.write_text('{"model": "a"}')
    backup_file.write_text('{"model": "b"}')
    snapshot_opencode_config_if_unwrapped(config_file, backup_file)
    assert backup_file.read_text() == '{"model": "b"}'


def test_snapshot_skips_if_markers_present(tmp_path: Path) -> None:
    """snapshot skips if the config already contains Headroom markers."""
    config_file = tmp_path / "opencode.json"
    backup_file = tmp_path / "opencode.json.headroom-backup"
    config_file.write_text("// --- Headroom proxy provider ---\n{}")
    snapshot_opencode_config_if_unwrapped(config_file, backup_file)
    assert not backup_file.exists()


# ---------------------------------------------------------------------------
# Strip blocks
# ---------------------------------------------------------------------------


def test_strip_blocks_removes_provider_and_mcp() -> None:
    """strip removes both provider and MCP blocks."""
    content = (
        "// --- Headroom proxy provider ---\n"
        '{"provider": {}}\n'
        "// --- end Headroom proxy provider ---\n"
        "// --- Headroom MCP server ---\n"
        '{"mcp": {}}\n'
        "// --- end Headroom MCP server ---\n"
        '{"model": "openai/gpt-4o"}'
    )
    cleaned = strip_opencode_headroom_blocks(content)
    assert "Headroom" not in cleaned
    assert '{"model": "openai/gpt-4o"}' in cleaned


def test_strip_blocks_preserves_user_content() -> None:
    """strip leaves user content untouched when no blocks are present."""
    content = '{"model": "openai/gpt-4o", "provider": {"openai": {}}}'
    cleaned = strip_opencode_headroom_blocks(content)
    assert cleaned == content


# ---------------------------------------------------------------------------
# Parse JSON loose
# ---------------------------------------------------------------------------


def test_parse_json_loose_strips_comments() -> None:
    """_parse_json_loose ignores // comments."""
    text = '{\n  "model": "gpt-4o", // default model\n  "provider": {}\n}'
    data = _parse_json_loose(text)
    assert data["model"] == "gpt-4o"
    assert "provider" in data


def test_parse_json_loose_returns_empty_on_invalid() -> None:
    """_parse_json_loose returns empty dict for invalid JSON."""
    assert _parse_json_loose("not json") == {}


# ---------------------------------------------------------------------------
# Inject key
# ---------------------------------------------------------------------------


def test_inject_key_merges_dicts() -> None:
    """_inject_key_into_json merges nested dicts."""
    data = {"provider": {"openai": {}}}
    data = _inject_key_into_json(data, "provider", {"headroom": {}})
    assert "openai" in data["provider"]
    assert "headroom" in data["provider"]


def test_inject_key_overwrites_non_dict() -> None:
    """_inject_key_into_json overwrites when existing value is not a dict."""
    data = {"model": "gpt-4o"}
    data = _inject_key_into_json(data, "model", "headroom/claude-sonnet-4-6")
    assert data["model"] == "headroom/claude-sonnet-4-6"


# ---------------------------------------------------------------------------
# Inject provider config
# ---------------------------------------------------------------------------


def test_inject_provider_config_creates_file(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """inject_opencode_provider_config creates the config file when missing."""
    _set_test_home(monkeypatch, tmp_path)
    inject_opencode_provider_config(port=8787)
    config_file = tmp_path / ".config" / "opencode" / "opencode.json"
    assert config_file.exists()
    config = _parse_json_loose(config_file.read_text())
    assert config["provider"]["headroom"]["npm"] == "@ai-sdk/openai-compatible"
    # Bare model ids: OpenCode resolves them as "headroom/<id>" (#1657).
    models = config["provider"]["headroom"]["models"]
    assert set(models) == {"gpt-4o", "gpt-4.1"}
    # The injected provider is OpenAI-compatible. Claude models must remain on
    # OpenCode's native Anthropic provider so they are not sent to OpenAI.
    assert not any(model_id.startswith("claude-") for model_id in models)
    assert all(not model_id.startswith("headroom/") for model_id in models)
    assert "mcp" not in config
    assert "model" not in config  # headroom provider is a transparent pass-through


def test_inject_provider_config_idempotent(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
    """inject_opencode_provider_config is safe to call multiple times."""
    _set_test_home(monkeypatch, tmp_path)
    inject_opencode_provider_config(port=8787)
    inject_opencode_provider_config(port=9999)
    config_file = tmp_path / ".config" / "opencode" / "opencode.json"
    config = _parse_json_loose(config_file.read_text())
    assert config["provider"]["headroom"]["options"]["baseURL"] == "http://127.0.0.1:9999/v1"


def test_inject_provider_config_keeps_the_users_models_and_options(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """A third-party upstream needs its own model ids and key under `headroom`.

    OpenCode only resolves `headroom/<id>` for listed ids, so wiping the user's
    entries made `wrap opencode --openai-api-url ...` unusable for DeepSeek.
    """
    _set_test_home(monkeypatch, tmp_path)
    config_file = tmp_path / ".config" / "opencode" / "opencode.json"
    config_file.parent.mkdir(parents=True)
    config_file.write_text(
        json.dumps(
            {
                "provider": {
                    "headroom": {
                        "npm": "something-else",
                        "options": {
                            "apiKey": "{env:DEEPSEEK_API_KEY}",
                            "baseURL": "https://api.deepseek.com/v1",
                        },
                        "models": {"deepseek-chat": {"name": "DeepSeek Chat"}},
                    },
                    "anthropic": {"options": {"timeout": 5}},
                }
            }
        ),
        encoding="utf-8",
    )

    inject_opencode_provider_config(port=8787, keep_user_entries=True)
    inject_opencode_provider_config(port=9999, keep_user_entries=True)

    config = _parse_json_loose(config_file.read_text())
    headroom = config["provider"]["headroom"]
    # Headroom still owns how the provider reaches the proxy.
    assert headroom["npm"] == "@ai-sdk/openai-compatible"
    assert headroom["options"]["baseURL"] == "http://127.0.0.1:9999/v1"
    # The user's key and model ids survive alongside Headroom's defaults.
    assert headroom["options"]["apiKey"] == "{env:DEEPSEEK_API_KEY}"
    assert set(headroom["models"]) == {"deepseek-chat", "gpt-4o", "gpt-4.1"}
    assert headroom["models"]["deepseek-chat"] == {"name": "DeepSeek Chat"}
    assert config["provider"]["anthropic"] == {"options": {"timeout": 5}}


def test_inject_provider_config_drops_user_entries_without_an_explicit_upstream(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """Without a named upstream the proxy forwards to OpenAI, so a kept key would go there."""
    _set_test_home(monkeypatch, tmp_path)
    config_file = tmp_path / ".config" / "opencode" / "opencode.json"
    config_file.parent.mkdir(parents=True)
    config_file.write_text(
        json.dumps(
            {
                "provider": {
                    "headroom": {
                        "npm": "something-else",
                        "options": {
                            "apiKey": "{env:DEEPSEEK_API_KEY}",
                            "baseURL": "https://api.deepseek.com/v1",
                        },
                        "models": {"deepseek-chat": {"name": "DeepSeek Chat"}},
                    },
                    "anthropic": {"options": {"timeout": 5}},
                }
            }
        ),
        encoding="utf-8",
    )

    inject_opencode_provider_config(port=8787)

    headroom = _parse_json_loose(config_file.read_text())["provider"]["headroom"]
    assert "apiKey" not in headroom["options"]
    assert set(headroom["models"]) == {"gpt-4o", "gpt-4.1"}


# ---------------------------------------------------------------------------
# Edge cases — JSON parsing
# ---------------------------------------------------------------------------


def test_parse_json_loose_handles_valid_json() -> None:
    """_parse_json_loose returns correct dict for valid JSON without comments."""
    data = _parse_json_loose('{"model": "gpt-4o", "key": "value"}')
    assert data == {"model": "gpt-4o", "key": "value"}


def test_parse_json_loose_handles_jsonc_with_comments() -> None:
    """_parse_json_loose strips comments and returns valid data."""
    text = '{\n  "model": "gpt-4o",\n  // this is a comment\n  "provider": {}\n}'
    data = _parse_json_loose(text)
    assert data["model"] == "gpt-4o"
    assert data["provider"] == {}


def test_parse_json_loose_handles_urls_in_json() -> None:
    """_parse_json_loose does NOT corrupt URLs containing //."""
    text = '{"baseURL": "http://127.0.0.1:8787/v1"}'
    data = _parse_json_loose(text)
    assert data["baseURL"] == "http://127.0.0.1:8787/v1"


def test_parse_json_loose_handles_comments_and_urls() -> None:
    """_parse_json_loose handles both comments and URLs in the same file."""
    text = (
        "{\n"
        "  // proxy configuration\n"
        '  "baseURL": "http://127.0.0.1:8787/v1",\n'
        '  "name": "Headroom // Proxy"\n'
        "}"
    )
    data = _parse_json_loose(text)
    assert data["baseURL"] == "http://127.0.0.1:8787/v1"
    assert data["name"] == "Headroom // Proxy"


def test_parse_json_loose_returns_empty_on_empty_string() -> None:
    """_parse_json_loose returns {} for empty input."""
    assert _parse_json_loose("") == {}


def test_parse_json_loose_returns_empty_on_whitespace() -> None:
    """_parse_json_loose returns {} for whitespace-only input."""
    assert _parse_json_loose("   \n  \t  ") == {}


def test_parse_json_loose_returns_empty_on_unclosed_brace() -> None:
    """_parse_json_loose returns {} for malformed JSON (unclosed brace)."""
    assert _parse_json_loose('{"model": "gpt-4o"') == {}


# ---------------------------------------------------------------------------
# Edge cases — strip blocks
# ---------------------------------------------------------------------------


def test_strip_blocks_handles_empty_string() -> None:
    """strip_opencode_headroom_blocks returns empty string for empty input."""
    assert strip_opencode_headroom_blocks("") == ""


def test_strip_blocks_handles_whitespace_only() -> None:
    """strip_opencode_headroom_blocks returns empty string for whitespace input."""
    assert strip_opencode_headroom_blocks("  \n  ") == ""


def test_strip_blocks_preserves_non_headroom_jsonc() -> None:
    """strip_opencode_headroom_blocks preserves JSONC comments not from Headroom."""
    content = '// user comment\n{"model": "gpt-4o"}\n// another user comment\n'
    cleaned = strip_opencode_headroom_blocks(content)
    assert "// user comment" in cleaned
    assert '{"model": "gpt-4o"}' in cleaned


def test_strip_blocks_removes_only_one_of_two_identical_blocks() -> None:
    """strip_opencode_headroom_blocks removes all provider blocks, not just the first."""
    from headroom.providers.opencode.config import _PROVIDER_MARKER_END, _PROVIDER_MARKER_START

    content = (
        _PROVIDER_MARKER_START
        + "\nblock1\n"
        + _PROVIDER_MARKER_END
        + "\n"
        + _PROVIDER_MARKER_START
        + "\nblock2\n"
        + _PROVIDER_MARKER_END
    )
    cleaned = strip_opencode_headroom_blocks(content)
    assert _PROVIDER_MARKER_START not in cleaned
    assert "block1" not in cleaned
    assert "block2" not in cleaned


def test_strip_blocks_handles_only_mcp_markers() -> None:
    """strip_opencode_headroom_blocks also strips MCP markers."""
    from headroom.providers.opencode.config import _MCP_MARKER_END, _MCP_MARKER_START

    content = _MCP_MARKER_START + "\nmcp data\n" + _MCP_MARKER_END
    cleaned = strip_opencode_headroom_blocks(content)
    assert _MCP_MARKER_START not in cleaned


# ---------------------------------------------------------------------------
# Edge cases — inject config
# ---------------------------------------------------------------------------


def test_inject_provider_config_preserves_existing_mcp(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """inject_opencode_provider_config preserves MCP without adding headroom."""
    _set_test_home(monkeypatch, tmp_path)
    config_file = tmp_path / ".config" / "opencode" / "opencode.json"
    config_file.parent.mkdir(parents=True, exist_ok=True)
    config_file.write_text(
        '{"mcp": {"existing-server": {"type": "remote", "url": "https://example.com"}}}'
    )

    inject_opencode_provider_config(port=8787)

    config = json.loads(config_file.read_text())
    assert "existing-server" in config["mcp"]
    assert "headroom" not in config["mcp"]


def test_inject_provider_config_idempotent_with_complex_config(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """inject_opencode_provider_config is idempotent on complex configs."""
    _set_test_home(monkeypatch, tmp_path)
    config_file = tmp_path / ".config" / "opencode" / "opencode.json"
    config_file.parent.mkdir(parents=True, exist_ok=True)
    config_file.write_text(
        json.dumps(
            {
                "model": "openai/gpt-4o",
                "provider": {"openai": {"models": {"gpt-4o": {}}}},
                "mcp": {"myserver": {"type": "local", "command": ["echo"]}},
            }
        )
    )

    inject_opencode_provider_config(port=8787)
    inject_opencode_provider_config(port=8787)

    config = json.loads(config_file.read_text())
    assert "openai" in config["provider"]
    assert "headroom" in config["provider"]
    assert "myserver" in config["mcp"]
    assert "headroom" not in config["mcp"]


def test_inject_provider_config_preserves_unrelated_top_level_keys(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """inject_opencode_provider_config preserves top-level keys like plugin, permission, etc."""
    _set_test_home(monkeypatch, tmp_path)
    config_file = tmp_path / ".config" / "opencode" / "opencode.json"
    config_file.parent.mkdir(parents=True, exist_ok=True)
    config_file.write_text(
        json.dumps(
            {
                "plugin": ["some-plugin"],
                "permission": {"bash": {"*": "ask"}},
                "model": "openai/gpt-4o",
            }
        )
    )

    inject_opencode_provider_config(port=8787)

    config = json.loads(config_file.read_text())
    assert config["plugin"] == ["some-plugin"]
    assert config["permission"] == {"bash": {"*": "ask"}}
    assert "headroom" in config.get("provider", {})


def test_inject_provider_config_no_crash_on_unwriteable_dir(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """inject_opencode_provider_config raises click.ClickException on OSError."""

    import click as click_mod

    monkeypatch.setenv("HOME", "/nonexistent/path/that/cannot/be/created")
    try:
        inject_opencode_provider_config(port=8787)
    except click_mod.ClickException:
        pass
    except OSError:
        pass


# ---------------------------------------------------------------------------
# Runtime module coverage: build_opencode_config_content, build_launch_env
# ---------------------------------------------------------------------------


def test_build_opencode_config_content_without_mcp(
    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
    from headroom.providers.opencode.runtime import build_opencode_config_content

    plugin = tmp_path / "headroom-plugin"
    plugin.mkdir()
    (plugin / "index.js").write_text("export default {}", encoding="utf-8")
    monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(plugin))

    config = build_opencode_config_content(port=8787, include_mcp=False)
    assert "mcp" not in config
    assert "model" not in config
    # Native providers are pointed at the proxy so traffic routes through Headroom.
    providers = config["provider"]
    assert providers["anthropic"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
    assert providers["openai"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
    # The headroom provider exposes only models supported by its
    # OpenAI-compatible endpoint so "headroom/<id>" resolves safely (#1657).
    assert providers["headroom"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"
    models = providers["headroom"]["models"]
    assert set(models) == {"gpt-4o", "gpt-4.1"}
    assert not any(model_id.startswith("claude-") for model_id in models)
    assert all(not model_id.startswith("headroom/") for model_id in models)
    # The transport plugin directory is injected by absolute path (opencode loads it directly).
    assert config["plugin"] == [str(plugin)]


def test_build_opencode_config_content_skips_plugin_when_unbuilt(
    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
    from headroom.providers.opencode.runtime import build_opencode_config_content

    # An override pointing at a missing file resolves to None → no plugin entry,
    # but native-provider routing still applies (the pip-only fallback).
    monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(tmp_path / "missing.js"))
    config = build_opencode_config_content(port=8787)
    assert "plugin" not in config
    assert config["provider"]["anthropic"]["options"]["baseURL"] == "http://127.0.0.1:8787/v1"


def test_build_opencode_config_content_with_mcp_uses_local_stdio() -> None:
    from headroom.providers.opencode.runtime import build_opencode_config_content

    config = build_opencode_config_content(port=9000, include_mcp=True)
    assert config["mcp"]["headroom"] == {
        "type": "local",
        "command": ["headroom", "mcp", "serve"],
        "enabled": True,
        "environment": {"HEADROOM_PROXY_URL": "http://127.0.0.1:9000"},
    }


def test_build_launch_env_with_project(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
    from headroom.providers.opencode.runtime import build_launch_env

    monkeypatch.delenv("HEADROOM_PROJECT", raising=False)
    monkeypatch.delenv("OPENAI_BASE_URL", raising=False)
    monkeypatch.delenv("ANTHROPIC_BASE_URL", raising=False)
    plugin = tmp_path / "headroom-plugin"
    plugin.mkdir()
    (plugin / "index.js").write_text("export default {}", encoding="utf-8")
    monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(plugin))

    env, display = build_launch_env(
        port=8787,
        project="test-proj",
        include_mcp=False,
    )
    assert env["HEADROOM_PROJECT"] == "test-proj"
    # Plugin loaded → its proxy target is exported for self-configuration.
    assert env["HEADROOM_PROXY_URL"] == "http://127.0.0.1:8787"
    # Compare the decoded entry: JSON escapes Windows backslashes, so the raw
    # path is not a substring of the serialized text there.
    assert json.loads(env["OPENCODE_CONFIG_CONTENT"])["plugin"] == [str(plugin)]
    assert f"plugin={HEADROOM_OPENCODE_PLUGIN}" in display
    assert "OPENAI_BASE_URL" not in env
    assert "ANTHROPIC_BASE_URL" not in env


def test_build_launch_env_forwards_session_token_when_plugin_present(
    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
    """Token reaches OpenCode only via the transport plugin -- the only
    header-capable layer (native baseURL is header-blind, like Cursor)."""
    from headroom.providers.opencode.runtime import build_launch_env

    plugin = tmp_path / "entry.opencode.js"
    plugin.write_text("export default () => {}", encoding="utf-8")
    monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(plugin))

    env, _display = build_launch_env(
        port=8787,
        include_mcp=False,
        session_token="tok-abc",
    )
    assert env["HEADROOM_OPENCODE_SESSION_TOKEN"] == "tok-abc"


def test_build_launch_env_omits_session_token_when_plugin_absent(
    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
    """No plugin -> no header surface -> token must not be forwarded,
    same as Cursor's UNKNOWN."""
    from headroom.providers.opencode.runtime import build_launch_env

    monkeypatch.setenv("HEADROOM_OPENCODE_PLUGIN_PATH", str(tmp_path / "missing.js"))

    env, _display = build_launch_env(
        port=8787,
        include_mcp=False,
        session_token="tok-abc",
    )
    assert "HEADROOM_OPENCODE_SESSION_TOKEN" not in env


def test_build_launch_env_with_custom_environ() -> None:
    from headroom.providers.opencode.runtime import build_launch_env

    custom = {
        "EXISTING_VAR": "keep-me",
        "OPENAI_BASE_URL": "https://deepseek.example/v1",
        "ANTHROPIC_BASE_URL": "https://anthropic.example",
    }
    env, display = build_launch_env(
        port=8787,
        environ=custom,
        include_mcp=False,
    )
    assert env["EXISTING_VAR"] == "keep-me"
    assert env["OPENAI_BASE_URL"] == "https://deepseek.example/v1"
    assert env["ANTHROPIC_BASE_URL"] == "https://anthropic.example"


def test_proxy_base_url() -> None:
    from headroom.providers.opencode.runtime import proxy_base_url

    assert proxy_base_url(9000) == "http://127.0.0.1:9000/v1"


def test_inject_provider_config_strips_existing_markers(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    _set_test_home(monkeypatch, tmp_path)
    config_file = tmp_path / ".config" / "opencode" / "opencode.json"
    config_file.parent.mkdir(parents=True, exist_ok=True)

    inject_opencode_provider_config(port=9000)
    first = config_file.read_text()
    assert "headroom" in first

    inject_opencode_provider_config(port=9001)
    second = config_file.read_text()
    assert "headroom" in second
    assert second.count("headroom") == first.count("headroom")


# ---------------------------------------------------------------------------
# OpenCode 2.x --standalone launch flag
# ---------------------------------------------------------------------------


@pytest.mark.parametrize(
    ("stdout", "returncode", "expected"),
    [
        ("opencode v2.0.12\n", 0, 2),
        ("1.18.32\n", 0, 1),
        ("opencode v0.0.0-v2-202610061051\n", 0, 2),
        ("0.0.0-dev-202610060234\n", 0, 0),
        ("garbage\n", 0, None),
        ("opencode v2.0.12\n", 1, None),
    ],
)
def test_opencode_major_version_parses_both_cli_formats(
    monkeypatch: pytest.MonkeyPatch, stdout: str, returncode: int, expected: int | None
) -> None:
    import subprocess

    import headroom.providers.opencode.runtime as oc_runtime

    def fake_run(*args, **kwargs):  # noqa: ANN002, ANN003
        return subprocess.CompletedProcess(args[0], returncode, stdout=stdout, stderr="")

    monkeypatch.setattr(oc_runtime, "run", fake_run)
    assert oc_runtime.opencode_major_version("opencode") == expected


def test_opencode_major_version_missing_binary_is_unknown(tmp_path: Path) -> None:
    from headroom.providers.opencode.runtime import opencode_major_version

    assert opencode_major_version(str(tmp_path / "no-such-opencode")) is None


@pytest.mark.parametrize(
    ("args", "expected"),
    [
        ((), ("--standalone",)),
        (("--continue",), ("--standalone", "--continue")),
        (("run", "fix it"), ("run", "--standalone", "fix it")),
        (("--print-logs", "mini"), ("--print-logs", "mini", "--standalone")),
        (("models",), ("models",)),
        (("auth", "list"), ("auth", "list")),
        (("--session", "models"), ("--standalone", "--session", "models")),
        (("--prompt", "models", "extra"), ("--standalone", "--prompt", "models", "extra")),
        (("-s", "stats"), ("--standalone", "-s", "stats")),
        (("run", "--agent", "models"), ("run", "--standalone", "--agent", "models")),
        (("--standalone",), ("--standalone",)),
        (
            ("run", "--server", "http://127.0.0.1:4096", "x"),
            ("run", "--server", "http://127.0.0.1:4096", "x"),
        ),
        (("--server=http://127.0.0.1:4096",), ("--server=http://127.0.0.1:4096",)),
    ],
)
def test_with_opencode_standalone_on_v2(args: tuple[str, ...], expected: tuple[str, ...]) -> None:
    from headroom.providers.opencode.runtime import with_opencode_standalone

    assert with_opencode_standalone(args, 2) == expected


@pytest.mark.parametrize("major", [1, None])
def test_with_opencode_standalone_leaves_v1_and_unknown_alone(major: int | None) -> None:
    from headroom.providers.opencode.runtime import with_opencode_standalone

    assert with_opencode_standalone(("run", "fix it"), major) == ("run", "fix it")


@pytest.mark.parametrize("conflict", ["canonical", "sibling"])
def test_jsonc_migration_treats_dangling_conflict_as_ambiguous(
    tmp_path: Path, conflict: str
) -> None:
    from headroom.providers.opencode.config import migrate_legacy_opencode_jsonc_backup

    config = tmp_path / "opencode.jsonc"
    canonical = config.with_name(config.name + ".headroom-backup")
    legacy = config.with_suffix(".json.headroom-backup")
    original = b'{"theme":"unrelated legacy"}\n'
    legacy.write_bytes(original)
    conflicting_path = canonical if conflict == "canonical" else config.with_suffix(".json")
    try:
        conflicting_path.symlink_to(tmp_path / "missing-target")
    except OSError:
        pytest.skip("creating symlinks requires platform permissions")

    migrate_legacy_opencode_jsonc_backup(config, canonical)
    assert conflicting_path.is_symlink()
    assert legacy.read_bytes() == original
    conflicting_path.unlink()
    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"