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

llm_tool_cli/cli/tests/test_options.py

@@ -0,0 +1,125 @@
+from pathlib import Path
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from llm_tool_cli.cli.options import ConfigOption, ProtocolOption
+from llm_tool_cli.core import settings
+from llm_tool_cli.core.tests.fixtures import isolated_settings
+from llm_tool_cli.paths import ProjectConfigPath
+from llm_tool_cli.protocol import Protocol
+
+__all__ = ["isolated_settings"]
+
+
+@pytest.fixture
+def protocol_app(isolated_settings: None) -> typer.Typer:
+    settings.initialize(label=settings.ToolLabel("TEST"))
+    app = typer.Typer()
+
+    @app.callback()
+    def initialize(protocol: ProtocolOption = None) -> None:
+        typer.echo("unspecified" if protocol is None else protocol.value)
+
+    @app.command()
+    def show() -> None:
+        pass
+
+    return app
+
+
+class TestParseConfigPath:
+    @pytest.mark.parametrize(
+        ("value", "expected"),
+        [
+            (None, None),
+            ("", "."),
+            (".", "."),
+            ("missing/config.toml", "missing/config.toml"),
+            ("/absolute/config.toml", "/absolute/config.toml"),
+            ("relative/../config.toml", "relative/../config.toml"),
+            ("~/config.toml", "~/config.toml"),
+            ("  café 日本語.toml  ", "  café 日本語.toml  "),
+        ],
+    )
+    def test_parses_without_filesystem_validation(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, value: str | None, expected: str | None
+    ) -> None:
+        monkeypatch.chdir(tmp_path)
+        app = typer.Typer()
+        received: list[ProjectConfigPath | None] = []
+
+        @app.callback()
+        def initialize(config: ConfigOption = None) -> None:
+            received.append(config)
+
+        @app.command()
+        def show() -> None:
+            pass
+
+        arguments = [] if value is None else ["--config", value]
+        result = CliRunner().invoke(app, [*arguments, "show"])
+
+        assert result.exit_code == 0
+        assert not result.output
+        assert received == [None if expected is None else ProjectConfigPath(Path(expected))]
+
+
+class TestParseProtocol:
+    @pytest.mark.parametrize("option", ["-p", "--protocol"])
+    @pytest.mark.parametrize("protocol", list(Protocol))
+    def test_parses_supported_values(self, protocol_app: typer.Typer, option: str, protocol: Protocol) -> None:
+        result = CliRunner().invoke(protocol_app, [option, protocol.value, "show"])
+
+        assert result.exit_code == 0
+        assert result.stdout == f"{protocol.value}\n"
+        assert not result.stderr
+
+    def test_leaves_missing_protocol_unspecified(self, protocol_app: typer.Typer) -> None:
+        result = CliRunner().invoke(protocol_app, ["show"])
+
+        assert result.exit_code == 0
+        assert result.stdout == "unspecified\n"
+        assert not result.stderr
+
+    @pytest.mark.parametrize("value", ["invalid", "HUMAN", " llm", "llm ", "", "{protocol}", "{"])
+    @pytest.mark.parametrize("prefix", [[], ["-p", "automation"]])
+    def test_invalid_value_uses_llm_cell_before_command_execution(
+        self, protocol_app: typer.Typer, value: str, prefix: list[str]
+    ) -> None:
+        result = CliRunner().invoke(protocol_app, [*prefix, "--protocol", value, "show"])
+
+        assert result.exit_code == 1
+        assert not result.stderr
+        assert result.stdout.startswith("--TEST-CELL ")
+        assert result.stdout.count(" BEGIN--\n") == 1
+        assert result.stdout.count(" END--\n") == 1
+        assert "kind=error\n" in result.stdout
+        assert "code=invalid_arguments\n" in result.stdout
+        assert "type=error\n" in result.stdout
+        assert "\nreason=" in result.stdout
+        assert f"`{value}`" in result.stdout
+        for protocol in Protocol:
+            assert protocol.value in result.stdout
+
+    @pytest.mark.parametrize("option", ["-p", "--protocol"])
+    def test_missing_value_remains_a_framework_error(self, protocol_app: typer.Typer, option: str) -> None:
+        result = CliRunner().invoke(protocol_app, [option])
+
+        assert result.exit_code == 2
+        assert not result.stdout
+        assert option in result.stderr
+        assert "--TEST-CELL " not in result.stderr
+
+    def test_help_describes_shared_option(self, protocol_app: typer.Typer) -> None:
+        result = CliRunner().invoke(protocol_app, ["--help"])
+
+        assert result.exit_code == 0
+        assert not result.stderr
+        assert "--protocol" in result.stdout
+        assert "-p" in result.stdout
+        assert "PROTOCOL" in result.stdout
+        for protocol in Protocol:
+            assert protocol.value in result.stdout
+        assert "skill" in result.stdout

