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

llm_tool_cli/config/tests/test_project.py

@@ -0,0 +1,257 @@
+from pathlib import Path
+from typing import Literal
+
+import pydantic
+import pytest
+from pytest_mock import MockerFixture
+
+from llm_tool_cli.config import errors
+from llm_tool_cli.config.project import (
+    ProjectConfig,
+    _load_project_config,
+    initialize_project,
+    load_project,
+    project_config,
+)
+from llm_tool_cli.config.runtime import RuntimeConfig, runtime_config
+from llm_tool_cli.config.tests.fixtures import project_static_settings
+from llm_tool_cli.core.entities import BaseEntity
+from llm_tool_cli.core.errors import EnvironmentErrors
+from llm_tool_cli.core.result import Err, Ok, UnwrapError
+from llm_tool_cli.core.settings import ConfigFilename, StaticConfig, ToolLabel, static_config
+from llm_tool_cli.paths import PathInput, ProjectConfigPath
+from llm_tool_cli.paths.errors import InvalidProjectPath
+from llm_tool_cli.protocol import Protocol
+
+__all__ = ["project_static_settings"]
+
+pytestmark = pytest.mark.usefixtures("project_static_settings")
+
+
+class ApplicationConfig(BaseEntity):
+    version: Literal[1] = 1
+    count: int = 0
+
+
+class TestProjectConfig:
+    def test_project_dir__derives_from_configuration_path(self) -> None:
+        config = ProjectConfig(config_path=ProjectConfigPath(Path("/project/custom.toml")))
+
+        assert config.project_dir == Path("/project")
+
+    @pytest.mark.parametrize("path", ["~/config.toml", "relative.toml"])
+    def test_validate_config_path__rejects_unresolved_inputs(self, path: str) -> None:
+        with pytest.raises(pydantic.ValidationError):
+            ProjectConfig(config_path=ProjectConfigPath(Path(path)))
+
+
+class TestLoadProject:
+    def test_discovers_nearest_configuration_and_restores_scope(self, tmp_path: Path) -> None:
+        (tmp_path / "tool.toml").write_text("count = 1", encoding="utf-8")
+        project = tmp_path / "project"
+        nested = project / "nested"
+        nested.mkdir(parents=True)
+        path = project / "tool.toml"
+        path.write_text("count = 2", encoding="utf-8")
+
+        scope = load_project(ApplicationConfig, cwd=PathInput(nested))
+        assert not project_config.is_set()
+        with scope as result:
+            assert result.unwrap().count == 2
+            assert project_config.get().config_path == path
+            assert project_config.get().project_dir == project
+            assert not runtime_config.is_set()
+        assert not project_config.is_set()
+
+    def test_uses_static_filename(self, tmp_path: Path) -> None:
+        (tmp_path / "custom.toml").write_text("count = 3", encoding="utf-8")
+        settings = StaticConfig(tool_label=ToolLabel("TEST"), config_filename=ConfigFilename("custom.toml"))
+        with static_config.scope(settings), load_project(ApplicationConfig, cwd=PathInput(tmp_path)) as result:
+            assert result.unwrap().count == 3
+            assert project_config.get().config_path == tmp_path / "custom.toml"
+
+    @pytest.mark.parametrize("explicit", [False, True])
+    def test_rejects_config_symlink_without_binding_project(self, tmp_path: Path, explicit: bool) -> None:
+        target_dir = tmp_path / "target"
+        target_dir.mkdir()
+        target = target_dir / "actual.toml"
+        target.write_text("count = 4", encoding="utf-8")
+        link = tmp_path / "tool.toml"
+        link.symlink_to(target)
+        path = ProjectConfigPath(Path("tool.toml")) if explicit else None
+
+        with load_project(ApplicationConfig, cwd=PathInput(tmp_path), path=path) as result:
+            assert result.unwrap_err() == [InvalidProjectPath(path=str(link))]
+            assert not project_config.is_set()
+
+    @pytest.mark.parametrize("explicit", [False, True])
+    def test_directory_alias_selects_resolved_project(self, tmp_path: Path, explicit: bool) -> None:
+        root = tmp_path / "project"
+        root.mkdir()
+        (root / "tool.toml").write_text("count = 4", encoding="utf-8")
+        alias = tmp_path / "alias"
+        alias.symlink_to(root, target_is_directory=True)
+
+        with load_project(
+            ApplicationConfig,
+            cwd=PathInput(alias),
+            path=ProjectConfigPath(alias / "tool.toml") if explicit else None,
+        ) as result:
+            assert result.unwrap().count == 4
+            assert project_config.get().config_path == root / "tool.toml"
+            assert project_config.get().project_dir == root
+
+    def test_missing_explicit_path_does_not_fall_back(self, tmp_path: Path) -> None:
+        (tmp_path / "tool.toml").write_text("", encoding="utf-8")
+        with load_project(
+            ApplicationConfig, cwd=PathInput(tmp_path), path=ProjectConfigPath(Path("missing.toml"))
+        ) as result:
+            error = result.unwrap_err()[0]
+            assert isinstance(error, errors.Unreadable)
+            assert error.path == tmp_path / "missing.toml"
+            assert not project_config.is_set()
+
+    def test_missing_discovered_configuration(self, mocker: MockerFixture, tmp_path: Path) -> None:
+        mocker.patch("llm_tool_cli.config.files.find_config", return_value=Ok(None))
+        with load_project(ApplicationConfig, cwd=PathInput(tmp_path)) as result:
+            error = result.unwrap_err()[0]
+            assert isinstance(error, errors.NotFound)
+            assert error.path == tmp_path
+            assert "tool.toml" in error.reason
+            assert not project_config.is_set()
+
+    def test_missing_static_filename_is_internal_misuse(self, tmp_path: Path) -> None:
+        with static_config.scope(StaticConfig(tool_label=ToolLabel("TEST"))):
+            with pytest.raises(errors.ConfigFilenameNotSet):
+                with load_project(ApplicationConfig, cwd=PathInput(tmp_path)):
+                    pytest.fail("Project setup must reject missing application metadata.")
+        assert not project_config.is_set()
+
+
+class TestInitializeProject:
+    @pytest.mark.parametrize("explicit", [False, True])
+    def test_creates_validates_and_scopes_without_discovery(
+        self, mocker: MockerFixture, tmp_path: Path, explicit: bool
+    ) -> None:
+        package = tmp_path / "package"
+        (package / "fixtures").mkdir(parents=True)
+        text = "version = 1\ncount = 5\n"
+        (package / "fixtures/starter.toml").write_text(text, encoding="utf-8")
+        mocker.patch("llm_tool_cli.config.files.importlib.resources.files", return_value=package)
+        (tmp_path / "tool.toml").write_text("count = 9", encoding="utf-8")
+        child = tmp_path / "child"
+        child.mkdir()
+        path = ProjectConfigPath(Path("custom.toml")) if explicit else None
+        created = child / ("custom.toml" if explicit else "tool.toml")
+
+        scope = initialize_project(
+            ApplicationConfig, package="test", template="starter.toml", cwd=PathInput(child), path=path
+        )
+        assert not created.exists()
+        with scope as result:
+            assert result.unwrap().count == 5
+            assert created.read_text(encoding="utf-8") == text
+            assert project_config.get().config_path == created
+            assert project_config.get().project_dir == child
+        assert not project_config.is_set()
+
+    @pytest.mark.parametrize(
+        "text, error_type", [("version =", errors.InvalidToml), ("version = 2", errors.ValidationFailed)]
+    )
+    def test_invalid_starter_remains_on_disk_without_binding(
+        self, mocker: MockerFixture, tmp_path: Path, text: str, error_type: type[errors.EnvironmentError]
+    ) -> None:
+        package = tmp_path / "package"
+        (package / "fixtures").mkdir(parents=True)
+        (package / "fixtures/starter.toml").write_text(text, encoding="utf-8")
+        mocker.patch("llm_tool_cli.config.files.importlib.resources.files", return_value=package)
+        with initialize_project(
+            ApplicationConfig, package="test", template="starter.toml", cwd=PathInput(tmp_path)
+        ) as result:
+            assert isinstance(result.unwrap_err()[0], error_type)
+            assert (tmp_path / "tool.toml").read_text(encoding="utf-8") == text
+            assert not project_config.is_set()
+
+    def test_creation_failure_skips_loading_and_preserves_binding(self, mocker: MockerFixture, tmp_path: Path) -> None:
+        failure = errors.Unwritable(path=tmp_path / "tool.toml", reason="denied")
+        mocker.patch("llm_tool_cli.config.project.initialize_config", return_value=Err([failure]))
+        loading = mocker.patch("llm_tool_cli.config.project.load_config")
+        previous = ProjectConfig(config_path=ProjectConfigPath(tmp_path / "active.toml"))
+        with project_config.scope(previous):
+            with initialize_project(
+                ApplicationConfig, package="test", template="starter.toml", cwd=PathInput(tmp_path)
+            ) as result:
+                assert result.unwrap_err() == [failure]
+                assert project_config.get() == previous
+            assert project_config.get() == previous
+        loading.assert_not_called()
+
+    def test_missing_static_filename_is_internal_misuse(self, tmp_path: Path) -> None:
+        with static_config.scope(StaticConfig(tool_label=ToolLabel("TEST"))):
+            with pytest.raises(errors.ConfigFilenameNotSet):
+                with initialize_project(
+                    ApplicationConfig, package="test", template="starter.toml", cwd=PathInput(tmp_path)
+                ):
+                    pytest.fail("Project setup must reject missing application metadata.")
+        assert not list(tmp_path.iterdir())
+
+
+class TestLoadProjectConfig:
+    @pytest.mark.parametrize("failure", [None, RuntimeError("body failed"), UnwrapError(error=[])])
+    def test_restores_previous_binding_after_success_and_body_failures(
+        self, tmp_path: Path, failure: Exception | None
+    ) -> None:
+        path = ProjectConfigPath(tmp_path / "tool.toml")
+        path.write_text("count = 7", encoding="utf-8")
+        previous = ProjectConfig(config_path=ProjectConfigPath(tmp_path / "outer.toml"))
+        with project_config.scope(previous), runtime_config.scope(RuntimeConfig(protocol=Protocol.llm)):
+            try:
+                with _load_project_config(Ok(path), ApplicationConfig) as result:
+                    assert result.unwrap().count == 7
+                    assert project_config.get().config_path == path
+                    assert runtime_config.get().protocol == Protocol.llm
+                    if failure is not None:
+                        raise failure
+            except Exception as caught:
+                assert caught == failure
+            else:
+                assert failure is None
+            assert project_config.get() == previous
+
+    def test_selection_failure_is_preserved_without_loading(self, mocker: MockerFixture, tmp_path: Path) -> None:
+        failures: EnvironmentErrors = [
+            errors.DiscoveryFailed(path=tmp_path, reason="denied"),
+            errors.NotFound(path=tmp_path, reason="missing"),
+        ]
+        loading = mocker.patch("llm_tool_cli.config.project.load_config")
+        with _load_project_config(Err(failures), ApplicationConfig) as result:
+            assert result.unwrap_err() == failures
+            assert not project_config.is_set()
+        loading.assert_not_called()
+
+    @pytest.mark.parametrize(
+        "content, error_type",
+        [
+            (b"count =", errors.InvalidToml),
+            (b"\xff", errors.InvalidEncoding),
+            (b"version = 2", errors.ValidationFailed),
+        ],
+    )
+    def test_loading_failure_preserves_previous_project(
+        self, tmp_path: Path, content: bytes, error_type: type[errors.EnvironmentError]
+    ) -> None:
+        path = ProjectConfigPath(tmp_path / "tool.toml")
+        path.write_bytes(content)
+        previous = ProjectConfig(config_path=ProjectConfigPath(tmp_path / "active.toml"))
+        with project_config.scope(previous), _load_project_config(Ok(path), ApplicationConfig) as result:
+            assert isinstance(result.unwrap_err()[0], error_type)
+            assert project_config.get() == previous
+
+    def test_unexpected_loading_failure_propagates(self, mocker: MockerFixture, tmp_path: Path) -> None:
+        failure = RuntimeError("unexpected schema defect")
+        mocker.patch("llm_tool_cli.config.project.load_config", side_effect=failure)
+        with pytest.raises(RuntimeError) as caught:
+            with _load_project_config(Ok(ProjectConfigPath(tmp_path / "tool.toml")), ApplicationConfig):
+                pytest.fail("Loading must fail before entering the project.")
+        assert caught.value == failure
+        assert not project_config.is_set()

