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

llm_tool_cli/cli/__init__.py

@@ -0,0 +1 @@
+"""Shared command-line options and policies."""

llm_tool_cli/cli/application.py

@@ -0,0 +1,31 @@
+import typer
+
+from llm_tool_cli.cli.options import ConfigOption, ProtocolOption
+
+
+def create_app(*, help: str) -> typer.Typer:
+    app = typer.Typer(
+        help=help,
+        add_completion=True,
+        context_settings={"help_option_names": ["-h", "--help"]},
+    )
+
+    @app.callback()
+    def initialize(
+        protocol: ProtocolOption = None,
+        config_path: ConfigOption = None,
+    ) -> None:
+        """Declare global options for command-specific runtime setup."""
+        # Typer uses this callback's signature to register --protocol/-p and
+        # --config on the root command group. Before calling it, the framework
+        # parses these options and stores them in the root context's params;
+        # this function does not need to store or forward the values itself.
+        # CommandContext reads them through context.find_root().params when the
+        # selected command starts. It can then choose the command's default
+        # protocol and bind RuntimeConfig, while leaving configuration path
+        # resolution and loading to commands that actually need a workspace.
+        # The callback therefore intentionally performs no initialization.
+        # Removing it would remove the global option declarations and could
+        # make a single-command application lose its command-group interface.
+
+    return app

llm_tool_cli/cli/commands/initialization.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+
+import pydantic
+import typer
+
+from llm_tool_cli.cli.context import command_context
+from llm_tool_cli.config import initialize_project
+from llm_tool_cli.config.project import project_config
+from llm_tool_cli.output import output
+from llm_tool_cli.paths import PathInput
+from llm_tool_cli.protocol.cell_shortcuts import configuration_created
+
+
+def register_init_command(
+    app: typer.Typer,
+    *,
+    config_class: type[pydantic.BaseModel],
+    package: str,
+    template: str,
+    help: str | None = None,
+) -> None:
+    """Register project initialization using the supplied schema and starter."""
+
+    @app.command("init", help=help)
+    def init(context: typer.Context) -> None:
+        with command_context(context) as command:
+            context.with_resource(
+                initialize_project(
+                    config_class,
+                    package=package,
+                    template=template,
+                    cwd=PathInput(Path.cwd()),
+                    path=command.config_input,
+                )
+            ).unwrap()
+            output.get().emit([configuration_created(project_config.get().config_path)]).unwrap()

llm_tool_cli/cli/commands/skills.py

@@ -0,0 +1,25 @@
+from enum import StrEnum
+from typing import Annotated
+
+import typer
+
+from llm_tool_cli.cli.context import command_context
+from llm_tool_cli.output import output
+from llm_tool_cli.protocol import cell_shortcuts
+from llm_tool_cli.skills import load_skill_text
+
+
+def register_skill_command(app: typer.Typer, *, package: str, documents: type[StrEnum]) -> None:
+    """Register packaged documentation using the consumer's enum, including usage."""
+
+    def skill(
+        context: typer.Context,
+        document: StrEnum = documents("usage"),
+    ) -> None:
+        with command_context(context):
+            content = load_skill_text(package=package, document=document.value).unwrap()
+            output.get().emit([cell_shortcuts.skill(document=document.value, content=content)]).unwrap()
+
+    # Typer reads the consumer's concrete enum for validation, help, and completion.
+    skill.__annotations__["document"] = Annotated[documents, typer.Argument()]
+    app.command("skill", help="Print built-in skill documentation.")(skill)

llm_tool_cli/cli/commands/tests/test_initialization.py