llm_tool_cli/config/__init__.py

@@ -0,0 +1,33 @@
+"""Configuration file mechanics and reusable schema fields.
+
+The exported operations, ``config.fields``, and ``config.errors`` are public interfaces.
+Applications declare their default filename in static settings and own template
+resources, schemas, workspace construction, and presentation of failures.
+"""
+
+from llm_tool_cli.config.files import (
+    create_config,
+    create_config_from_template,
+    find_config,
+    initialize_config,
+    load_config,
+    locate_config,
+    read_toml,
+    resolve_config_path,
+    resolve_init_config_path,
+)
+from llm_tool_cli.config.project import initialize_project, load_project
+
+__all__ = [
+    "create_config",
+    "create_config_from_template",
+    "find_config",
+    "initialize_config",
+    "initialize_project",
+    "load_config",
+    "load_project",
+    "locate_config",
+    "read_toml",
+    "resolve_config_path",
+    "resolve_init_config_path",
+]

llm_tool_cli/config/errors.py

@@ -0,0 +1,92 @@
+"""Public configuration failures.
+
+Concrete ``code`` values are stable compatibility identifiers. Callers may inspect
+the returned values without parsing messages. ``path`` identifies the
+failed operation's filesystem input; ``reason`` contains the original reason.
+The producing operation preserves any underlying low-level exception as ``cause``.
+"""
+
+from pathlib import Path
+from typing import ClassVar
+
+from llm_tool_cli.core import errors as core_errors
+from llm_tool_cli.core.entities import ExitCode
+
+
+class InternalError(core_errors.InternalError):
+    """Misuse of configuration setup interfaces."""
+
+
+class ConfigFilenameNotSet(InternalError):
+    message_template = "Project setup requires a configuration filename in static settings."
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    """Classification and filesystem context for configuration failures."""
+
+    cli_exit_code: ClassVar[ExitCode] = ExitCode.configuration_error
+    path: Path
+    reason: str
+    message: str = "{error.path}: {error.reason}"
+
+
+class PathResolutionFailed(EnvironmentError):
+    """An explicit path could not be resolved."""
+
+    code: str = "config_path_resolution_failed"
+
+
+class DiscoveryFailed(EnvironmentError):
+    """The search directory or a candidate could not be inspected."""
+
+    code: str = "config_discovery_failed"
+
+
+class NotFound(EnvironmentError):
+    """No configuration file was found in the search directory or its parents."""
+
+    code: str = "config_not_found"
+
+
+class Unreadable(EnvironmentError):
+    """A configuration file could not be opened or read."""
+
+    code: str = "config_unreadable"
+
+
+class InvalidEncoding(EnvironmentError):
+    """A configuration file does not contain valid UTF-8."""
+
+    code: str = "config_invalid_encoding"
+
+
+class InvalidToml(EnvironmentError):
+    """A configuration file does not contain valid TOML."""
+
+    code: str = "config_invalid_toml"
+
+
+class ValidationFailed(EnvironmentError):
+    """Parsed configuration does not satisfy the supplied model."""
+
+    code: str = "config_validation_failed"
+
+
+class AlreadyExists(EnvironmentError):
+    """The starter target already exists and was left untouched."""
+
+    code: str = "config_already_exists"
+
+
+class TemplateUnreadable(EnvironmentError):
+    """A packaged starter could not be read as UTF-8 for the target path."""
+
+    code: str = "config_template_unreadable"
+    message: str = "could not read configuration template `{error.template}`: {error.reason}"
+    template: str
+
+
+class Unwritable(EnvironmentError):
+    """Starter text could not be encoded or written to the target."""
+
+    code: str = "config_unwritable"

llm_tool_cli/config/fields.py