llm_tool_cli/core/__init__.py

@@ -0,0 +1 @@
+"""Shared infrastructure; ``core.errors`` defines the public exception base."""

llm_tool_cli/core/context.py

@@ -0,0 +1,50 @@
+"""Independent typed bindings with initialization and temporary scopes."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+from llm_tool_cli.core.errors import ContextValueAlreadySet, ContextValueNotSet
+
+
+class ContextValue[T]:
+    """Access one value in the current execution context.
+
+    The name is diagnostic only. Each instance owns an independent binding;
+    binding an object does not copy it or manage its resources.
+    """
+
+    __slots__ = ("_variable",)
+
+    def __init__(self, name: str) -> None:
+        self._variable: ContextVar[T] = ContextVar(name)
+
+    def get(self) -> T:
+        """Return the bound value, raising an internal exception when unset."""
+        try:
+            return self._variable.get()
+        except LookupError as error:
+            raise ContextValueNotSet(details={"name": self._variable.name}) from error
+
+    def is_set(self) -> bool:
+        """Report whether a value is bound, including an explicit None."""
+        try:
+            self._variable.get()
+        except LookupError:
+            return False
+        return True
+
+    def initialize(self, value: T) -> None:
+        """Install a value once in the current context, rejecting reassignment."""
+        if self.is_set():
+            raise ContextValueAlreadySet(details={"name": self._variable.name})
+        self._variable.set(value)
+
+    @contextmanager
+    def scope(self, value: T) -> Iterator[None]:
+        """Temporarily bind a value and restore the previous binding on exit."""
+        token = self._variable.set(value)
+        try:
+            yield
+        finally:
+            self._variable.reset(token)

llm_tool_cli/core/entities.py

@@ -0,0 +1,35 @@
+from enum import IntEnum
+from typing import Self
+
+import pydantic
+
+
+class ExitCode(IntEnum):
+    success = 0
+    invalid_arguments = 1
+    configuration_error = 2
+    environment_error = 3
+
+
+class BaseEntity(pydantic.BaseModel):
+    """Shared validation, copying, and JSON serialization for structured values."""
+
+    model_config = pydantic.ConfigDict(
+        str_strip_whitespace=True,
+        validate_default=True,
+        extra="forbid",
+        frozen=True,
+        validate_assignment=True,
+        from_attributes=False,
+    )
+
+    def replace(self, **changes: object) -> Self:
+        """Return a deep copy with trusted changes applied without validation."""
+        return self.model_copy(update=changes, deep=True)
+
+    def to_json(self) -> str:
+        return self.model_dump_json(indent=2)
+
+    @classmethod
+    def from_json(cls, json_data: str) -> Self:
+        return cls.model_validate_json(json_data)

llm_tool_cli/core/errors.py

@@ -0,0 +1,97 @@
+from collections.abc import Mapping
+from typing import ClassVar, Self
+
+import pydantic
+
+from llm_tool_cli.core.entities import BaseEntity, ExitCode
+
+
+class InternalError(Exception):
+    """Base for internal and technical exceptions with structured context.
+
+    Details are copied shallowly and may contain arbitrary debugging context or
+    technical propagation payloads. They are not environment-error diagnostics.
+    """
+
+    message_template: ClassVar[str | None] = None
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        details: Mapping[str, object] | None = None,
+    ) -> None:
+        self.details: dict[str, object] = dict(details) if details is not None else {}
+        if message is None and self.message_template is not None:
+            message = self.message_template.format(**self.details)
+        super().__init__(type(self).__name__ if message is None else message)
+
+    @property
+    def message(self) -> str:
+        return super().__str__()
+
+
+class ContextValueNotSet(InternalError):
+    message_template = "Context value {name!r} is not set."
+
+
+class ContextValueAlreadySet(InternalError):
+    message_template = "Context value {name!r} is already set."
+
+
+class ToolLabelAlreadyInitialized(InternalError):
+    message_template = "Tool label is already initialized as {current!r}; cannot initialize it as {requested!r}."
+
+
+class EnvironmentError(BaseEntity):
+    """An expected operational failure returned as data.
+
+    Subclasses declare typed context fields. Messages and corrective guidance may
+    reference those fields using ``{error.field}``.
+    """
+
+    cli_exit_code: ClassVar[ExitCode] = ExitCode.environment_error
+    code: str
+    message: str
+    ways_to_fix: list[str] = pydantic.Field(default_factory=list)
+    _cause: Exception | None = pydantic.PrivateAttr(default=None)
+
+    @property
+    def cause(self) -> Exception | None:
+        return self._cause
+
+    def with_cause(self, cause: Exception) -> Self:
+        """Attach the original failure at its translation boundary."""
+        self._cause = cause
+        return self
+
+    def format_message(self) -> str:
+        return self.message.format(error=self)
+
+    def as_record(self) -> dict[str, object]:
+        """Serialize typed context with the stable diagnostic record fields."""
+        context = self.model_dump(mode="json", exclude={"code", "message", "ways_to_fix"})
+        return {
+            **context,
+            "type": "error",
+            "code": self.code,
+            "message": self.format_message(),
+        }
+
+
+EnvironmentErrors = list[EnvironmentError]
+
+
+def exit_code_for_errors(errors: EnvironmentErrors) -> ExitCode:
+    """Return the highest declared exit code, or success for an empty list."""
+    return max((error.cli_exit_code for error in errors), default=ExitCode.success)
+
+
+class EnvironmentErrorsProxy(InternalError):
+    """Carry environment errors through callbacks that cannot return results."""
+
+    def __init__(self, errors: EnvironmentErrors) -> None:
+        super().__init__(
+            "This is a technical exception to pass an environment error up the call stack.",
+            details={"errors": errors},
+        )

llm_tool_cli/core/result.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import functools
+from typing import Callable, Generic, Never, ParamSpec, TypeVar, cast
+
+from llm_tool_cli.core.errors import EnvironmentError, EnvironmentErrors, InternalError
+
+T = TypeVar("T", covariant=True)
+U = TypeVar("U")
+TValue = TypeVar("TValue")
+P = ParamSpec("P")
+
+
+class UnwrapError(InternalError):
+    def __init__(self, error: EnvironmentErrors) -> None:
+        super().__init__("Called unwrap on an Err value.", details={"error": error})
+
+    @property
+    def errors(self) -> EnvironmentErrors:
+        """Return the original error list, or re-raise this exception if malformed.
+
+        The payload lives only in ``details["error"]``. Lists, including empty
+        lists, are returned unchanged after verifying every item is an
+        environment error. Other payloads are internal failures, not recoverable
+        diagnostics.
+        """
+        errors = self.details.get("error")
+        if isinstance(errors, list) and all(isinstance(error, EnvironmentError) for error in errors):
+            return errors
+        raise self
+
+
+class UnwrapErrError(InternalError):
+    def __init__(self, value: object) -> None:
+        super().__init__("Called unwrap_err on an Ok value.", details={"value": value})
+
+
+class Result(Generic[T]):
+    __slots__ = ("_is_ok", "_value")
+
+    def __init__(self, is_ok: bool, value: T | EnvironmentErrors) -> None:
+        self._is_ok = is_ok
+        self._value = value
+
+    def is_ok(self) -> bool:
+        return self._is_ok
+
+    def is_err(self, error_type: type[EnvironmentError] | None = None) -> bool:
+        """Check for failure, optionally requiring all environment errors to match.
+
+        A requested type also matches subclasses. Successes, empty lists, and
+        errors outside that type do not match. Without a type, every failed
+        result matches, including one with an empty error list.
+        """
+        if self._is_ok:
+            return False
+        if error_type is None:
+            return True
+        errors = cast(EnvironmentErrors, self._value)
+        return bool(errors) and all(isinstance(error, error_type) for error in errors)
+
+    def ok(self) -> T | None:
+        if self._is_ok:
+            return cast(T, self._value)
+        return None
+
+    def err(self) -> EnvironmentErrors | None:
+        if not self._is_ok:
+            return cast(EnvironmentErrors, self._value)
+        return None
+
+    def unwrap(self) -> T:
+        if self._is_ok:
+            return cast(T, self._value)
+
+        raise UnwrapError(error=self.unwrap_err())
+
+    def unwrap_err(self) -> EnvironmentErrors:
+        if not self._is_ok:
+            return cast(EnvironmentErrors, self._value)
+
+        raise UnwrapErrError(value=self.unwrap())
+
+    def unwrap_or(self, default: U) -> T | U:
+        if self._is_ok:
+            return cast(T, self._value)
+        return default
+
+    def map(self, func: Callable[[T], U]) -> Result[U]:
+        if self._is_ok:
+            return Result(True, func(cast(T, self._value)))
+        return Result(False, cast(EnvironmentErrors, self._value))
+
+    def map_err(self, func: Callable[[EnvironmentErrors], EnvironmentErrors]) -> Result[T]:
+        if not self._is_ok:
+            return Result(False, func(cast(EnvironmentErrors, self._value)))
+        return Result(True, cast(T, self._value))
+
+
+def Ok(value: TValue) -> Result[TValue]:
+    return Result(True, value)
+
+
+def Err(error: EnvironmentErrors) -> Result[Never]:
+    return Result(False, error)
+
+
+def unwrap_to_error(func: Callable[P, Result[T]]) -> Callable[P, Result[T]]:
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> Result[T]:
+
+        try:
+            return func(*args, **kwargs)
+        except UnwrapError as e:
+            return Err(e.errors)
+
+    return wrapper

llm_tool_cli/core/settings.py

@@ -0,0 +1,37 @@
+"""Application settings bound before command-line parsing in the active context."""
+
+from typing import NewType
+
+import pydantic
+
+from llm_tool_cli.core.context import ContextValue
+from llm_tool_cli.core.entities import BaseEntity
+from llm_tool_cli.core.errors import ContextValueAlreadySet, ToolLabelAlreadyInitialized
+
+ToolLabel = NewType("ToolLabel", str)
+ConfigFilename = NewType("ConfigFilename", str)
+
+
+class StaticConfig(BaseEntity):
+    """Application identity available before command-line parsing."""
+
+    model_config = pydantic.ConfigDict(str_strip_whitespace=False)
+
+    tool_label: ToolLabel
+    config_filename: ConfigFilename | None = None
+
+
+static_config = ContextValue[StaticConfig]("static_config")
+
+
+def initialize(*, label: ToolLabel, config_filename: ConfigFilename | None = None) -> None:
+    value = StaticConfig(tool_label=label, config_filename=config_filename)
+    if static_config.is_set():
+        current = static_config.get()
+        if current.tool_label != label:
+            raise ToolLabelAlreadyInitialized(details={"current": current.tool_label, "requested": label})
+        if current != value:
+            raise ContextValueAlreadySet(details={"name": "static_config"})
+        return
+
+    static_config.initialize(value)

llm_tool_cli/core/tests/fixtures.py

@@ -0,0 +1,13 @@
+import pytest
+from pytest_mock import MockerFixture
+
+from llm_tool_cli.core import settings
+from llm_tool_cli.core.context import ContextValue
+
+
+@pytest.fixture
+def isolated_settings(mocker: MockerFixture) -> None:
+    """Start with unset static settings and restore the previous state after the test."""
+    # Approved test-only reset: replace the binding because production initialization
+    # cannot clear it. Keep real initialization and access; pytest-mock restores it.
+    mocker.patch.object(settings, "static_config", ContextValue[settings.StaticConfig]("static_config"))