@@ -0,0 +1,130 @@
+import json
+from pathlib import Path
+
+import pydantic
+import pytest
+import typer
+from pytest_mock import MockerFixture
+from typer.testing import CliRunner
+
+from llm_tool_cli.cli.application import create_app
+from llm_tool_cli.cli.commands.initialization import register_init_command
+from llm_tool_cli.config.project import project_config
+from llm_tool_cli.config.runtime import runtime_config
+from llm_tool_cli.config.tests.fixtures import project_static_settings
+from llm_tool_cli.output import output
+from llm_tool_cli.protocol.tests.helpers import cell_payloads
+
+__all__ = ["project_static_settings"]
+
+pytestmark = pytest.mark.usefixtures("project_static_settings")
+
+
+class ApplicationConfig(pydantic.BaseModel):
+    count: int
+
+
+@pytest.fixture
+def init_app(tmp_path: Path, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch) -> typer.Typer:
+    fixtures = tmp_path / "fixtures"
+    fixtures.mkdir()
+    (fixtures / "starter.toml").write_text("count = 5\n", encoding="utf-8")
+    mocker.patch("llm_tool_cli.config.files.importlib.resources.files", return_value=tmp_path)
+    monkeypatch.chdir(tmp_path)
+    app = create_app(help="Initialize a test project.")
+    register_init_command(app, config_class=ApplicationConfig, package="test_resources", template="starter.toml")
+    return app
+
+
+class TestRegisterInitCommand:
+    @pytest.mark.parametrize("protocol", [None, "human", "llm", "automation"])
+    @pytest.mark.parametrize("explicit", [False, True])
+    def test_creates_validated_config_and_reports_selected_path(
+        self, init_app: typer.Typer, tmp_path: Path, protocol: str | None, explicit: bool
+    ) -> None:
+        options = [] if protocol is None else ["-p", protocol]
+        if explicit:
+            options.extend(["--config", "custom.toml"])
+        path = tmp_path / ("custom.toml" if explicit else "tool.toml")
+
+        result = CliRunner().invoke(init_app, [*options, "init"])
+
+        assert result.exit_code == 0, result.exception
+        assert path.read_text(encoding="utf-8") == "count = 5\n"
+        assert not result.stderr
+        if protocol == "automation":
+            assert cell_payloads([json.loads(result.stdout)]) == [
+                {"type": "operation_succeeded", "content": "Configuration created.", "path": str(path)}
+            ]
+        elif protocol == "llm":
+            assert "type=operation_succeeded\n" in result.stdout
+            assert f"path={path}\n" in result.stdout
+        else:
+            assert result.stdout == f"path: {path}\n\nConfiguration created.\n\n"
+        assert not project_config.is_set()
+        assert not runtime_config.is_set()
+        assert not output.is_set()
+
+    @pytest.mark.parametrize(
+        "text, code", [("count =", "config_invalid_toml"), ('count = "invalid"', "config_validation_failed")]
+    )
+    def test_invalid_starter_keeps_file_and_reports_failure_without_success(
+        self, init_app: typer.Typer, tmp_path: Path, text: str, code: str
+    ) -> None:
+        (tmp_path / "fixtures/starter.toml").write_text(text, encoding="utf-8")
+
+        result = CliRunner().invoke(init_app, ["-p", "automation", "init"])
+
+        assert result.exit_code == 2
+        record = json.loads(result.stdout)
+        assert record["type"] == "error"
+        assert record["code"] == code
+        assert (tmp_path / "tool.toml").read_text(encoding="utf-8") == text
+        assert not result.stderr
+        assert not project_config.is_set()
+
+    def test_existing_file_is_preserved(self, init_app: typer.Typer, tmp_path: Path) -> None:
+        path = tmp_path / "tool.toml"
+        path.write_text("count = 9", encoding="utf-8")
+
+        result = CliRunner().invoke(init_app, ["-p", "automation", "init"])
+
+        assert result.exit_code == 2
+        assert json.loads(result.stdout)["code"] == "config_already_exists"
+        assert path.read_text(encoding="utf-8") == "count = 9"
+        assert not result.stderr
+        assert not project_config.is_set()
+
+    def test_unexpected_failure_propagates(self, init_app: typer.Typer, mocker: MockerFixture) -> None:
+        failure = RuntimeError("Unexpected creation failure")
+        mocker.patch("llm_tool_cli.config.project.initialize_config", side_effect=failure)
+
+        result = CliRunner().invoke(init_app, ["init"])
+
+        assert result.exception == failure
+        assert not result.stdout
+        assert not result.stderr
+        assert not project_config.is_set()
+        assert not runtime_config.is_set()
+        assert not output.is_set()
+
+    def test_registration_and_help_do_not_prepare_project(self, mocker: MockerFixture) -> None:
+        prepare = mocker.patch("llm_tool_cli.cli.commands.initialization.initialize_project", side_effect=RuntimeError)
+        app = create_app(help="Initialize a project.")
+        register_init_command(
+            app,
+            config_class=ApplicationConfig,
+            package="unavailable_resources",
+            template="missing.toml",
+            help="Create the application configuration.",
+        )
+
+        result = CliRunner().invoke(app, ["init", "-h"])
+
+        assert result.exit_code == 0
+        assert "Create the application configuration." in result.stdout
+        assert not result.stderr
+        assert not project_config.is_set()
+        assert not runtime_config.is_set()
+        assert not output.is_set()
+        prepare.assert_not_called()

