llm-tool-cli 0.2.0__py3-none-any.whl

llm_tool_cli/protocol/output_cells/tests/test_human.py

@@ -0,0 +1,112 @@
+import pytest
+
+from llm_tool_cli.protocol.output_cells.base import RenderContext
+from llm_tool_cli.protocol.output_cells.human import HumanErrorOutputCell, HumanOutputCell, HumanWarningOutputCell
+from llm_tool_cli.protocol.output_cells.tests.make import cell
+
+
+class TestHumanOutputCell:
+    def test_render__renders_human_cell_with_sorted_metadata(self) -> None:
+        formatted = (
+            cell(
+                HumanOutputCell,
+            )
+            .render(RenderContext(index=0, total=1, tool_label="TOOL"))
+            .decode()
+        )
+
+        assert formatted == "alpha: first\nenabled: True\nmissing: None\nzeta: 2\n\nSample content.\n\n"
+
+    def test_render__omits_media_type_and_content_when_absent(self) -> None:
+        formatted = (
+            cell(HumanOutputCell, media_type=None, content=None, meta={})
+            .render(RenderContext(index=0, total=1, tool_label="TOOL"))
+            .decode()
+        )
+
+        assert formatted == "sample_status\n\n"
+
+    def test_render__omits_empty_content_section(self) -> None:
+        formatted = (
+            cell(HumanOutputCell, content="", meta={})
+            .render(RenderContext(index=0, total=1, tool_label="TOOL"))
+            .decode()
+        )
+
+        assert formatted == "sample_status\n\n"
+
+    def test_render__preserves_unicode_content_and_list_metadata(self) -> None:
+        source = cell(HumanOutputCell, content="日本語\nSecond line.", meta={"labels": ["一", "two"]})
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL")).decode()
+
+        assert formatted == "labels: ['一', 'two']\n\n日本語\nSecond line.\n\n"
+
+    def test_render__omits_redundant_type_and_preserves_application_metadata(self) -> None:
+        source = HumanOutputCell.build_meta(kind="status", type="status", id="domain-id", count=0, labels=[])
+        original = source.model_dump()
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL")).decode()
+
+        assert formatted == "count: 0\nid: domain-id\nlabels: []\n\n"
+        assert source.model_dump() == original
+
+    def test_render__preserves_type_when_it_has_a_distinct_meaning(self) -> None:
+        source = HumanOutputCell.build_meta(kind="status", type="custom")
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL")).decode()
+
+        assert formatted == "type: custom\n\n"
+
+    def test_render__shows_content_without_metadata(self) -> None:
+        source = HumanOutputCell.build_markdown(kind="document", content="First paragraph.\n\nSecond paragraph.")
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL")).decode()
+
+        assert formatted == "First paragraph.\n\nSecond paragraph.\n\n"
+
+
+class TestHumanErrorOutputCell:
+    def test_render__shows_message_without_diagnostic_context(self) -> None:
+        source = HumanErrorOutputCell.build_markdown(kind="error", content="失敗", type="error")
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL")).decode()
+
+        assert formatted == "Error: 失敗\n\n"
+
+    def test_render__shows_message_and_guidance_before_diagnostic_context(self) -> None:
+        source = HumanErrorOutputCell.build_markdown(
+            kind="error",
+            content="Service unavailable.\nWay to fix: Retry later.",
+            type="error",
+            code="unavailable",
+            path="/project",
+        )
+        original = source.model_dump()
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL")).decode()
+
+        assert formatted == (
+            "Error: Service unavailable.\nWay to fix: Retry later.\n\ncode: unavailable\npath: /project\n\n"
+        )
+        assert source.model_dump() == original
+
+    @pytest.mark.parametrize("content", [None, ""])
+    def test_render__retains_diagnostics_without_a_message(self, content: str | None) -> None:
+        source = HumanErrorOutputCell.build(kind="error", media_type="text/markdown", content=content, code="empty")
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL")).decode()
+
+        assert formatted == "Error:\n\ncode: empty\n\n"
+
+
+class TestHumanWarningOutputCell:
+    @pytest.mark.parametrize("message", ["first\nsecond", "café", ""])
+    def test_render__shows_warning_message_without_record_fields(self, message: str) -> None:
+        source = HumanWarningOutputCell.build_meta(kind="warning", type="warning", message=message)
+        original = source.model_dump()
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL")).decode()
+
+        assert formatted == f"Warning: {message}".rstrip() + "\n\n"
+        assert source.model_dump() == original

