"""Concrete tool handlers, public-safe failures, root validation, and import safety.""" import json import logging import shutil import subprocess import sys import uuid from collections.abc import Iterator from pathlib import Path from unittest.mock import patch import pytest from jsonschema import Draft202012Validator from mcp import types from mcp.server.lowlevel import Server from pydantic import JsonValue, ValidationError from riff_groove_builder.errors import OutputIOError from riff_groove_builder.schemas import ( GenerationError, GenerationResult, ProfileListResult, ToolName, tool_input_schema, tool_output_schema, ) from riff_groove_builder.server import create_server, validate_output_root ROOT = Path(__file__).resolve().parents[2] pytestmark = pytest.mark.anyio @pytest.fixture def anyio_backend() -> str: return "asyncio" @pytest.fixture def output_root() -> Iterator[Path]: path = ROOT / ".test-artifacts" / f"server-unit-{uuid.uuid4().hex}" path.mkdir(parents=True) try: yield path finally: shutil.rmtree(path) async def _call( server: Server[Path], name: str, arguments: dict[str, JsonValue] ) -> types.CallToolResult: result = await server.request_handlers[types.CallToolRequest]( types.CallToolRequest(params=types.CallToolRequestParams(name=name, arguments=arguments)) ) assert isinstance(result, types.ServerResult) assert isinstance(result.root, types.CallToolResult) if result.root.structuredContent is not None: assert len(result.root.content) == 1 assert isinstance(result.root.content[0], types.TextContent) assert json.loads(result.root.content[0].text) == result.root.structuredContent return result.root async def test_exact_tools_and_schemas(output_root: Path) -> None: server = create_server(output_root) response = await server.request_handlers[types.ListToolsRequest]( types.ListToolsRequest(method="tools/list") ) assert isinstance(response.root, types.ListToolsResult) tools = response.root.tools assert [tool.name for tool in tools] == ["list_instrument_profiles", "generate_music"] names: tuple[ToolName, ...] = ("list_instrument_profiles", "generate_music") for name, tool in zip(names, tools, strict=True): assert tool.inputSchema == tool_input_schema(name) assert tool.outputSchema == tool_output_schema(name) guidance = tools[1].description or "" for phrase in ( "Omit formats", "lead -> griff", "bass -> briff", "drums -> sd3p", "mid works for all", "Omit profiles", "never invent profile IDs", "Never add CC events without user intent", "triplet", "preserve user intent", ): assert phrase in guidance async with server.lifespan(server) as stored_root: assert stored_root == output_root capabilities = server.create_initialization_options().capabilities assert capabilities.tools is not None assert capabilities.resources is None assert capabilities.prompts is None assert capabilities.logging is None @pytest.mark.parametrize( ("name", "arguments"), [ ("list_instrument_profiles", {"private-property": "private-value"}), ("generate_music", {}), ("generate_music", {"description": "private-description", "basename": "../private-path"}), ("generate_music", {"description": "private-description", "basename": "x", "bars": True}), ("generate_music", {"description": "private-description", "basename": "x", "bars": 4.0}), ("generate_music", {"description": "private-description", "basename": "x", "seed": "4"}), ( "generate_music", {"description": "private-description", "basename": "x", "tempo_bpm": True}, ), ( "generate_music", { "description": "private-description", "basename": "x", "time_signature": {"numerator": 4, "denominator": 4.0}, }, ), ( "generate_music", { "description": "private-description", "basename": "x", "parts": ["lead"], "formats": ["sdp"], }, ), ( "generate_music", { "description": "private-description", "basename": "x", "parts": ["lead"], "profiles": {"drums": "private-profile"}, }, ), ( "generate_music", {"description": "private-description", "basename": "x", "parts": ["lead", "lead"]}, ), ( "generate_music", {"description": "private-description", "basename": "x", "private-property": "secret"}, ), ( "generate_music", { "description": "private-description", "basename": "x", "profiles": {"private-property": "private-value"}, }, ), ], ) async def test_authoritative_validation_is_public_safe( output_root: Path, name: ToolName, arguments: dict[str, JsonValue], caplog: pytest.LogCaptureFixture, ) -> None: result = await _call(create_server(output_root), name, arguments) assert result.isError assert result.structuredContent is not None error = GenerationError.model_validate(result.structuredContent) assert error.code == "INVALID_REQUEST" assert error.details["issues"] Draft202012Validator(tool_output_schema(name)).validate(result.structuredContent) assert "private-" not in result.model_dump_json() + caplog.text assert "secret" not in result.model_dump_json() + caplog.text assert not list(output_root.iterdir()) async def test_real_registry_and_generation(output_root: Path) -> None: server = create_server(output_root) profiles = await _call(server, "list_instrument_profiles", {}) assert not profiles.isError summaries = ProfileListResult.model_validate(profiles.structuredContent).profiles assert len(summaries) == 6 assert [profile.mapping_kind for profile in summaries] == [ "instrument", "instrument", "standard_midi", "standard_midi", "standard_midi", "instrument", ] assert [profile.native_available for profile in summaries] == [ True, True, False, False, False, False, ] assert isinstance(profiles.content[0], types.TextContent) assert json.loads(profiles.content[0].text)["profiles"][0]["id"] == ( "ample.ame.4.0.1.riffer.v1" ) result = await _call( server, "generate_music", {"description": "lead only 1 bar quarter", "basename": "example"} ) assert not result.isError generated = GenerationResult.model_validate(result.structuredContent) assert generated.status == "complete" assert generated.artifacts[0].fallback_for == [] assert [artifact.format for artifact in generated.artifacts] == ["mid", "griff"] assert Path(generated.artifacts[0].path).read_bytes().startswith(b"MThd") assert isinstance(result.content[0], types.TextContent) assert json.loads(result.content[0].text)["artifacts"][0]["path"] == ( generated.artifacts[0].path ) Draft202012Validator(tool_output_schema("generate_music")).validate(result.structuredContent) assert list(output_root.iterdir()) == [output_root / "example"] @pytest.mark.parametrize("name", ["list_instrument_profiles", "generate_music"]) async def test_domain_error_preserves_public_contract_only( output_root: Path, caplog: pytest.LogCaptureFixture, name: ToolName ) -> None: error = OutputIOError(details={"reason": "public_reason"}) error.__cause__ = OSError("private-fixture-path secret") with patch(f"riff_groove_builder.server.GenerationService.{name}", side_effect=error): result = await _call( create_server(output_root), name, {} if name == "list_instrument_profiles" else {"description": "private-description", "basename": "x"}, ) assert result.isError assert result.structuredContent == { "code": error.code, "message": error.public_message, "details": {"reason": "public_reason"}, } assert "private-" not in result.model_dump_json() + caplog.text async def test_unexpected_failure_is_diagnostic_not_silent( output_root: Path, caplog: pytest.LogCaptureFixture ) -> None: with ( caplog.at_level(logging.ERROR), patch( "riff_groove_builder.server.GenerationService.generate_music", side_effect=OSError("private-fixture-path secret"), ), ): result = await _call( create_server(output_root), "generate_music", {"description": "riff", "basename": "x"} ) assert result.isError assert result.structuredContent is None assert "Unexpected tool execution failure (OSError)." in caplog.text assert "private-" not in result.model_dump_json() + caplog.text assert "secret" not in result.model_dump_json() + caplog.text assert not list(output_root.iterdir()) async def test_wrong_format_with_valid_key_identifies_formats(output_root: Path) -> None: result = await _call( create_server(output_root), "generate_music", { "description": "lead only 1 bar quarter", "basename": "wrong", "parts": ["lead"], "formats": ["sd3p", "mid"], "key": "E minor", "profiles": {"lead": "aggressive_rock"}, "cc_events": [ {"part": "lead", "beat": {"numerator": 0}, "controller": 91, "value": 64} ], }, ) assert result.isError error = GenerationError.model_validate(result.structuredContent) issues = error.details["issues"] assert isinstance(issues, list) and len(issues) == 1 issue = issues[0] assert isinstance(issue, dict) assert issue["field"] == "formats" and issue["reason"] == "format_parts" assert "sd3p/sdp requires drums" in str(issue["correction"]) assert "Guitar lead uses griff/agp or mid" in str(issue["correction"]) assert "aggressive_rock" not in result.model_dump_json() assert not list(output_root.iterdir()) @pytest.mark.parametrize( ("updates", "field", "guidance"), [ ({"key": "private-mode"}, "key", "Em, F#m, Bbm"), ({"time_signature": "4/4"}, "time_signature", "integer numerator 1-16"), ( {"time_signature": {"numerator": 4, "denominator": True}}, "time_signature.denominator", "integer denominator", ), ({"parts": ["guitar"]}, "parts.0", "guitar is lead"), ({"formats": ["wav"]}, "formats.0", "griff/agp or mid"), ({"parts": ["lead", "lead"]}, "parts", "duplicate"), ({"profiles": {"lead": 123}}, "profiles.lead", "list_instrument_profiles({})"), ({"bars": True}, "bars", "1 through 256"), ({"tempo_bpm": 301}, "tempo_bpm", "20 through 300"), ({"private-property": "private-value"}, "", "Remove unknown"), ( { "cc_events": [ {"part": "guitar", "beat": {"numerator": 0}, "controller": 1, "value": 2} ] }, "cc_events.0.part", "part must be selected", ), ( {"cc_events": [{"part": "lead", "beat": 0, "controller": 1, "value": 2}]}, "cc_events.0.beat", "quarter-note beats", ), ( { "cc_events": [ {"part": "lead", "beat": {"numerator": 0}, "controller": True, "value": 2} ] }, "cc_events.0.controller", "integers 0-127", ), ( { "cc_events": [ { "part": "lead", "beat": {"numerator": 1, "denominator": 7}, "controller": 1, "value": 2, } ] }, "cc_events", "960", ), ( { "cc_events": [ { "part": "lead", "beat": {"numerator": 0}, "controller": 1, "value": 2, "private-property": "private-value", } ] }, "cc_events.0.", "Remove unknown", ), ], ) async def test_field_guidance_is_safe_and_actionable( output_root: Path, updates: dict[str, JsonValue], field: str, guidance: str ) -> None: result = await _call( create_server(output_root), "generate_music", {"description": "private-description", "basename": "x", **updates}, ) error = GenerationError.model_validate(result.structuredContent) assert result.isError and error.code == "INVALID_REQUEST" issues = error.details["issues"] assert isinstance(issues, list) assert any( isinstance(issue, dict) and issue["field"] == field and guidance in str(issue["correction"]) for issue in issues ) assert "private-" not in result.model_dump_json() assert not list(output_root.iterdir()) async def test_missing_fields_and_cross_field_cc_corrections(output_root: Path) -> None: server = create_server(output_root) missing = await _call(server, "generate_music", {}) error = GenerationError.model_validate(missing.structuredContent) issues = error.details["issues"] assert isinstance(issues, list) assert {issue["field"] for issue in issues if isinstance(issue, dict)} == { "description", "basename", } assert all( isinstance(issue, dict) and "Supply this required field" in str(issue["correction"]) for issue in issues ) cc: dict[str, JsonValue] = { "part": "lead", "beat": {"numerator": 0}, "controller": 1, "value": 2, } cases: list[tuple[dict[str, JsonValue], str, str]] = [ ({"cc_events": [cc, cc]}, "cc_duplicates", "cc_events"), ({"parts": ["drums"], "cc_events": [cc]}, "cc_parts", "cc_events"), ( {"parts": ["lead"], "profiles": {"drums": "private-profile"}}, "profile_parts", "profiles", ), ] for updates, reason, field in cases: result = await _call( server, "generate_music", {"description": "private-description", "basename": "x", **updates}, ) failure = GenerationError.model_validate(result.structuredContent) assert result.isError actual = failure.details["issues"] assert isinstance(actual, list) and isinstance(actual[0], dict) assert actual[0]["field"] == field and actual[0]["reason"] == reason assert actual[0]["correction"] assert "private-" not in result.model_dump_json() assert not list(output_root.iterdir()) @pytest.mark.parametrize( ("updates", "code", "guidance"), [ ( {"profiles": {"lead": "private-invented-id"}}, "PROFILE_REQUIRED", "omit profiles for defaults", ), ( {"profiles": {"lead": "standard.bass.v1"}}, "PROFILE_REQUIRED", "list_instrument_profiles({})", ), ( {"description": "private-description triplet melody"}, "UNSUPPORTED_DESCRIPTION", "Arbitrary triplet patterns", ), ( { "cc_events": [ {"part": "lead", "beat": {"numerator": 5}, "controller": 1, "value": 2} ] }, "INVALID_REQUEST", "within the musical duration", ), ], ) async def test_real_domain_errors_offer_text_only_recovery( output_root: Path, updates: dict[str, JsonValue], code: str, guidance: str ) -> None: result = await _call( create_server(output_root), "generate_music", {"description": "lead only 1 bar quarter", "basename": "x", **updates}, ) assert result.isError assert result.structuredContent is not None assert result.structuredContent["code"] == code assert isinstance(result.content[0], types.TextContent) assert guidance in result.content[0].text assert "private-" not in result.content[0].text assert not list(output_root.iterdir()) async def test_internal_model_failure_is_not_blame_on_input( output_root: Path, caplog: pytest.LogCaptureFixture ) -> None: with pytest.raises(ValidationError) as captured: ProfileListResult.model_validate({"private-property": "secret"}) with patch( "riff_groove_builder.server.GenerationService.generate_music", side_effect=captured.value ): result = await _call( create_server(output_root), "generate_music", {"description": "riff", "basename": "x"} ) assert result.isError assert result.structuredContent is None assert "Unexpected tool execution failure (ValidationError)." in caplog.text assert "private-" not in result.model_dump_json() + caplog.text assert "secret" not in result.model_dump_json() + caplog.text @pytest.mark.parametrize( "value", [ "", " ", ".\n", "https://example.invalid/root", "file:///C:/music", r"\\server\share", "//server/share", r"\\?\C:\music", r"\\.\NUL", r"\rooted-on-current-drive", "C:relative", "C:\\music:stream", "\x00", ], ) def test_reject_unsafe_roots(value: str) -> None: with pytest.raises(ValueError, match="existing local directory"): validate_output_root(value) def test_root_must_exist_and_be_directory(output_root: Path) -> None: assert validate_output_root(str(output_root)) == output_root.resolve() assert validate_output_root(".") == ROOT with pytest.raises(ValueError): validate_output_root(str(output_root / "missing")) file = output_root / "sentinel" file.write_text("existing unrelated data", encoding="utf-8") with pytest.raises(ValueError): validate_output_root(str(file)) assert file.read_text(encoding="utf-8") == "existing unrelated data" assert not (output_root / "missing").exists() @pytest.mark.parametrize( "module", ["riff_groove_builder", "riff_groove_builder.server", "riff_groove_builder.__main__"] ) def test_import_is_silent_without_cli(module: str, output_root: Path) -> None: result = subprocess.run( [sys.executable, "-I", "-B", "-c", f"import {module}"], cwd=output_root, capture_output=True, timeout=15, check=False, ) assert result.returncode == 0, result.stderr assert result.stdout == result.stderr == b"" assert not list(output_root.iterdir()) def test_required_cli_argument(capsys: pytest.CaptureFixture[str]) -> None: from riff_groove_builder.__main__ import main with pytest.raises(SystemExit) as error: main([]) assert error.value.code == 2 captured = capsys.readouterr() assert captured.out == "" assert "--output-dir" in captured.err