llm_tool_cli/cli/commands/tests/test_skills.py

@@ -0,0 +1,154 @@
+import importlib.util
+import json
+import sys
+from enum import StrEnum
+from pathlib import Path
+
+import pytest
+import typer
+from pytest_mock import MockerFixture
+from typer.testing import CliRunner
+
+from llm_tool_cli.cli.application import create_app
+from llm_tool_cli.cli.commands.skills import register_skill_command
+from llm_tool_cli.core.settings import ToolLabel, initialize
+from llm_tool_cli.core.tests.fixtures import isolated_settings
+
+__all__ = ["isolated_settings"]
+
+
+class Document(StrEnum):
+    overview = "usage"
+    custom = "custom-guide"
+
+
+@pytest.fixture
+def skill_app(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, isolated_settings: None) -> typer.Typer:
+    initialize(label=ToolLabel("TEST"))
+    initializer = tmp_path / "__init__.py"
+    initializer.write_text("", encoding="utf-8")
+    package = "cli_skill_test_package"
+    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()
+    for document in Document:
+        (tmp_path / "fixtures" / f"{document.value}.md").write_text(
+            f"  # {document.value}\nCafé 日本語\n\n", encoding="utf-8"
+        )
+    app = create_app(help="Read test documentation.")
+
+    register_skill_command(app, package=package, documents=Document)
+    return app
+
+
+class TestRegisterSkillCommand:
+    @pytest.mark.parametrize("document", [None, "usage", "custom-guide"])
+    @pytest.mark.parametrize("protocol", [None, "human", "llm", "automation"])
+    def test_selected_document_and_protocol(  # noqa: CCR001
+        self, skill_app: typer.Typer, tmp_path: Path, protocol: str | None, document: str | None
+    ) -> None:
+        arguments = [] if protocol is None else ["-p", protocol]
+        arguments.extend(["--config", str(tmp_path / "missing.toml"), "skill"])
+        if document is not None:
+            arguments.append(document)
+
+        result = CliRunner().invoke(skill_app, arguments)
+
+        assert result.exit_code == 0
+        assert not result.stderr
+        name = document or "usage"
+        content = (tmp_path / "fixtures" / f"{name}.md").read_text(encoding="utf-8").strip()
+        if protocol == "automation":
+            record = json.loads(result.stdout)
+            assert record.pop("id")
+            assert record == {"type": "skill", "document": name, "content": content}
+        else:
+            assert result.stdout.startswith("document: " if protocol == "human" else "--TEST-CELL ")
+            separator = ": " if protocol == "human" else "="
+            assert f"document{separator}{name}\n" in result.stdout
+            assert content in result.stdout
+
+    @pytest.mark.parametrize("document", ["missing", "overview", "USAGE", " usage", "../usage", ""])
+    def test_unknown_document_fails_before_loading(
+        self, skill_app: typer.Typer, mocker: MockerFixture, document: str
+    ) -> None:
+        loader = mocker.patch("llm_tool_cli.cli.commands.skills.load_skill_text")
+
+        result = CliRunner().invoke(skill_app, ["skill", document])
+
+        assert result.exit_code == 2
+        assert not result.stdout
+        assert "Invalid value" in result.stderr
+        assert "usage" in result.stderr
+        assert "custom-guide" in result.stderr
+        loader.assert_not_called()
+
+    @pytest.mark.parametrize("protocol", ["human", "llm", "automation"])
+    @pytest.mark.parametrize("content", [None, b"\xff"])
+    def test_unreadable_document(
+        self, skill_app: typer.Typer, tmp_path: Path, protocol: str, content: bytes | None
+    ) -> None:
+        path = tmp_path / "fixtures" / "usage.md"
+        if content is None:
+            path.unlink()
+        else:
+            path.write_bytes(content)
+
+        result = CliRunner().invoke(skill_app, ["-p", protocol, "skill"])
+
+        assert result.exit_code == 3
+        if protocol == "automation":
+            assert not result.stderr
+            record = json.loads(result.stdout)
+            assert record["type"] == "error"
+            assert record["code"] == "skill_unreadable"
+            assert record["document"] == "usage"
+            assert record["reason"]
+            assert record["content"]
+        else:
+            assert not result.stderr
+            separator = ": " if protocol == "human" else "="
+            assert f"code{separator}skill_unreadable\n" in result.stdout
+            assert f"document{separator}usage\n" in result.stdout
+
+    def test_empty_document(self, skill_app: typer.Typer, tmp_path: Path) -> None:
+        (tmp_path / "fixtures" / "usage.md").write_text("", encoding="utf-8")
+
+        result = CliRunner().invoke(skill_app, ["-p", "automation", "skill"])
+
+        assert result.exit_code == 0
+        assert not result.stderr
+        assert json.loads(result.stdout)["content"] is None
+
+    def test_unexpected_failure_propagates(self, skill_app: typer.Typer, mocker: MockerFixture) -> None:
+        mocker.patch("llm_tool_cli.cli.commands.skills.load_skill_text", side_effect=RuntimeError("broken loader"))
+
+        result = CliRunner().invoke(skill_app, ["skill"])
+
+        assert result.exit_code != 0
+        assert isinstance(result.exception, RuntimeError)
+        assert not result.stdout
+        assert not result.stderr
+
+    def test_help_uses_document_values(self, skill_app: typer.Typer) -> None:
+        result = CliRunner().invoke(skill_app, ["skill", "-h"])
+
+        assert result.exit_code == 0
+        assert "Print built-in skill documentation." in result.stdout
+        assert "usage" in result.stdout
+        assert "custom-guide" in result.stdout
+        assert "overview" not in result.stdout
+
+    @pytest.mark.parametrize("prefix, expected", [("", ["usage", "custom-guide"]), ("c", ["custom-guide"])])
+    def test_completion_uses_document_values(self, skill_app: typer.Typer, prefix: str, expected: list[str]) -> None:
+        result = CliRunner().invoke(
+            skill_app,
+            [],
+            prog_name="sample",
+            env={"_SAMPLE_COMPLETE": "complete_bash", "COMP_WORDS": f"sample skill {prefix}", "COMP_CWORD": "2"},
+        )
+
+        assert result.exit_code == 0
+        assert not result.stderr
+        assert result.stdout.splitlines() == expected