@@ -0,0 +1,39 @@
+"""Reusable fields for application-owned configuration schemas."""
+
+from typing import Annotated
+
+import pydantic
+
+from llm_tool_cli.paths import RelativeProjectPath
+
+
+def _validate_config_version(value: object, handler: pydantic.ValidatorFunctionWrapHandler) -> object:
+    """Require an integer and explain failures of the application's version constraint."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"Configuration version must be an integer; received {value!r}.")
+
+    try:
+        return handler(value)
+    except pydantic.ValidationError as error:
+        failures = error.errors()
+        if len(failures) != 1 or failures[0]["type"] != "literal_error":
+            raise
+        supported = failures[0]["ctx"]["expected"]
+        raise ValueError(f"Unsupported configuration version {value}; supported version: {supported}.") from error
+
+
+type ConfigVersion[Version: int] = Annotated[Version, pydantic.WrapValidator(_validate_config_version)]
+
+
+def validate_relative_project_path(path: RelativeProjectPath) -> RelativeProjectPath:
+    """Pydantic validator for project-relative paths without parent references."""
+    if path.is_absolute():
+        raise ValueError("Project paths must be relative to the project root.")
+
+    if any(part == ".." for part in path.parts):
+        raise ValueError("Project paths must not contain parent-directory references.")
+
+    return path
+
+
+type SessionDir = Annotated[RelativeProjectPath, pydantic.AfterValidator(validate_relative_project_path)]

llm_tool_cli/config/files.py

@@ -0,0 +1,175 @@
+import importlib.resources
+from pathlib import Path
+
+import pydantic
+import tomli
+
+from llm_tool_cli.config import errors
+from llm_tool_cli.core.result import Err, Ok, Result, unwrap_to_error
+from llm_tool_cli.paths import PathInput, ProjectConfigPath, ProjectRootPath, resolve_inside_project
+
+
+@unwrap_to_error
+def find_config(filename: str, start_dir: Path) -> Result[ProjectConfigPath | None]:
+    """Find the nearest file from the resolved start directory through its root.
+
+    Matching directories are skipped. No match returns ``Ok(None)``; filesystem
+    failures reported by pathlib return ``Err([DiscoveryFailed(...)])``.
+    Shared path validation rejects matching symlinks, including broken links,
+    before checking file existence. No matching file is read.
+    """
+    candidate = start_dir
+    try:
+        current = start_dir.resolve()
+        for directory in (current, *current.parents):
+            candidate = directory / filename
+            resolve_inside_project(candidate, ProjectRootPath(directory)).unwrap()
+            if candidate.is_file():
+                return Ok(ProjectConfigPath(candidate))
+    except (OSError, RuntimeError) as exc:
+        return Err([errors.DiscoveryFailed(path=candidate, reason=str(exc)).with_cause(exc)])
+    return Ok(None)
+
+
+@unwrap_to_error
+def resolve_config_path(path: Path, cwd: Path) -> Result[ProjectConfigPath]:
+    """Expand an explicit path's home marker, then resolve it against cwd.
+
+    Resolve the containing directory as the project root, then apply shared
+    containment and symlink validation to the file. Neither needs to exist.
+    Do not search for a config or interpret application path syntax. Home
+    expansion and directory resolution failures return ``PathResolutionFailed``;
+    shared path diagnostics propagate unchanged.
+    """
+    candidate = path
+    try:
+        expanded = path.expanduser()
+        candidate = expanded if expanded.is_absolute() else cwd / expanded
+        root = ProjectRootPath(candidate.parent.resolve())
+        return Ok(ProjectConfigPath(resolve_inside_project(root / candidate.name, root).unwrap()))
+    except (OSError, RuntimeError) as exc:
+        return Err([errors.PathResolutionFailed(path=candidate, reason=str(exc)).with_cause(exc)])
+
+
+def resolve_init_config_path(
+    filename: str, *, path: ProjectConfigPath | None = None, cwd: PathInput
+) -> Result[ProjectConfigPath]:
+    """Select and resolve a configuration target without upward discovery.
+
+    An explicit path takes precedence over the filename under ``cwd``.
+    Reuse ``resolve_config_path`` for home expansion, shared path validation, and
+    unchanged failure propagation. No file is read or created, and neither the
+    target nor its parent is required to exist.
+    """
+    return resolve_config_path(path if path is not None else Path(filename), cwd)
+
+
+@unwrap_to_error
+def locate_config(filename: str, *, path: Path | None = None, cwd: Path) -> Result[ProjectConfigPath]:
+    """Select an explicit configuration path or discover the nearest file.
+
+    Explicit paths use ``resolve_config_path`` without falling back to discovery
+    or requiring an existing target. Otherwise, search with ``find_config`` and
+    return ``Err([NotFound(...)])`` if no match exists. Its ``path`` is the supplied search
+    directory and its ``reason`` identifies the filename and search scope.
+    Resolution and discovery failures propagate unchanged. No file is read.
+    """
+    if path is not None:
+        return resolve_config_path(path, cwd)
+
+    config_path = find_config(filename, cwd).unwrap()
+    if config_path is None:
+        return Err([errors.NotFound(path=cwd, reason=f"{filename} was not found in this directory or its parents")])
+    return Ok(config_path)
+
+
+def read_toml(path: Path) -> Result[dict[str, object]]:
+    """Read UTF-8 TOML 1.1 data without applying an application schema.
+
+    Filesystem, UTF-8, and TOML failures return ``Unreadable``, ``InvalidEncoding``,
+    and ``InvalidToml`` in error lists respectively. The supplied path is used without discovery
+    or normalization. An empty document returns ``Ok({})``.
+    """
+    try:
+        with path.open("rb") as stream:
+            return Ok(tomli.load(stream))
+    except OSError as exc:
+        return Err([errors.Unreadable(path=path, reason=str(exc)).with_cause(exc)])
+    except UnicodeDecodeError as exc:
+        return Err([errors.InvalidEncoding(path=path, reason=str(exc)).with_cause(exc)])
+    except tomli.TOMLDecodeError as exc:
+        return Err([errors.InvalidToml(path=path, reason=str(exc)).with_cause(exc)])
+
+
+@unwrap_to_error
+def load_config[T: pydantic.BaseModel](path: Path, config_class: type[T]) -> Result[T]:
+    """Read a TOML file and validate it using the caller's Pydantic model.
+
+    Use the supplied path unchanged, without discovery or normalization.
+    The model owns its schema, defaults, and validation rules. Read failures
+    propagate as documented by ``read_toml``; Pydantic validation failures return
+    ``Err([ValidationFailed(...)])`` with diagnostic text and the original exception cause.
+    Unexpected model failures propagate unchanged.
+    """
+    raw = read_toml(path).unwrap()
+    try:
+        return Ok(config_class.model_validate(raw))
+    except pydantic.ValidationError as exc:
+        return Err([errors.ValidationFailed(path=path, reason=str(exc)).with_cause(exc)])
+
+
+def create_config(path: ProjectConfigPath, text: str) -> Result[None]:
+    """Create a starter from verbatim UTF-8 text, without overwriting any target.
+
+    The parent must already exist. No discovery, path normalization, directory
+    creation, or TOML validation occurs. Exclusive creation returns ``AlreadyExists``
+    for an existing target, including a symlink. Encoding and other filesystem
+    failures return ``Unwritable``. Failures are carried in error lists; success is
+    ``Ok(None)``. Failed writes may leave a partial new file.
+    """
+    try:
+        data = text.encode("utf-8")
+        with path.open("xb") as stream:
+            stream.write(data)
+    except FileExistsError as exc:
+        return Err([errors.AlreadyExists(path=path, reason=str(exc)).with_cause(exc)])
+    except (OSError, UnicodeEncodeError) as exc:
+        return Err([errors.Unwritable(path=path, reason=str(exc)).with_cause(exc)])
+    return Ok(None)
+
+
+def create_config_from_template(path: ProjectConfigPath, *, package: str, template: str) -> Result[None]:
+    """Read a packaged UTF-8 starter and create it at the supplied target path.
+
+    Read ``fixtures/<template>`` from ``package`` before attempting creation.
+    Filesystem and decoding failures return ``Err([TemplateUnreadable(...)])``
+    with the target path, template name, reason, and private original cause.
+    Unexpected resource errors propagate. Otherwise, pass the loaded text to
+    ``create_config`` and return its result unchanged, including write failures.
+    No target selection, path resolution, or configuration validation occurs.
+    """
+    try:
+        text = importlib.resources.files(package).joinpath("fixtures", template).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return Err([errors.TemplateUnreadable(path=path, template=template, reason=str(exc)).with_cause(exc)])
+    return create_config(path, text)
+
+
+@unwrap_to_error
+def initialize_config(
+    filename: str,
+    *,
+    package: str,
+    template: str,
+    cwd: PathInput,
+    path: ProjectConfigPath | None = None,
+) -> Result[ProjectConfigPath]:
+    """Resolve an initialization target and create the selected packaged starter.
+
+    Return the resolved path only after successful creation. Resolution, template
+    reading, and creation failures propagate unchanged, stopping the sequence.
+    No configuration loading, schema validation, or workspace construction occurs.
+    """
+    selected_path = resolve_init_config_path(filename, path=path, cwd=cwd).unwrap()
+    create_config_from_template(selected_path, package=package, template=template).unwrap()
+    return Ok(selected_path)

llm_tool_cli/config/project.py

@@ -0,0 +1,87 @@
+"""Project preparation and scoped settings, independent of CLI frameworks."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import pydantic
+
+from llm_tool_cli.config import errors
+from llm_tool_cli.config.files import initialize_config, load_config, locate_config
+from llm_tool_cli.core import settings
+from llm_tool_cli.core.context import ContextValue
+from llm_tool_cli.core.entities import BaseEntity
+from llm_tool_cli.core.result import Err, Result
+from llm_tool_cli.paths import PathInput, ProjectConfigPath, ProjectRootPath
+
+
+class ProjectConfig(BaseEntity):
+    config_path: ProjectConfigPath
+
+    @pydantic.field_validator("config_path")
+    @classmethod
+    def validate_config_path(cls, value: ProjectConfigPath) -> ProjectConfigPath:
+        if not value.is_absolute():
+            raise ValueError("The active configuration path must be absolute.")
+        return value
+
+    @property
+    def project_dir(self) -> ProjectRootPath:
+        return ProjectRootPath(self.config_path.parent)
+
+
+project_config = ContextValue[ProjectConfig]("project_config")
+
+
+@contextmanager
+def load_project[T: pydantic.BaseModel](
+    config_class: type[T], *, cwd: PathInput, path: ProjectConfigPath | None = None
+) -> Iterator[Result[T]]:
+    """Select and validate a configuration, binding its project for the scope.
+
+    Failures yield an error result without replacing the active project. The
+    caller owns the scope's lifetime and application-specific configuration use.
+    """
+    filename = settings.static_config.get().config_filename
+    if filename is None:
+        raise errors.ConfigFilenameNotSet()
+    selected = locate_config(filename, path=path, cwd=cwd)
+    with _load_project_config(selected, config_class) as result:
+        yield result
+
+
+@contextmanager
+def initialize_project[T: pydantic.BaseModel](
+    config_class: type[T],
+    *,
+    package: str,
+    template: str,
+    cwd: PathInput,
+    path: ProjectConfigPath | None = None,
+) -> Iterator[Result[T]]:
+    """Create and validate a starter, binding its project for the scope.
+
+    Creation never searches parent directories or overwrites an existing file.
+    A created file remains on disk if subsequent validation fails.
+    """
+    filename = settings.static_config.get().config_filename
+    if filename is None:
+        raise errors.ConfigFilenameNotSet()
+    selected = initialize_config(filename, package=package, template=template, cwd=cwd, path=path)
+    with _load_project_config(selected, config_class) as result:
+        yield result
+
+
+@contextmanager
+def _load_project_config[T: pydantic.BaseModel](
+    selected: Result[ProjectConfigPath], config_class: type[T]
+) -> Iterator[Result[T]]:
+    if selected.is_err():
+        yield Err(selected.unwrap_err())
+        return
+    path = selected.unwrap()
+    loaded = load_config(path, config_class)
+    if loaded.is_err():
+        yield loaded
+        return
+    with project_config.scope(ProjectConfig(config_path=path)):
+        yield loaded

