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

llm_tool_cli/output/tests/test_emitter.py

@@ -0,0 +1,406 @@
+import io
+import json
+import sys
+
+import pytest
+from pytest_mock import MockerFixture
+
+from llm_tool_cli.config.runtime import RuntimeConfig, runtime_config
+from llm_tool_cli.config.tests.fixtures import project_static_settings, runtime_settings
+from llm_tool_cli.core.errors import ContextValueNotSet, EnvironmentError
+from llm_tool_cli.core.result import Err, Ok, Result
+from llm_tool_cli.core.settings import StaticConfig, ToolLabel, static_config
+from llm_tool_cli.core.tests.fixtures import isolated_settings
+from llm_tool_cli.output import StreamOutputEmitter
+from llm_tool_cli.protocol import Protocol
+from llm_tool_cli.protocol.journal import JournalRecord
+from llm_tool_cli.protocol.logic_cells import ContentCell, EnvironmentErrorCell
+from llm_tool_cli.protocol.logic_cells.base import LogicCell
+from llm_tool_cli.protocol.logic_cells.journal import JournalCell
+from llm_tool_cli.protocol.logic_cells.warning import WarningCell
+from llm_tool_cli.protocol.output_cells import HumanOutputCell
+from llm_tool_cli.protocol.output_cells.base import OutputCell, RenderContext
+
+__all__ = ["isolated_settings", "project_static_settings", "runtime_settings"]
+pytestmark = pytest.mark.usefixtures("project_static_settings", "runtime_settings")
+
+
+class RecordingProcessor:
+    def __init__(self, result: Result[None] = Ok(None)) -> None:
+        self.records: list[JournalRecord] = []
+        self.result = result
+
+    def process(self, record: JournalRecord) -> Result[None]:
+        self.records.append(record)
+        return self.result
+
+
+class PositionedOutputCell(OutputCell):
+    def render(self, context: RenderContext) -> bytes:
+        return f"{context.tool_label} {context.index}/{context.total}: {self.content}\n".encode()
+
+
+class PositionedLogicCell(LogicCell):
+    items: tuple[str, ...]
+
+    def to_journal_record(self) -> JournalRecord:
+        return JournalRecord(message="\n".join(self.items))
+
+    def render_human(self) -> list[OutputCell]:
+        return [PositionedOutputCell.build_markdown(kind="item", content=text) for text in self.items]
+
+    def render_llm(self) -> list[OutputCell]:
+        return []
+
+    def render_automation(self) -> list[OutputCell]:
+        return []
+
+
+class TestStreamOutputEmitter:
+    @pytest.mark.parametrize(
+        "protocol, actor", [(Protocol.human, "human"), (Protocol.llm, "agent"), (Protocol.automation, "automation")]
+    )
+    def test_journal__uses_default_factory_and_protocol_actor(self, protocol: Protocol, actor: str) -> None:
+        stream = io.StringIO()
+        processor = RecordingProcessor()
+        emitter = StreamOutputEmitter(stream=stream, journal_processor=processor)
+        with runtime_config.scope(RuntimeConfig(protocol=protocol)):
+            emitter.journal("starting").unwrap()
+        assert len(processor.records) == 1
+        assert processor.records[0].message == "starting"
+        assert processor.records[0].actor_id == actor
+        assert "starting" in stream.getvalue()
+
+    @pytest.mark.parametrize("actor", [None, "worker"])
+    def test_journal__custom_factory_receives_explicit_actor_at_each_call(self, actor: str | None) -> None:
+        calls: list[tuple[str, str | None]] = []
+
+        def factory(*, message: str, actor_id: str | None) -> JournalCell:
+            calls.append((message, actor_id))
+            return JournalCell(message=f"{len(calls)}: {message}", actor_id=actor_id)
+
+        processor = RecordingProcessor()
+        emitter = StreamOutputEmitter(stream=io.StringIO(), journal_factory=factory, journal_processor=processor)
+        emitter.journal("first", actor_id=actor).unwrap()
+        emitter.journal("second", actor_id=actor).unwrap()
+        assert calls == [("first", actor), ("second", actor)]
+        assert [record.message for record in processor.records] == ["1: first", "2: second"]
+
+    def test_emit__direct_cells_do_not_invoke_journal_factory(self) -> None:
+        def factory(*, message: str, actor_id: str | None) -> JournalCell:
+            raise AssertionError("factory must not run")
+
+        emitter = StreamOutputEmitter(stream=io.StringIO(), journal_factory=factory)
+        emitter.emit(
+            [EnvironmentErrorCell(error=EnvironmentError(code="failed", message="failure"), is_journal=True)]
+        ).unwrap()
+
+    def test_journal__processor_failure_propagates(self) -> None:
+        failure = EnvironmentError(code="forward_failed", message="delivery failed")
+        stream = io.StringIO()
+        emitter = StreamOutputEmitter(stream=stream, journal_processor=RecordingProcessor(Err([failure])))
+        assert emitter.journal("event").unwrap_err() == [failure]
+        assert not stream.getvalue()
+
+    @pytest.mark.parametrize("errors", [[], [EnvironmentError(code="custom_failure", message="unavailable")]])
+    def test_emit__processor_failure_disables_forwarding_but_preserves_console_routing(
+        self, errors: list[EnvironmentError]
+    ) -> None:
+        processor = RecordingProcessor(Err(errors))
+        stream = io.StringIO()
+        emitter = StreamOutputEmitter(stream=stream, journal_processor=processor)
+        with runtime_config.scope(RuntimeConfig(protocol=Protocol.automation)):
+            assert emitter.journal("failed event").unwrap_err() == errors
+            emitter.discard()
+            emitter.flush()
+            assert not stream.getvalue()
+
+            emitter.journal("later event").unwrap()
+            emitter.emit(
+                [
+                    ContentCell(kind="result", media_type="text/plain", content="result"),
+                    WarningCell(message="warning", is_journal=True),
+                    JournalCell(message="last event"),
+                ]
+            ).unwrap()
+            assert [json.loads(line)["message"] for line in stream.getvalue().splitlines()] == [
+                "later event",
+                "last event",
+            ]
+            emitter.flush()
+
+        records = [json.loads(line) for line in stream.getvalue().splitlines()]
+        assert len(records) == 4
+        assert records[2]["content"] == "result"
+        assert records[3]["message"] == "warning"
+        assert [record.message for record in processor.records] == ["failed event"]
+
+    def test_emit__processor_failure_is_local_to_emitter(self) -> None:
+        error = EnvironmentError(code="custom_failure", message="unavailable")
+        processor = RecordingProcessor(Err([error]))
+        first = StreamOutputEmitter(stream=io.StringIO(), journal_processor=processor)
+        second = StreamOutputEmitter(stream=io.StringIO(), journal_processor=processor)
+        assert first.journal("first").unwrap_err() == [error]
+        assert second.journal("second").unwrap_err() == [error]
+        assert [record.message for record in processor.records] == ["first", "second"]
+
+    @pytest.mark.parametrize("journal", [False, True])
+    def test_render__override_retains_buffering_and_stream_delivery(
+        self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], journal: bool
+    ) -> None:
+        class CustomOutputEmitter(StreamOutputEmitter):
+            def _render(self, cells: list[LogicCell]) -> str:
+                return f"Batch of {len(cells)}\n"
+
+        stream = io.StringIO()
+        flush = mocker.spy(stream, "flush")
+        emitter = CustomOutputEmitter(stream=stream)
+        emitter.emit([JournalCell(message="result", is_journal=journal)]).unwrap()
+        assert stream.getvalue() == ("Batch of 1\n" if journal else "")
+        emitter.flush()
+        emitter.flush()
+        assert stream.getvalue() == "Batch of 1\n"
+        flush.assert_called_once()
+        assert not stream.closed
+        assert capsys.readouterr() == ("", "")
+
+    @pytest.mark.parametrize("protocol", list(Protocol))
+    def test_emit__custom_stream_receives_journals_then_results_and_warnings(
+        self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], protocol: Protocol
+    ) -> None:
+        stream = io.StringIO()
+        flush = mocker.spy(stream, "flush")
+        processor = RecordingProcessor()
+        emitter = StreamOutputEmitter(stream=stream, journal_processor=processor)
+        event = JournalCell(message="progress")
+        with runtime_config.scope(RuntimeConfig(protocol=protocol)):
+            emitter.emit(
+                [
+                    WarningCell(message="warning"),
+                    ContentCell(kind="result", media_type="text/plain", content="completed"),
+                    event,
+                ]
+            ).unwrap()
+            assert "progress" in stream.getvalue()
+            assert "completed" not in stream.getvalue()
+            assert "warning" not in stream.getvalue()
+            assert processor.records == [event.to_journal_record()]
+            flush.assert_called_once()
+
+            emitter.flush()
+            delivered = stream.getvalue()
+            assert delivered.index("progress") < delivered.index("completed") < delivered.index("warning")
+            assert flush.call_count == 2
+            emitter.flush()
+            assert stream.getvalue() == delivered
+            assert flush.call_count == 2
+        assert not stream.closed
+        assert capsys.readouterr() == ("", "")
+
+    def test_emit__default_uses_current_stdout_at_delivery(self, mocker: MockerFixture) -> None:
+        first = io.StringIO()
+        second = io.StringIO()
+        mocker.patch.object(sys, "stdout", first)
+        emitter = StreamOutputEmitter()
+        emitter.emit([ContentCell(kind="result", media_type="text/plain", content="completed")]).unwrap()
+        mocker.patch.object(sys, "stdout", second)
+        emitter.emit([JournalCell(message="progress")]).unwrap()
+        emitter.flush()
+        assert not first.getvalue()
+        assert second.getvalue().index("progress") < second.getvalue().index("completed")
+
+    @pytest.mark.parametrize("operation", ["write", "flush"])
+    def test_flush__stream_failure_propagates_without_retry(self, mocker: MockerFixture, operation: str) -> None:
+        stream = io.StringIO()
+        failing_operation = mocker.patch.object(stream, operation, side_effect=OSError("delivery failed"))
+        emitter = StreamOutputEmitter(stream=stream)
+        emitter.emit([ContentCell(kind="result"), WarningCell(message="warning")]).unwrap()
+        with pytest.raises(OSError, match="delivery failed"):
+            emitter.flush()
+        emitter.flush()
+        failing_operation.assert_called_once()
+        assert not stream.closed
+
+    def test_emit__buffers_results_and_warnings_but_delivers_journals(
+        self, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        processor = RecordingProcessor()
+        emitter = StreamOutputEmitter(journal_processor=processor)
+        first = ContentCell(kind="result", media_type="text/plain", content="first")
+        event = JournalCell(message="progress")
+        last = first.replace(content="last")
+        with runtime_config.scope(RuntimeConfig(protocol=Protocol.automation)):
+            emitter.emit(
+                [WarningCell(message="warning one"), first, event, last, WarningCell(message="warning two")]
+            ).unwrap()
+            immediate = [json.loads(line) for line in capsys.readouterr().out.splitlines()]
+            assert [record["message"] for record in immediate] == ["progress"]
+            assert processor.records == [event.to_journal_record()]
+            emitter.flush()
+            records = [json.loads(line) for line in capsys.readouterr().out.splitlines()]
+            assert [record["content"] for record in records[:2]] == ["first", "last"]
+            assert [record["message"] for record in records[2:]] == ["warning one", "warning two"]
+            emitter.flush()
+            assert not capsys.readouterr().out
+            assert processor.records == [event.to_journal_record()]
+
+    @pytest.mark.parametrize("journal", [False, True])
+    @pytest.mark.parametrize("warning", [False, True])
+    def test_emit__flags_override_subclass_defaults(
+        self, capsys: pytest.CaptureFixture[str], journal: bool, warning: bool
+    ) -> None:
+        processor = RecordingProcessor()
+        emitter = StreamOutputEmitter(journal_processor=processor)
+        cell = JournalCell(message="event", is_journal=journal, is_warning=warning)
+        emitter.emit([cell]).unwrap()
+        assert processor.records == ([cell.to_journal_record()] if journal else [])
+        assert bool(capsys.readouterr().out) == (journal and not warning)
+        emitter.flush()
+        assert bool(capsys.readouterr().out) == (not journal or warning)
+
+    def test_emit__journals_semantic_record_and_preserves_console_projection(
+        self, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        cell = EnvironmentErrorCell(
+            error=EnvironmentError(code="failed", message="failure", ways_to_fix=["Retry."]), is_journal=True
+        )
+        processor = RecordingProcessor()
+        emitter = StreamOutputEmitter(journal_processor=processor)
+        emitter.emit([cell]).unwrap()
+        assert len(processor.records) == 1
+        assert processor.records[0].message == "failure"
+        assert processor.records[0].attributes == {"type": "error", "code": "failed"}
+        assert "failure\nWay to fix: Retry." in capsys.readouterr().out
+
+    def test_emit__failure_stops_delivery_and_never_replays_processor(
+        self, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        error = EnvironmentError(code="forward_failed", message="failed")
+        processor = RecordingProcessor(Err([error]))
+        emitter = StreamOutputEmitter(journal_processor=processor)
+        cell = JournalCell(message="failed event", is_warning=True)
+        assert emitter.emit([cell, WarningCell(message="unreached")]).unwrap_err() == [error]
+        emitter.flush()
+        assert not capsys.readouterr().out
+        assert processor.records == [cell.to_journal_record()]
+
+    @pytest.mark.parametrize(
+        ("items", "expected"),
+        [
+            ([("café", "second"), (), ("third",)], "  TOOL   0/3: café\n  TOOL   1/3: second\n  TOOL   2/3: third\n"),
+            ([("only",)], "  TOOL   0/1: only\n"),
+            ([()], ""),
+            ([], ""),
+        ],
+    )
+    def test_flush__preserves_projection_order_and_supplies_complete_batch_context(
+        self, capsys: pytest.CaptureFixture[str], items: list[tuple[str, ...]], expected: str
+    ) -> None:
+        emitter = StreamOutputEmitter()
+        emitter.emit([PositionedLogicCell(items=values) for values in items]).unwrap()
+        with static_config.scope(StaticConfig(tool_label=ToolLabel("  TOOL  "))):
+            emitter.flush()
+        assert capsys.readouterr() == (expected, "")
+
+    def test_flush__selects_protocol_at_delivery(self, capsys: pytest.CaptureFixture[str]) -> None:
+        emitter = StreamOutputEmitter()
+        emitter.emit([PositionedLogicCell(items=("hidden",))]).unwrap()
+        with runtime_config.scope(RuntimeConfig(protocol=Protocol.llm)):
+            emitter.flush()
+        assert capsys.readouterr() == ("", "")
+
+    @pytest.mark.parametrize("protocol", [Protocol.human, Protocol.llm])
+    @pytest.mark.parametrize("custom_stream", [False, True])
+    def test_flush__preserves_unicode_and_protocol_specific_text(
+        self, capsys: pytest.CaptureFixture[str], protocol: Protocol, custom_stream: bool
+    ) -> None:
+        stream = io.StringIO()
+        emitter = StreamOutputEmitter(stream=stream if custom_stream else None)
+        emitter.emit([ContentCell(kind="message", media_type="text/plain", content="café 日本語")]).unwrap()
+        with (
+            runtime_config.scope(RuntimeConfig(protocol=protocol)),
+            static_config.scope(StaticConfig(tool_label=ToolLabel("  TOOL  "))),
+        ):
+            emitter.flush()
+        captured = capsys.readouterr()
+        text = stream.getvalue() if custom_stream else captured.out
+        assert (captured.out if custom_stream else stream.getvalue()) == ""
+        assert captured.err == ""
+        assert "café 日本語" in text
+        if protocol == Protocol.human:
+            assert text == "café 日本語\n\n"
+        else:
+            assert text.startswith("--  TOOL  -CELL ")
+            assert text.endswith(" END--\n")
+
+    @pytest.mark.parametrize("label", ["FIRST", "SECOND"])
+    def test_flush__automation_preserves_cells_and_ignores_label(self, label: str) -> None:
+        stream = io.StringIO()
+        emitter = StreamOutputEmitter(stream=stream)
+        cell = ContentCell(kind="message", media_type="text/plain", content="café 日本語", meta={"type": "message"})
+        original = cell.model_dump()
+        with (
+            runtime_config.scope(RuntimeConfig(protocol=Protocol.automation)),
+            static_config.scope(StaticConfig(tool_label=ToolLabel(label))),
+        ):
+            emitter.emit([cell]).unwrap()
+            emitter.flush()
+            emitter.emit([cell]).unwrap()
+            emitter.flush()
+        first, second = [json.loads(line) for line in stream.getvalue().splitlines()]
+        assert first.pop("id") != second.pop("id")
+        assert first == second == {"type": "message", "content": "café 日本語"}
+        assert cell.model_dump() == original
+        assert stream.getvalue().endswith("\n")
+
+    def test_flush__preserves_error_order_and_guidance(self, capsys: pytest.CaptureFixture[str]) -> None:
+        emitter = StreamOutputEmitter()
+        emitter.emit(
+            [
+                EnvironmentErrorCell(error=EnvironmentError(code="first", message="First", ways_to_fix=["Retry."])),
+                EnvironmentErrorCell(error=EnvironmentError(code="second", message="Second")),
+            ]
+        ).unwrap()
+        with runtime_config.scope(RuntimeConfig(protocol=Protocol.automation)):
+            emitter.flush()
+        records = [json.loads(line) for line in capsys.readouterr().out.splitlines()]
+        assert records[0].pop("id") != records[1].pop("id")
+        assert records == [
+            {"type": "error", "code": "first", "content": "First\nWay to fix: Retry."},
+            {"type": "error", "code": "second", "content": "Second"},
+        ]
+
+    def test_flush__missing_initialization_writes_nothing(
+        self, isolated_settings: None, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        emitter = StreamOutputEmitter()
+        emitter.emit([ContentCell(kind="message")]).unwrap()
+        with pytest.raises(ContextValueNotSet) as caught:
+            emitter.flush()
+        assert caught.value.details == {"name": "static_config"}
+        assert capsys.readouterr() == ("", "")
+
+    @pytest.mark.parametrize(
+        ("last_output", "exception_type"),
+        [(ValueError("bad render"), ValueError), (b"\xff", UnicodeDecodeError)],
+    )
+    def test_flush__render_or_decode_failure_writes_nothing(
+        self,
+        mocker: MockerFixture,
+        capsys: pytest.CaptureFixture[str],
+        last_output: bytes | Exception,
+        exception_type: type[Exception],
+    ) -> None:
+        emitter = StreamOutputEmitter()
+        emitter.emit([ContentCell(kind="first"), ContentCell(kind="last")]).unwrap()
+        mocker.patch.object(HumanOutputCell, "render", side_effect=[b"first", last_output])
+        with pytest.raises(exception_type):
+            emitter.flush()
+        assert not capsys.readouterr().out
+        emitter.flush()
+        assert not capsys.readouterr().out
+
+    def test_emit__flushes_live_journal_stream(self, mocker: MockerFixture) -> None:
+        flush = mocker.spy(sys.stdout, "flush")
+        StreamOutputEmitter().emit([JournalCell(message="live")]).unwrap()
+        flush.assert_called_once()

llm_tool_cli/output/tests/test_journal.py

@@ -0,0 +1,141 @@
+import datetime
+import json
+import sys
+from pathlib import Path
+
+import pydantic
+import pytest
+from pytest_mock import MockerFixture
+
+from llm_tool_cli.core.errors import EnvironmentError
+from llm_tool_cli.output.errors import JournalCommandConfigInvalid, JournalCommandFailed
+from llm_tool_cli.output.journal import CommandJournalProcessor, JournalConfig, NoopJournalProcessor
+from llm_tool_cli.protocol.journal import JournalRecord
+from llm_tool_cli.protocol.logic_cells import EnvironmentErrorCell
+from llm_tool_cli.protocol.logic_cells.journal import JournalCell
+
+
+class TestNoopJournalProcessor:
+    def test_process__accepts_record_without_output(self, capsys: pytest.CaptureFixture[str]) -> None:
+        assert NoopJournalProcessor().process(JournalRecord(message="event")).is_ok()
+        assert capsys.readouterr() == ("", "")
+
+
+class TestCommandJournalProcessor:
+    def test_process__preserves_literal_and_multiline_arguments(self, tmp_path: Path) -> None:
+        target = tmp_path / "arguments.json"
+        timestamp = datetime.datetime.now(datetime.UTC)
+        cell = JournalCell(message="  first\nsecond\rthird  ", timestamp=timestamp)
+        processor = CommandJournalProcessor(
+            [
+                sys.executable,
+                "-c",
+                "import json, pathlib, sys; pathlib.Path(sys.argv[1]).write_text(json.dumps(sys.argv[2:]))",
+                str(target),
+                "{message}",
+                "{timestamp}",
+                "{actor_id}",
+                "literal:{message}",
+                "{message",
+            ]
+        )
+        processor.process(cell.to_journal_record()).unwrap()
+        assert json.loads(target.read_text()) == [
+            "first\nsecond\rthird",
+            timestamp.isoformat(),
+            "",
+            "literal:{message}",
+            "{message",
+        ]
+
+    def test_process__supports_error_cell_fields(self, tmp_path: Path) -> None:
+        target = tmp_path / "code.txt"
+        processor = CommandJournalProcessor(
+            [
+                sys.executable,
+                "-c",
+                "import pathlib, sys; pathlib.Path(sys.argv[1]).write_text(sys.argv[2])",
+                str(target),
+                "{code}",
+            ]
+        )
+        processor.process(
+            EnvironmentErrorCell(error=EnvironmentError(code="failed", message="failure")).to_journal_record()
+        ).unwrap()
+        assert target.read_text() == "failed"
+
+    def test_process__empty_command_does_not_execute(self, mocker: MockerFixture) -> None:
+        run = mocker.patch("llm_tool_cli.output.journal.subprocess.run")
+        failures = CommandJournalProcessor([]).process(JournalRecord(message="test")).unwrap_err()
+        assert isinstance(failures[0], JournalCommandConfigInvalid)
+        run.assert_not_called()
+
+    def test_process__missing_executable_is_expected_error(self, tmp_path: Path) -> None:
+        command = [str(tmp_path / "missing")]
+        error = CommandJournalProcessor(command).process(JournalRecord(message="test")).unwrap_err()[0]
+        assert isinstance(error, JournalCommandFailed)
+        assert error.command == command
+        assert error.returncode is None
+
+    @pytest.mark.parametrize("stderr", ["", "explanation"])
+    def test_process__nonzero_exit_preserves_context(self, stderr: str) -> None:
+        command = [sys.executable, "-c", "import sys; sys.stderr.write(sys.argv[1]); sys.exit(7)", stderr]
+        error = CommandJournalProcessor(command).process(JournalRecord(message="test")).unwrap_err()[0]
+        assert isinstance(error, JournalCommandFailed)
+        assert error.returncode == 7
+        assert error.command == command
+        assert error.details == ("exit code 7; stderr: explanation" if stderr else "exit code 7")
+
+    @pytest.mark.parametrize(
+        "attributes, expected",
+        [
+            ({}, ""),
+            ({"task_id": None}, ""),
+            ({"task_id": "T-1"}, "T-1"),
+            ({"task_id": 0}, "0"),
+            ({"task_id": False}, "False"),
+        ],
+    )
+    def test_process__substitutes_record_fields(
+        self, tmp_path: Path, attributes: dict[str, pydantic.JsonValue], expected: str
+    ) -> None:
+        target = tmp_path / "argument.txt"
+        processor = CommandJournalProcessor(
+            [
+                sys.executable,
+                "-c",
+                "import pathlib, sys; pathlib.Path(sys.argv[1]).write_text(sys.argv[2])",
+                str(target),
+                "{task_id}",
+            ]
+        )
+        processor.process(JournalRecord(message="event", attributes=attributes)).unwrap()
+        assert target.read_text() == expected
+
+
+class TestJournalConfig:
+    @pytest.mark.parametrize("command", [[], ["tool", 1]])
+    def test_validation__rejects_invalid_command(self, command: list[object]) -> None:
+        with pytest.raises(pydantic.ValidationError):
+            JournalConfig.model_validate({"cmd": command})
+
+    def test_processor__defaults_to_noop(self) -> None:
+        assert JournalConfig().processor().process(JournalRecord(message="event")).is_ok()
+
+    def test_processor__uses_record_fields_without_declarations(self, tmp_path: Path) -> None:
+        target = tmp_path / "arguments.json"
+        config = JournalConfig(
+            cmd=[
+                sys.executable,
+                "-c",
+                "import json, pathlib, sys; pathlib.Path(sys.argv[1]).write_text(json.dumps(sys.argv[2:]))",
+                str(target),
+                "{missing}",
+                "{message}",
+                "{custom_field}",
+                "{attributes}",
+                "after",
+            ]
+        )
+        config.processor().process(JournalRecord(message="event", attributes={"custom_field": "value"})).unwrap()
+        assert json.loads(target.read_text()) == ["", "event", "value", "", "after"]

llm_tool_cli/paths/__init__.py

@@ -0,0 +1,51 @@
+"""Lexical identifiers, filesystem resolution, and project-root containment.
+
+Lexical normalization is independent of the filesystem. Application-specific
+syntax belongs to callers. ``paths.errors`` exposes public path failures.
+"""
+
+from llm_tool_cli.paths.enumeration import enumerate_files
+from llm_tool_cli.paths.filesystem import (
+    PathInput,
+    ProjectConfigPath,
+    ProjectRootPath,
+    RelativeProjectPath,
+    ResolvedProjectPath,
+    normalize_path,
+    project_path_id_from_filesystem,
+    project_path_id_from_resolved,
+    resolve_inside_project,
+    resolve_project_path,
+    resolve_project_root,
+    resolve_root_anchored_path,
+)
+from llm_tool_cli.paths.globs import FileGlobPattern, glob_capture_names, match_glob
+from llm_tool_cli.paths.normalization import (
+    ProjectPathId,
+    is_project_path_id,
+    normalize_project_path_id,
+    project_path_parts,
+)
+
+__all__ = [
+    "FileGlobPattern",
+    "PathInput",
+    "ProjectConfigPath",
+    "ProjectPathId",
+    "ProjectRootPath",
+    "RelativeProjectPath",
+    "ResolvedProjectPath",
+    "enumerate_files",
+    "glob_capture_names",
+    "is_project_path_id",
+    "match_glob",
+    "normalize_path",
+    "normalize_project_path_id",
+    "project_path_id_from_filesystem",
+    "project_path_id_from_resolved",
+    "project_path_parts",
+    "resolve_inside_project",
+    "resolve_project_path",
+    "resolve_project_root",
+    "resolve_root_anchored_path",
+]

llm_tool_cli/paths/enumeration.py

@@ -0,0 +1,72 @@
+"""Deterministic project-file discovery without symlink traversal."""
+
+import stat
+from collections.abc import Iterator
+from pathlib import Path
+
+from llm_tool_cli.core.result import Err, Ok, Result, unwrap_to_error
+from llm_tool_cli.paths.errors import FilesUnreadable
+from llm_tool_cli.paths.filesystem import (
+    ResolvedProjectPath,
+    project_path_id_from_resolved,
+    resolve_project_root,
+)
+from llm_tool_cli.paths.globs import FileGlobPattern, _compile_glob, _pattern_parts
+from llm_tool_cli.paths.normalization import ProjectPathId
+
+
+def _glob_files(path: Path, parts: tuple[str, ...]) -> Iterator[Path]:  # noqa: CCR001
+    try:
+        mode = path.lstat().st_mode
+    except (FileNotFoundError, NotADirectoryError):
+        return
+
+    if not parts:
+        if stat.S_ISREG(mode):
+            yield path
+        return
+    if not stat.S_ISDIR(mode):
+        return
+
+    segment, *remaining = parts
+    compiled, recursive = _compile_glob(FileGlobPattern(segment)).unwrap()
+    if recursive:
+        compiled, _ = _compile_glob(FileGlobPattern("/".join(parts))).unwrap()
+        for entry in _walk_files(path):
+            if compiled.fullmatch(entry.relative_to(path).as_posix()):
+                yield entry
+        return
+    for entry in sorted(path.iterdir()):
+        if compiled.fullmatch(entry.name):
+            yield from _glob_files(entry, tuple(remaining))
+
+
+def _walk_files(path: Path) -> Iterator[Path]:
+    """Walk regular files without following links, including broken links."""
+    try:
+        mode = path.lstat().st_mode
+    except (FileNotFoundError, NotADirectoryError):
+        return
+    if stat.S_ISREG(mode):
+        yield path
+    elif stat.S_ISDIR(mode):
+        for entry in sorted(path.iterdir()):
+            yield from _walk_files(entry)
+
+
+@unwrap_to_error
+def enumerate_files(root: Path, pattern: FileGlobPattern = FileGlobPattern("**/*")) -> Result[list[ProjectPathId]]:
+    """Find regular files matching a project-relative or root-anchored glob.
+
+    Support absolute and home-relative patterns through shared path resolution.
+    Include hidden entries, skip all discovered symlinks, and reject symlinks
+    in explicit pattern components. Return unique ids in path-component order.
+    """
+    project_root = resolve_project_root(root).unwrap()
+    parts = _pattern_parts(pattern, project_root).unwrap()
+    _compile_glob(FileGlobPattern("/".join(parts))).unwrap()
+    try:
+        paths = sorted(set(_glob_files(project_root, parts)))
+    except OSError as error:
+        return Err([FilesUnreadable(path=str(project_root), reason=str(error)).with_cause(error)])
+    return Ok([project_path_id_from_resolved(ResolvedProjectPath(path), project_root) for path in paths])