llm_tool_cli/cli/commands/tests/test_version.py

@@ -0,0 +1,98 @@
+import json
+import re
+from importlib import metadata
+from pathlib import Path
+
+import pytest
+import typer
+from pytest_mock import MockerFixture
+from typer.testing import CliRunner
+
+from llm_tool_cli.cli.application import create_app
+from llm_tool_cli.cli.commands.version import register_version_command
+from llm_tool_cli.core.settings import ToolLabel, initialize
+from llm_tool_cli.core.tests.fixtures import isolated_settings
+
+__all__ = ["isolated_settings"]
+
+
+@pytest.fixture
+def version_app(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, isolated_settings: None) -> typer.Typer:
+    initialize(label=ToolLabel("TEST"))
+    distribution = tmp_path / "sample_distribution-9.8.7.dist-info"
+    distribution.mkdir()
+    (distribution / "METADATA").write_text(
+        "Metadata-Version: 2.1\nName: sample-distribution\nVersion: 9.8.7\n", encoding="utf-8"
+    )
+    monkeypatch.syspath_prepend(str(tmp_path))
+    monkeypatch.chdir(tmp_path)
+    app = create_app(help="Inspect the test package version.")
+
+    register_version_command(app, distribution="sample-distribution")
+    return app
+
+
+class TestRegisterVersionCommand:
+    @pytest.mark.parametrize("protocol", [None, "human", "llm", "automation"])
+    def test_installed_version_and_protocol(self, version_app: typer.Typer, protocol: str | None) -> None:
+        options = [] if protocol is None else ["-p", protocol]
+
+        result = CliRunner().invoke(version_app, [*options, "version"])
+
+        assert result.exit_code == 0
+        assert not result.stderr
+        if protocol == "automation":
+            record = json.loads(result.stdout)
+            assert record.pop("id")
+            assert record == {"type": "version", "version": "9.8.7", "content": None}
+        else:
+            output = re.sub(r"[A-Za-z0-9_-]{22}", "<id>", result.stdout)
+            if protocol == "llm":
+                assert output == (
+                    "--TEST-CELL <id> BEGIN--\nkind=version\ntype=version\nversion=9.8.7\n" "--TEST-CELL <id> END--\n"
+                )
+            else:
+                assert output == "version: 9.8.7\n\n"
+
+    @pytest.mark.parametrize("config_kind", ["missing", "invalid", "directory"])
+    def test_ignores_configuration(self, version_app: typer.Typer, tmp_path: Path, config_kind: str) -> None:
+        config = tmp_path / "config.toml"
+        if config_kind == "invalid":
+            config.write_text("not valid TOML", encoding="utf-8")
+        elif config_kind == "directory":
+            config.mkdir()
+
+        result = CliRunner().invoke(version_app, ["--config", str(config), "-p", "automation", "version"])
+
+        assert result.exit_code == 0
+        assert not result.stderr
+        assert json.loads(result.stdout)["version"] == "9.8.7"
+
+    @pytest.mark.parametrize(
+        "failure", [metadata.PackageNotFoundError("sample-distribution"), RuntimeError("lookup failed")]
+    )
+    def test_metadata_failure_propagates(
+        self, version_app: typer.Typer, mocker: MockerFixture, failure: Exception
+    ) -> None:
+        mocker.patch("llm_tool_cli.cli.commands.version.metadata.version", side_effect=failure)
+
+        result = CliRunner().invoke(version_app, ["-p", "automation", "version"])
+
+        assert result.exit_code != 0
+        assert isinstance(result.exception, type(failure))
+        assert not result.stdout
+        assert not result.stderr
+
+    def test_registration_and_help_do_not_lookup_metadata(
+        self, version_app: typer.Typer, mocker: MockerFixture
+    ) -> None:
+        lookup = mocker.patch("llm_tool_cli.cli.commands.version.metadata.version", side_effect=RuntimeError)
+        app = create_app(help="An uninstalled package.")
+        register_version_command(app, distribution="uninstalled-distribution")
+
+        result = CliRunner().invoke(version_app, ["version", "-h"])
+
+        assert result.exit_code == 0
+        assert not result.stderr
+        assert "Print the installed package version." in result.stdout
+        lookup.assert_not_called()