llm_tool_cli/protocol/output_cells/tests/test_llm.py

@@ -0,0 +1,65 @@
+from llm_tool_cli.protocol.output_cells.base import RenderContext
+from llm_tool_cli.protocol.output_cells.llm import LLMOutputCell
+from llm_tool_cli.protocol.output_cells.tests.make import cell
+
+
+class TestLLMOutputCell:
+    def test_render__renders_llm_cell_with_sorted_metadata(self) -> None:
+        formatted = (
+            cell(
+                LLMOutputCell,
+            )
+            .render(RenderContext(index=0, total=1, tool_label="TOOL"))
+            .decode()
+        )
+
+        assert formatted == (
+            "--TOOL-CELL EjRWeBI0VniSNFZ4EjRWeA BEGIN--\n"
+            "kind=sample_status\n"
+            "media_type=text/markdown\n"
+            "alpha=first\n"
+            "enabled=True\n"
+            "missing=None\n"
+            "zeta=2\n"
+            "\n"
+            "Sample content.\n"
+            "--TOOL-CELL EjRWeBI0VniSNFZ4EjRWeA END--\n"
+        )
+
+    def test_render__omits_media_type_and_content_when_absent(self) -> None:
+        formatted = (
+            cell(LLMOutputCell, media_type=None, content=None, meta={})
+            .render(RenderContext(index=0, total=1, tool_label="TOOL"))
+            .decode()
+        )
+
+        assert formatted == (
+            "--TOOL-CELL EjRWeBI0VniSNFZ4EjRWeA BEGIN--\n"
+            "kind=sample_status\n"
+            "--TOOL-CELL EjRWeBI0VniSNFZ4EjRWeA END--\n"
+        )
+
+    def test_render__omits_empty_content_section(self) -> None:
+        formatted = (
+            cell(LLMOutputCell, content="", meta={})
+            .render(RenderContext(index=0, total=1, tool_label="TOOL"))
+            .decode()
+        )
+
+        assert formatted == (
+            "--TOOL-CELL EjRWeBI0VniSNFZ4EjRWeA BEGIN--\n"
+            "kind=sample_status\nmedia_type=text/markdown\n"
+            "--TOOL-CELL EjRWeBI0VniSNFZ4EjRWeA END--\n"
+        )
+
+    def test_render__preserves_unicode_content_and_list_metadata(self) -> None:
+        source = cell(LLMOutputCell, content="日本語\nSecond line.", meta={"labels": ["一", "two"]})
+
+        formatted = source.render(RenderContext(index=0, total=1, tool_label="TOOL")).decode()
+
+        assert formatted == (
+            "--TOOL-CELL EjRWeBI0VniSNFZ4EjRWeA BEGIN--\n"
+            "kind=sample_status\nmedia_type=text/markdown\n"
+            "labels=['一', 'two']\n\n日本語\nSecond line.\n"
+            "--TOOL-CELL EjRWeBI0VniSNFZ4EjRWeA END--\n"
+        )

llm_tool_cli/protocol/serialization.py