llm_tool_cli/config/runtime.py

@@ -0,0 +1,14 @@
+"""Effective runtime settings, independent of their input source."""
+
+from llm_tool_cli.core.context import ContextValue
+from llm_tool_cli.core.entities import BaseEntity
+from llm_tool_cli.protocol import Protocol
+
+
+class RuntimeConfig(BaseEntity):
+    """Complete settings for an execution, including commands without a project."""
+
+    protocol: Protocol
+
+
+runtime_config = ContextValue[RuntimeConfig]("runtime_config")

llm_tool_cli/config/tests/fixtures.py

@@ -0,0 +1,34 @@
+"""Scoped application, runtime, and project settings for consumer tests."""
+
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+
+from llm_tool_cli.config.project import ProjectConfig, project_config
+from llm_tool_cli.config.runtime import RuntimeConfig, runtime_config
+from llm_tool_cli.core.settings import ConfigFilename, StaticConfig, ToolLabel, static_config
+from llm_tool_cli.paths import ProjectConfigPath
+from llm_tool_cli.protocol import Protocol
+
+
+@pytest.fixture
+def project_static_settings() -> Iterator[StaticConfig]:
+    value = StaticConfig(tool_label=ToolLabel("TEST"), config_filename=ConfigFilename("tool.toml"))
+    with static_config.scope(value):
+        yield value
+
+
+@pytest.fixture
+def runtime_settings() -> Iterator[RuntimeConfig]:
+    value = RuntimeConfig(protocol=Protocol.human)
+    with runtime_config.scope(value):
+        yield value
+
+
+@pytest.fixture
+def project_settings(tmp_path: Path) -> Iterator[ProjectConfig]:
+    """Bind a project rooted at the test directory without filesystem loading."""
+    value = ProjectConfig(config_path=ProjectConfigPath(tmp_path / "config.toml"))
+    with project_config.scope(value):
+        yield value