llm_tool_cli/cli/commands/version.py

@@ -0,0 +1,17 @@
+from importlib import metadata
+
+import typer
+
+from llm_tool_cli.cli.context import command_context
+from llm_tool_cli.output import output
+from llm_tool_cli.protocol import cell_shortcuts
+
+
+def register_version_command(app: typer.Typer, *, distribution: str) -> None:
+    """Register version output for the supplied installed distribution."""
+
+    @app.command("version", help="Print the installed package version.")
+    def version(context: typer.Context) -> None:
+        with command_context(context):
+            value = metadata.version(distribution)
+            output.get().emit([cell_shortcuts.version(value)]).unwrap()

llm_tool_cli/cli/context.py

@@ -0,0 +1,39 @@
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import typer
+
+from llm_tool_cli.cli.handling import handle_command_errors
+from llm_tool_cli.config.runtime import RuntimeConfig, runtime_config
+from llm_tool_cli.output import StreamOutputEmitter, output
+from llm_tool_cli.paths import ProjectConfigPath
+from llm_tool_cli.protocol import Protocol
+
+
+class CommandContext:
+    __slots__ = ("_context",)
+
+    def __init__(self, context: typer.Context) -> None:
+        self._context = context
+        protocol = context.find_root().params.get("protocol")
+        if protocol is None:
+            protocol = Protocol.llm if context.info_name == "skill" else Protocol.human
+        context.with_resource(runtime_config.scope(RuntimeConfig(protocol=protocol)))
+        context.with_resource(output.scope(StreamOutputEmitter()))
+
+    @property
+    def config_input(self) -> ProjectConfigPath | None:
+        """Unresolved CLI input for configuration loading or creation."""
+        return self._context.find_root().params.get("config_path")
+
+    @property
+    def protocol(self) -> Protocol:
+        return runtime_config.get().protocol
+
+
+@contextmanager
+def command_context(context: typer.Context) -> Iterator[CommandContext]:
+    """Set up command execution and finalize output before framework cleanup."""
+    command = CommandContext(context)
+    with handle_command_errors(protocol=command.protocol):
+        yield command