@@ -0,0 +1,7 @@
+import json
+from collections.abc import Mapping
+
+
+def to_jsonl(record: Mapping[str, object]) -> str:
+    """Serialize a record as one compact, Unicode-preserving JSON line."""
+    return json.dumps(dict(record), ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n"

llm_tool_cli/protocol/tests/helpers.py

@@ -0,0 +1,25 @@
+import base64
+import uuid
+
+from llm_tool_cli.core.errors import EnvironmentErrors
+
+
+def cell_payloads(records: list[dict[str, object]]) -> list[dict[str, object]]:
+    """Validate generated cell IDs and return payload copies without them."""
+    payloads = []
+    for record in records:
+        payload = dict(record)
+        cell_id = payload.pop("id")
+        assert isinstance(cell_id, str)
+        assert uuid.UUID(bytes=base64.urlsafe_b64decode(cell_id + "==")).version == 4
+        payloads.append(payload)
+    return payloads
+
+
+def assert_error_cells(records: list[dict[str, object]], errors: EnvironmentErrors) -> None:
+    """Assert native automation diagnostics without corrective guidance."""
+    assert len(records) == len(errors)
+    for actual, error in zip(cell_payloads(records), errors):
+        expected = error.as_record()
+        expected["content"] = expected.pop("message")
+        assert actual == expected

llm_tool_cli/protocol/tests/test_cell_shortcuts.py

@@ -0,0 +1,126 @@
+from pathlib import Path
+
+import pytest
+
+from llm_tool_cli.core.errors import EnvironmentError
+from llm_tool_cli.paths import ProjectConfigPath
+from llm_tool_cli.protocol import Protocol, cell_shortcuts
+from llm_tool_cli.protocol.logic_cells import EnvironmentErrorCell
+
+
+class TestOperationSucceeded:
+    def test_creates_markdown_operation_succeeded_cell(self) -> None:
+        cell = cell_shortcuts.operation_succeeded("Done.", operation="setup")
+
+        assert cell.kind == "operation_succeeded"
+        assert cell.media_type == "text/markdown"
+        assert cell.content == "Done."
+        assert cell.meta == {"type": "operation_succeeded", "operation": "setup"}
+
+    @pytest.mark.parametrize("protocol", list(Protocol))
+    @pytest.mark.parametrize("message", ["Done.", ""])
+    def test_default_success_payload(self, protocol: Protocol, message: str) -> None:
+        cell = cell_shortcuts.operation_succeeded(message)
+
+        outputs = cell.render(protocol)
+
+        assert len(outputs) == 1
+        assert outputs[0].model_dump(exclude={"id"}) == {
+            "kind": "operation_succeeded",
+            "media_type": "text/markdown",
+            "content": message,
+            "meta": {"type": "operation_succeeded"},
+        }
+
+    def test_explicit_metadata_retains_precedence(self) -> None:
+        cell = cell_shortcuts.operation_succeeded("Done.", type="custom_success", path="config.toml")
+
+        assert cell.meta == {"type": "custom_success", "path": "config.toml"}
+
+
+class TestConfigurationCreated:
+    @pytest.mark.parametrize("protocol", list(Protocol))
+    @pytest.mark.parametrize("path", ["/project/config.toml", "folder name/café.toml"])
+    def test_shared_creation_payload_preserves_path(self, protocol: Protocol, path: str) -> None:
+        cell = cell_shortcuts.configuration_created(ProjectConfigPath(Path(path)))
+
+        outputs = cell.render(protocol)
+
+        assert len(outputs) == 1
+        assert outputs[0].model_dump(exclude={"id"}) == {
+            "kind": "operation_succeeded",
+            "media_type": "text/markdown",
+            "content": "Configuration created.",
+            "meta": {"type": "operation_succeeded", "path": path},
+        }
+
+
+class TestOperationFailed:
+    def test_creates_markdown_operation_failed_cell(self) -> None:
+        cell = cell_shortcuts.operation_failed("Failed.", operation="setup")
+
+        assert cell.kind == "operation_failed"
+        assert cell.media_type == "text/markdown"
+        assert cell.content == "Failed."
+        assert cell.meta == {"operation": "setup"}
+
+
+class TestInfo:
+    def test_creates_markdown_info_cell(self) -> None:
+        cell = cell_shortcuts.info("Ready.", scope="workspace")
+
+        assert cell.kind == "info"
+        assert cell.media_type == "text/markdown"
+        assert cell.content == "Ready."
+        assert cell.meta == {"scope": "workspace"}
+
+
+class TestSkill:
+    @pytest.mark.parametrize("protocol", list(Protocol))
+    @pytest.mark.parametrize("content", ["# Custom guide\n\nInstructions for café.", ""])
+    def test_shared_skill_payload(self, protocol: Protocol, content: str) -> None:
+        cell = cell_shortcuts.skill(document="custom-guide", content=content)
+
+        outputs = cell.render(protocol)
+
+        assert len(outputs) == 1
+        assert outputs[0].model_dump(exclude={"id"}) == {
+            "kind": "skill",
+            "media_type": "text/markdown",
+            "content": content,
+            "meta": {"type": "skill", "document": "custom-guide"},
+        }
+
+    def test_empty_document_name(self) -> None:
+        cell = cell_shortcuts.skill(document="", content="Instructions.")
+
+        assert cell.meta == {"type": "skill", "document": ""}
+
+
+class TestVersion:
+    @pytest.mark.parametrize("protocol", list(Protocol))
+    @pytest.mark.parametrize("value", ["1.2.3", "1.2.3rc1+local", ""])
+    def test_shared_version_payload(self, protocol: Protocol, value: str) -> None:
+        cell = cell_shortcuts.version(value)
+
+        outputs = cell.render(protocol)
+
+        assert len(outputs) == 1
+        assert outputs[0].model_dump(exclude={"id"}) == {
+            "kind": "version",
+            "media_type": None,
+            "content": None,
+            "meta": {"type": "version", "version": value},
+        }
+
+
+class TestEnvironmentError:
+    @pytest.mark.parametrize("protocol", list(Protocol))
+    def test_retains_error_until_projection(self, protocol: Protocol) -> None:
+        error = EnvironmentError(code="unavailable", message="Try later.", ways_to_fix=["Retry."])
+
+        cell = cell_shortcuts.environment_error(error)
+
+        assert isinstance(cell, EnvironmentErrorCell)
+        assert cell.error == error
+        assert cell.render(protocol)[0].content == "Try later.\nWay to fix: Retry."

llm_tool_cli/protocol/tests/test_journal.py

@@ -0,0 +1,44 @@
+import datetime
+
+from llm_tool_cli.protocol.journal import JournalRecord
+
+
+class TestJournalRecord:
+    def test_as_dict__flattens_attributes_and_protects_common_fields(self) -> None:
+        timestamp = datetime.datetime.now(datetime.UTC)
+        record = JournalRecord(
+            message="message",
+            timestamp=timestamp,
+            attributes={
+                "message": "conflict",
+                "actor_id": "conflict",
+                "timestamp": "conflict",
+                "task_id": None,
+                "context": {"items": ["first", "second"]},
+            },
+        )
+        original = record.model_dump()
+        fields = record.as_dict()
+        assert fields == {
+            "message": "message",
+            "timestamp": timestamp.isoformat(),
+            "actor_id": None,
+            "task_id": None,
+            "context": {"items": ["first", "second"]},
+        }
+        assert record.model_dump() == original
+        assert "attributes" not in fields
+
+    def test_as_dict__returns_independent_nested_data(self) -> None:
+        record = JournalRecord(message="event", attributes={"items": ["one"]})
+        fields = record.as_dict()
+        items = fields["items"]
+        assert isinstance(items, list)
+        items.append("two")
+        assert record.as_dict()["items"] == ["one"]
+
+    def test_timestamp__defaults_to_current_utc_time(self) -> None:
+        start = datetime.datetime.now(datetime.UTC)
+        record = JournalRecord(message="event")
+        assert start <= record.timestamp <= datetime.datetime.now(datetime.UTC)
+        assert record.timestamp.utcoffset() == datetime.timedelta(0)

llm_tool_cli/protocol/tests/test_serialization.py

@@ -0,0 +1,33 @@
+import json
+from types import MappingProxyType
+
+import pytest
+
+from llm_tool_cli.protocol import Protocol, to_jsonl
+
+
+class TestToJsonl:
+    def test_compact_sorted_unicode_record(self) -> None:
+        record = {"z": "日本語", "a": {"z": [True, None, "first\nsecond"], "a": 1}}
+
+        output = to_jsonl(record)
+
+        assert output == '{"a":{"a":1,"z":[true,null,"first\\nsecond"]},"z":"日本語"}\n'
+        assert json.loads(output) == record
+        assert len(output.splitlines()) == 1
+
+    def test_mapping(self) -> None:
+        record = MappingProxyType({"b": 2, "a": 1})
+
+        assert to_jsonl(record) == '{"a":1,"b":2}\n'
+
+    def test_empty_record(self) -> None:
+        assert to_jsonl({}) == "{}\n"
+
+    @pytest.mark.parametrize("mode", ["human", "llm", "automation"])
+    def test_protocol_wire_value(self, mode: str) -> None:
+        assert to_jsonl({"mode": Protocol(mode)}) == f'{{"mode":"{mode}"}}\n'
+
+    def test_unsupported_value(self) -> None:
+        with pytest.raises(TypeError):
+            to_jsonl({"value": object()})

llm_tool_cli/skills/__init__.py

@@ -0,0 +1,6 @@
+"""Packaged skill-document loading independent of document selection and output."""
+
+from llm_tool_cli.skills import errors as errors
+from llm_tool_cli.skills.fixtures import load_skill_text
+
+__all__ = ["errors", "load_skill_text"]

llm_tool_cli/skills/errors.py

@@ -0,0 +1,12 @@
+from llm_tool_cli.core import errors as core_errors
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    """An expected failure while loading a packaged skill document."""
+
+
+class SkillUnreadable(EnvironmentError):
+    code: str = "skill_unreadable"
+    message: str = "could not read skill document `{error.document}`: {error.reason}"
+    document: str
+    reason: str

llm_tool_cli/skills/fixtures.py

@@ -0,0 +1,14 @@
+import importlib.resources
+
+from llm_tool_cli.core.result import Err, Ok, Result
+from llm_tool_cli.skills.errors import SkillUnreadable
+
+
+def load_skill_text(package: str, document: str) -> Result[str]:
+    """Read a selected document from an application-owned package's fixtures."""
+    try:
+        return Ok(
+            importlib.resources.files(package).joinpath("fixtures", f"{document}.md").read_text(encoding="utf-8")
+        )
+    except (OSError, UnicodeDecodeError) as error:
+        return Err([SkillUnreadable(document=document, reason=str(error)).with_cause(error)])

llm_tool_cli/skills/tests/test_fixtures.py

@@ -0,0 +1,58 @@
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+from pytest_mock import MockerFixture
+
+from llm_tool_cli.skills import load_skill_text
+from llm_tool_cli.skills.errors import SkillUnreadable
+
+
+@pytest.fixture
+def skill_package(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> str:
+    package = "skill_fixture_package"
+    initializer = tmp_path / "__init__.py"
+    initializer.write_text("", encoding="utf-8")
+    spec = importlib.util.spec_from_file_location(package, initializer)
+    assert spec is not None
+    monkeypatch.setitem(sys.modules, package, importlib.util.module_from_spec(spec))
+    (tmp_path / "fixtures").mkdir()
+    return package
+
+
+class TestLoadSkillText:
+    @pytest.mark.parametrize(
+        ("document", "content"),
+        [("usage", "# Usage\n"), ("workflows", ""), ("custom_document", "  Привет 🌍\n\n")],
+    )
+    def test_reads_selected_utf8_resource(
+        self, tmp_path: Path, skill_package: str, document: str, content: str
+    ) -> None:
+        (tmp_path / "fixtures" / f"{document}.md").write_text(content, encoding="utf-8")
+
+        assert load_skill_text(skill_package, document).unwrap() == content
+
+    @pytest.mark.parametrize("content", [None, b"\xff"])
+    def test_read_failure_is_returned(self, tmp_path: Path, skill_package: str, content: bytes | None) -> None:
+        if content is not None:
+            (tmp_path / "fixtures" / "usage.md").write_bytes(content)
+
+        errors = load_skill_text(skill_package, "usage").unwrap_err()
+
+        assert len(errors) == 1
+        failure = errors[0]
+        assert isinstance(failure, SkillUnreadable)
+        assert failure.code == "skill_unreadable"
+        assert failure.document == "usage"
+        assert isinstance(failure.cause, FileNotFoundError if content is None else UnicodeDecodeError)
+        assert failure.reason == str(failure.cause)
+        assert "cause" not in failure.as_record()
+
+    def test_unexpected_failure_propagates(self, mocker: MockerFixture) -> None:
+        mocker.patch(
+            "llm_tool_cli.skills.fixtures.importlib.resources.files", side_effect=RuntimeError("broken loader")
+        )
+
+        with pytest.raises(RuntimeError, match="broken loader"):
+            load_skill_text("skill_fixture_package", "usage")