llm_tool_cli/cli/entities.py

@@ -0,0 +1,3 @@
+from llm_tool_cli.core.entities import ExitCode
+
+__all__ = ["ExitCode"]

llm_tool_cli/cli/errors.py

@@ -0,0 +1,15 @@
+from typing import ClassVar
+
+from llm_tool_cli.core import errors as core_errors
+from llm_tool_cli.core.entities import ExitCode
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    """An expected command-line input failure."""
+
+
+class InvalidArguments(EnvironmentError):
+    cli_exit_code: ClassVar[ExitCode] = ExitCode.invalid_arguments
+    code: str = "invalid_arguments"
+    message: str = "{error.reason}"
+    reason: str

llm_tool_cli/cli/handling.py

@@ -0,0 +1,41 @@
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import NoReturn
+
+import typer
+
+from llm_tool_cli.config.runtime import RuntimeConfig, runtime_config
+from llm_tool_cli.core.errors import EnvironmentErrors, exit_code_for_errors
+from llm_tool_cli.core.result import UnwrapError
+from llm_tool_cli.output import OutputEmitter, StreamOutputEmitter, output
+from llm_tool_cli.protocol import Protocol
+from llm_tool_cli.protocol.cell_shortcuts import environment_error
+
+
+def report_errors_and_exit(
+    errors: EnvironmentErrors, *, protocol: Protocol, emitter: OutputEmitter | None = None
+) -> NoReturn:
+    """Deliver ordered diagnostics through the emitter and exit."""
+    # Parsing can fail before command setup has established runtime/output scopes.
+    emitter = emitter if emitter is not None else StreamOutputEmitter()
+    with runtime_config.scope(RuntimeConfig(protocol=protocol)):
+        emitter.discard()
+        emitter.emit([environment_error(error) for error in errors]).unwrap()
+        emitter.flush()
+    raise typer.Exit(exit_code_for_errors(errors))
+
+
+@contextmanager
+def handle_command_errors(*, protocol: Protocol) -> Iterator[None]:
+    """Report failed result unwrapping while leaving unrelated exceptions alone."""
+    try:
+        yield
+    except UnwrapError as error:
+        report_errors_and_exit(error.errors, protocol=protocol, emitter=output.get() if output.is_set() else None)
+    except BaseException:
+        if output.is_set():
+            output.get().discard()
+        raise
+    else:
+        if output.is_set():
+            output.get().flush()

llm_tool_cli/cli/options.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from llm_tool_cli.cli.errors import InvalidArguments
+from llm_tool_cli.cli.handling import report_errors_and_exit
+from llm_tool_cli.paths import ProjectConfigPath
+from llm_tool_cli.protocol import Protocol
+
+
+def _parse_config_path(value: str) -> ProjectConfigPath:
+    return ProjectConfigPath(Path(value))
+
+
+ConfigOption = Annotated[
+    ProjectConfigPath | None,
+    typer.Option(
+        "--config",
+        parser=_parse_config_path,
+        metavar="PATH",
+        help="Configuration file path. Overrides the command's default configuration location.",
+    ),
+]
+
+
+def _parse_protocol(value: str) -> Protocol:
+    try:
+        return Protocol(value)
+    except ValueError:
+        choices = ", ".join(protocol.value for protocol in Protocol)
+        failure = InvalidArguments(reason=f"invalid protocol `{value}`; expected one of: {choices}")
+        report_errors_and_exit([failure], protocol=Protocol.llm)
+
+
+ProtocolOption = Annotated[
+    Protocol | None,
+    typer.Option(
+        "--protocol",
+        "-p",
+        parser=_parse_protocol,
+        metavar="PROTOCOL",
+        help=(
+            f"Output protocol ({', '.join(protocol.value for protocol in Protocol)}). "
+            "Defaults to llm for skill and human for other commands."
+        ),
+    ),
+]