wexample-cli 0.0.3__tar.gz → 0.2.0__tar.gz

{wexample_cli-0.0.3 → wexample_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-cli
-Version: 0.0.3
+Version: 0.2.0
 Summary: Reusable CLI primitives — command decorators, options, middlewares, and the enriched command runner — extracted from wex-core so any kernel built on wexample-app can opt in without depending on the full wex framework.
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -9,6 +9,10 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Project-URL: homepage, https://github.com/wexample/python-cli
 Requires-Python: >=3.10
+Requires-Dist: attrs>=23.1.0
+Requires-Dist: wexample-app>=15.1.0
+Requires-Dist: wexample-helpers>=13.0.0
+Requires-Dist: wexample-prompt>=9.0.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -16,7 +20,7 @@ Description-Content-Type: text/markdown
 
 # cli
 
-Version: 0.0.3
+Version: 0.2.0
 
 Reusable CLI primitives — command decorators, options, middlewares, and the enriched command runner — extracted from wex-core so any kernel built on wexample-app can opt in without depending on the full wex framework.
 
@@ -93,6 +97,13 @@ The suite includes packages for configuration management, file handling, prompts
 
 Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
 
+## Dependencies
+
+- attrs: >=23.1.0
+- wexample-app: >=15.1.0
+- wexample-helpers: >=13.0.0
+- wexample-prompt: >=9.0.0
+
 ## Versioning & Compatibility Policy
 
 Wexample packages follow **Semantic Versioning** (SemVer):

{wexample_cli-0.0.3 → wexample_cli-0.2.0}/README.md

@@ -1,6 +1,6 @@
 # cli
 
-Version: 0.0.3
+Version: 0.2.0
 
 Reusable CLI primitives — command decorators, options, middlewares, and the enriched command runner — extracted from wex-core so any kernel built on wexample-app can opt in without depending on the full wex framework.
 
@@ -77,6 +77,13 @@ The suite includes packages for configuration management, file handling, prompts
 
 Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
 
+## Dependencies
+
+- attrs: >=23.1.0
+- wexample-app: >=15.1.0
+- wexample-helpers: >=13.0.0
+- wexample-prompt: >=9.0.0
+
 ## Versioning & Compatibility Policy
 
 Wexample packages follow **Semantic Versioning** (SemVer):

{wexample_cli-0.0.3 → wexample_cli-0.2.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-cli"
-version = "0.0.3"
+version = "0.2.0"
 description = "Reusable CLI primitives — command decorators, options, middlewares, and the enriched command runner — extracted from wex-core so any kernel built on wexample-app can opt in without depending on the full wex framework."
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -17,7 +17,12 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
-dependencies = []
+dependencies = [
+    "attrs>=23.1.0",
+    "wexample-app>=15.1.0",
+    "wexample-helpers>=13.0.0",
+    "wexample-prompt>=9.0.0",
+]
 
 [project.readme]
 file = "README.md"

wexample_cli-0.2.0/src/wexample_cli/command/extended_command.py

@@ -0,0 +1,344 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from wexample_app.common.command import Command
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from wexample_app.common.command_request import CommandRequest
+
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+    from wexample_cli.const.types import ParsedArgs
+    from wexample_cli.context.execution_context import ExecutionContext
+
+
+@base_class
+class ExtendedCommand(Command):
+    command_wrapper: CommandMethodWrapper = public_field(
+        description="The wrapper holding the command function"
+    )
+
+    def __attrs_post_init__(self) -> None:
+        # Now override function based on command_wrapper
+        self.function = self.command_wrapper.function
+
+    def execute_request(self, request: CommandRequest) -> Any:
+        from wexample_app.helpers.response import response_normalize
+        from wexample_app.response.failure_response import FailureResponse
+        from wexample_app.response.multiple_response import MultipleResponse
+
+        from wexample_cli.const.middleware import (
+            MIDDLEWARE_OPTION_VALUE_ALLWAYS,
+            MIDDLEWARE_OPTION_VALUE_OPTIONAL,
+        )
+
+        # Universal --help / -h handling — render the command's options instead
+        # of dispatching. Done before middleware/option validation so it works
+        # even when required options are missing.
+        if isinstance(request.arguments, list) and any(
+            arg in ("--help", "-h") for arg in request.arguments
+        ):
+            return self._render_help(request)
+
+        middlewares_attributes = self.command_wrapper.middlewares_attributes
+        middlewares_registry = self.kernel.get_registry("middlewares")
+
+        for name in middlewares_attributes:
+            middleware_class = middlewares_registry.get_class(name)
+            middleware = middleware_class(**middlewares_attributes[name])
+            self.command_wrapper.set_middleware(middleware)
+
+        function_kwargs = self._build_function_kwargs(request=request)
+
+        if len(self.command_wrapper.middlewares) > 0:
+            output = MultipleResponse(kernel=self.kernel)
+
+            for middleware in self.command_wrapper.middlewares:
+                show_progress = (
+                    middleware.show_progress == MIDDLEWARE_OPTION_VALUE_ALLWAYS
+                    or (
+                        middleware.show_progress == MIDDLEWARE_OPTION_VALUE_OPTIONAL
+                        and function_kwargs["show_progress"]
+                    )
+                )
+
+                # Each middleware can multiply the executions,
+                # e.g. executing the command on every file of a list.
+                execution_contexts = middleware.build_execution_contexts(
+                    command_wrapper=self.command_wrapper,
+                    request=request,
+                    function_kwargs=function_kwargs,
+                )
+
+                # Apply limit if specified
+                if (
+                    isinstance(middleware.max_iterations, int)
+                    and middleware.max_iterations > 0
+                ):
+                    execution_contexts = execution_contexts[: middleware.max_iterations]
+                    self.kernel.io.info(
+                        f'Middleware "{middleware.get_short_class_name()}" truncated list to {middleware.max_iterations} items'
+                    )
+
+                # Check if middleware should run in parallel
+                if middleware.parallel == MIDDLEWARE_OPTION_VALUE_ALLWAYS or (
+                    middleware.parallel == MIDDLEWARE_OPTION_VALUE_OPTIONAL
+                    and "parallel" in function_kwargs
+                    and function_kwargs["parallel"]
+                ):
+                    # Execute passes in parallel using asyncio
+                    responses = asyncio.run(
+                        self._execute_passes_parallel(
+                            execution_contexts=execution_contexts,
+                        )
+                    )
+
+                    # Add all responses to output
+                    for response in responses:
+                        output.append(response)
+
+                        # Check if we should stop on failure
+                        if (
+                            isinstance(response, FailureResponse)
+                            and middleware.stop_on_failure
+                        ):
+                            # "Stop" does not mean "fail", so we just stop the process.
+                            return output
+                else:
+                    i = 0
+                    length = len(execution_contexts)
+
+                    if show_progress:
+                        # First bar.
+                        request.kernel.io.progress(length, i)
+
+                    # Execute passes sequentially
+                    for context in execution_contexts:
+                        # Use context.function if provided, otherwise use command's function
+                        function_to_execute = context.function or self.function
+
+                        response = response_normalize(
+                            kernel=self.kernel,
+                            response=function_to_execute(**context.function_kwargs),
+                        )
+
+                        output.append(response)
+                        i += 1
+
+                        if show_progress:
+                            request.kernel.io.progress(length, i)
+
+                        if isinstance(response, FailureResponse) and (
+                            middleware.stop_on_failure
+                            == MIDDLEWARE_OPTION_VALUE_ALLWAYS
+                            or (
+                                middleware.stop_on_failure
+                                == MIDDLEWARE_OPTION_VALUE_OPTIONAL
+                                and "stop_on_failure" in function_kwargs
+                                and function_kwargs["stop_on_failure"]
+                            )
+                        ):
+                            # "Stop" does not mean "fail", so we just stop the process.
+                            return output
+
+            # If only one response, return it directly instead of wrapping in MultipleResponse
+            if len(output.responses) == 1:
+                return output.responses[0]
+
+            return output
+
+        # Delegate context creation to resolver.
+        context = request.resolver.build_execution_context(
+            middleware=None,
+            command_wrapper=self.command_wrapper,
+            request=request,
+            function_kwargs=function_kwargs,
+        )
+
+        # Use context.function if provided, otherwise use command's function
+        function_to_execute = context.function or self.function
+
+        return response_normalize(
+            kernel=self.kernel, response=function_to_execute(**context.function_kwargs)
+        )
+
+    def _build_function_kwargs(self, request: CommandRequest) -> dict[str, Any]:
+        from wexample_cli.exception.command_option_missing_exception import (
+            CommandOptionMissingException,
+        )
+
+        # Allow middleware to add extra options.
+        for middleware in self.command_wrapper.middlewares:
+            middleware.append_options(
+                request=request,
+                command_wrapper=self.command_wrapper,
+            )
+
+        """Execute the command with the given request arguments."""
+        # Parse and convert arguments to appropriate types
+        parsed_args = self._parse_arguments(request.arguments)
+
+        """Build the final kwargs dictionary for the function call."""
+        function_kwargs = {}
+
+        # Process all declared options
+        for option in self.command_wrapper.options:
+            value = None
+
+            # If the option is in parsed args, use that value
+            if option.name in parsed_args:
+                value = parsed_args[option.name]
+            # Otherwise, use the default value if available
+            elif option.default is not None:
+                value = option.default
+            # If the option is required but not provided, raise an error
+            elif option.required:
+                raise CommandOptionMissingException(option_name=option.name)
+
+            # Validate the value if validators are defined and value is not None
+            if value is not None and option.validators:
+                # For multiple values, validate each item individually
+                values_to_validate = value if isinstance(value, list) else [value]
+
+                for val in values_to_validate:
+                    for validator in option.validators:
+                        if not validator.validate(val):
+                            from wexample_cli.exception.command_option_validation_exception import (
+                                CommandOptionValidationException,
+                            )
+
+                            raise CommandOptionValidationException(
+                                option_name=option.name,
+                                value=val,
+                                error_message=validator.get_error_message(val),
+                            )
+
+            # Normalize to list if always_list is True
+            if value is not None and option.always_list and not isinstance(value, list):
+                value = [value]
+
+            # Assign the validated value
+            if value is not None:
+                option.value = function_kwargs[option.name] = value
+
+        return function_kwargs
+
+    async def _execute_passes_parallel(
+        self, execution_contexts: list[ExecutionContext]
+    ) -> list[Any]:
+        """Execute multiple passes in parallel using asyncio.
+
+        Args:
+            execution_contexts: List of ExecutionPass objects to execute in parallel
+
+        Returns:
+            List of normalized responses from all executions
+        """
+        from concurrent.futures import ThreadPoolExecutor
+
+        from wexample_app.helpers.response import response_normalize
+        from wexample_app.response.abstract_response import AbstractResponse
+
+        # Create a list to store all tasks
+        tasks = []
+
+        # Create an executor for running CPU-bound functions in a thread pool
+        executor = ThreadPoolExecutor(max_workers=min(32, len(execution_contexts)))
+
+        # Define a coroutine that executes a single pass
+        async def execute_single_pass(
+            execution_context: ExecutionContext,
+        ) -> AbstractResponse:
+            from wexample_prompt.output.prompt_buffer_output_handler import (
+                PromptBufferOutputHandler,
+            )
+
+            output = PromptBufferOutputHandler()
+            # Detach io manager to print log result at the end.
+            execution_context._init_io_manager(output=output)
+
+            # Use context.function if provided, otherwise use command's function
+            function_to_execute = execution_context.function or self.function
+
+            # Run the function in a thread pool to avoid blocking the event loop
+            loop = asyncio.get_event_loop()
+            result = await loop.run_in_executor(
+                executor,
+                lambda: function_to_execute(**execution_context.function_kwargs),
+            )
+
+            self.kernel.io.print_responses(output.buffer)
+
+            # Normalize the response
+            return response_normalize(kernel=self.kernel, response=result)
+
+        # Create a task for each pass
+        for execution_context in execution_contexts:
+            task = asyncio.create_task(execute_single_pass(execution_context))
+            tasks.append(task)
+
+        # Wait for all tasks to complete
+        responses = await asyncio.gather(*tasks)
+
+        # Close the executor
+        executor.shutdown(wait=False)
+
+        return responses
+
+    def _parse_arguments(self, arguments: list[str] | dict) -> ParsedArgs:
+        """Parse raw command line arguments into a dictionary of option name to value.
+
+        Accepts either a CLI-style list (["--type", "dict"]) or a dict ({"type": "dict"})
+        which is used directly without conversion.
+        """
+        if isinstance(arguments, dict):
+            return arguments
+
+        from wexample_app.helpers.argument import argument_parse_options
+
+        return argument_parse_options(
+            arguments=arguments,
+            options=self.command_wrapper.options,
+            allowed_option_names=self.command_wrapper.get_options_names(),
+        )
+
+    def _render_help(self, request: CommandRequest) -> Any:
+        """Render usage + options for the command and return a NullResponse."""
+        from wexample_app.response.null_response import NullResponse
+
+        io = self.kernel.io
+        wrapper = self.command_wrapper
+
+        io.log(f"Usage: {request.name} [OPTIONS]")
+        if wrapper.description:
+            io.log("")
+            io.log(wrapper.description)
+
+        # Options listed in the order the user declared them (reverse of
+        # decorator application). Each line shows --kebab/-short, type, and
+        # required/default state.
+        if wrapper.options:
+            io.log("")
+            io.log("Options:")
+            for option in reversed(wrapper.options):
+                flag = f"--{option.kebab_name}"
+                if option.short_name:
+                    flag = f"{flag}, -{option.short_name}"
+                type_name = getattr(option.type, "__name__", str(option.type))
+                meta = []
+                if option.required:
+                    meta.append("required")
+                elif option.default is not None:
+                    meta.append(f"default={option.default!r}")
+                if option.is_flag:
+                    meta.append("flag")
+                meta_str = f"  [{', '.join(meta)}]" if meta else ""
+                desc = f"  {option.description}" if option.description else ""
+                io.log(f"  {flag}  <{type_name}>{meta_str}{desc}")
+        io.log("")
+        io.log("  --help, -h  Show this message and exit.")
+
+        return NullResponse(kernel=self.kernel)

wexample_cli-0.2.0/src/wexample_cli/common/command_method_wrapper.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from wexample_app.command.option import Option
+    from wexample_helpers.const.types import AnyCallable, Kwargs
+
+    from wexample_cli.middleware.abstract_middleware import AbstractMiddleware
+
+
+@base_class
+class CommandMethodWrapper(BaseClass):
+    aliases: list[str] = public_field(
+        factory=list,
+        description="Alternative names to invoke this command",
+    )
+    attachments: dict[str, list[dict]] = public_field(
+        factory=lambda: {"before": [], "after": [], "always_after": []},
+        description="Commands attached before/after this command executes",
+    )
+    description: str | None = public_field(
+        default=None,
+        description="Optional human-readable description of the command method",
+    )
+    extra: dict = public_field(
+        factory=dict,
+        description="Generic key/value storage for addon-specific metadata",
+    )
+    function: AnyCallable = public_field(
+        description="Callable object implementing the command method",
+    )
+    middlewares: list[AbstractMiddleware] = public_field(
+        factory=list,
+        description="List of middleware instances applied to the command method",
+    )
+    middlewares_attributes: dict[str, Kwargs] = public_field(
+        factory=dict,
+        description="Mapping of middleware names to their initialization attributes",
+    )
+    options: list[Option] = public_field(
+        factory=list,
+        description="List of command options available for this method",
+    )
+    sudo: bool = public_field(
+        default=False,
+        description="If True, re-exec the entire process under sudo if not already root",
+    )
+    type: str | None = public_field(
+        description="The command type",
+    )
+    webhook: bool = public_field(
+        default=False,
+        description="If True, this command is accessible via the webhook daemon",
+    )
+
+    def find_option_by_kebab_name(self, kabab_name: str) -> Option | None:
+        """Find an option by its name."""
+        for option in self.options:
+            if option.kebab_name == kabab_name:
+                return option
+        return None
+
+    def find_option_by_name(self, name: str) -> Option | None:
+        """Find an option by its name."""
+        for option in self.options:
+            if option.name == name:
+                return option
+        return None
+
+    def find_option_by_short_name(self, short_name: str) -> Option | None:
+        """Find an option by its short name."""
+        for option in self.options:
+            if option.short_name == short_name:
+                return option
+        return None
+
+    def get_options_names(self) -> list[str]:
+        from wexample_helpers.helpers.string import string_to_kebab_case
+
+        return [string_to_kebab_case(option.name) for option in self.options]
+
+    def register_middleware(
+        self, name: str | type[AbstractMiddleware], middleware_kwargs: Kwargs
+    ) -> None:
+        # Extract name from class if needed
+        if not isinstance(name, str):
+            middleware_name = name.get_name()
+        else:
+            middleware_name = name
+
+        self.middlewares_attributes[middleware_name] = middleware_kwargs
+
+    def set_middleware(self, middleware: AbstractMiddleware) -> None:
+        self.middlewares.append(middleware)
+
+        for option in middleware.normalized_options:
+            self.set_option(option)
+
+    def set_option(self, option: Option) -> None:
+        self.options.append(option)

wexample_cli-0.2.0/src/wexample_cli/const/middleware.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+# filestate: python-constant-sort
+MIDDLEWARE_OPTION_VALUE_ALLWAYS: str = "allways"
+MIDDLEWARE_OPTION_VALUE_OPTIONAL: str = "optional"

wexample_cli-0.2.0/src/wexample_cli/const/types.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from typing import Any
+
+ParsedArgs = dict[str, Any]

wexample_cli-0.2.0/src/wexample_cli/context/execution_context.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_app.common.abstract_kernel_child import AbstractKernelChild
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.classes.mixin.printable_mixin import PrintableMixin
+from wexample_helpers.classes.private_field import private_field
+from wexample_helpers.decorator.base_class import base_class
+from wexample_prompt.mixins.with_io_manager import WithIoManager
+
+if TYPE_CHECKING:
+    from wexample_app.common.command_request import CommandRequest
+    from wexample_app.common.mixins.command_runner_kernel import CommandRunnerKernel
+    from wexample_helpers.const.types import AnyCallable, Kwargs
+    from wexample_prompt.common.progress.progress_handle import ProgressHandle
+
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+    from wexample_cli.middleware.abstract_middleware import AbstractMiddleware
+
+
+@base_class
+class ExecutionContext(
+    AbstractKernelChild,
+    WithIoManager,
+    PrintableMixin,
+    BaseClass,
+):
+    command_wrapper: CommandMethodWrapper = public_field(
+        description="Wrapper around the command method being executed",
+    )
+    function: AnyCallable | None = public_field(
+        default=None,
+        description="Optional custom function to execute instead of command_wrapper.function",
+    )
+    function_kwargs: Kwargs = public_field(
+        factory=dict,
+        description="Keyword arguments passed to the command function",
+    )
+    kernel: CommandRunnerKernel = public_field(
+        description="The kernel is extracted from request", default=None
+    )
+    middleware: AbstractMiddleware | None = public_field(
+        description="Optional middleware applied in this execution context",
+    )
+    request: CommandRequest = public_field(
+        description="The command request associated with this execution",
+    )
+    _current_progress: ProgressHandle | None = private_field(
+        default=None,
+        description="Internal progress handle used to track execution progress",
+    )
+
+    def __attrs_post_init__(self) -> None:
+        self.function_kwargs["context"] = self
+        self.kernel = self.request.kernel
+        self.io = self.kernel.io
+
+    def create_progress_range(self, **kwargs) -> ProgressHandle:
+        self._current_progress = self.get_or_create_progress().create_range_handle(
+            **kwargs
+        )
+        return self._current_progress
+
+    def finish_progress(self, **kwargs) -> ProgressHandle:
+        self._current_progress.finish()
+
+        self._current_progress = self._current_progress.parent
+        self._current_progress.update(**kwargs)
+        return self._current_progress
+
+    def get_or_create_progress(self, **kwargs) -> ProgressHandle:
+        if self._current_progress is None:
+            self._current_progress = self.io.progress(
+                **kwargs, context=self.io.create_context()
+            ).get_handle()
+        return self._current_progress

wexample_cli-0.2.0/src/wexample_cli/decorator/alias.py

@@ -0,0 +1,34 @@
+"""@alias decorator — attach one or more invocation aliases to a command wrapper.
+
+Originally lived in ``wexample_cli.decorator.alias``; moved here so any
+kernel using the wexample-cli command primitives can register aliases without
+depending on wex-core. ``wex-core`` re-exports this symbol unchanged.
+
+The decorator simply appends to the wrapper's ``aliases`` list — it does not
+import the concrete wrapper class (which still lives in wex-core for now) to
+avoid a circular dependency. Any object exposing an ``aliases: list[str]``
+attribute is acceptable, which is the de facto contract.
+"""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def alias(*aliases: str):
+    """Append ``aliases`` to ``wrapper.aliases`` and return the wrapper.
+
+    Intended to be stacked on top of @command::
+
+        @alias("version")
+        @command(...)
+        def core__version__get(...): ...
+    """
+
+    def decorator(wrapper: T) -> T:
+        wrapper.aliases.extend(aliases)
+        return wrapper
+
+    return decorator

wexample_cli-0.2.0/src/wexample_cli/decorator/as_sudo.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+
+
+def as_sudo() -> CommandMethodWrapper:
+    def decorator(wrapper: CommandMethodWrapper) -> CommandMethodWrapper:
+        wrapper.sudo = True
+        return wrapper
+
+    return decorator

wexample_cli-0.2.0/src/wexample_cli/decorator/command.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from wexample_helpers.const.types import AnyCallable
+
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+
+
+def command(type: str, description: str | None = None):
+    def decorator(function: AnyCallable) -> CommandMethodWrapper:
+        from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+
+        return CommandMethodWrapper(
+            type=type, function=function, description=description
+        )
+
+    return decorator

wexample_cli-0.2.0/src/wexample_cli/decorator/middleware.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from wexample_helpers.const.types import AnyCallable
+
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+    from wexample_cli.middleware.abstract_middleware import AbstractMiddleware
+
+
+def middleware(
+    name: str | type[AbstractMiddleware] | None = None,
+    middleware: type[AbstractMiddleware] | None = None,
+    **kwargs,
+) -> AnyCallable:
+    def decorator(command_wrapper: CommandMethodWrapper) -> CommandMethodWrapper:
+        # Type safety check
+        from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+
+        if not isinstance(command_wrapper, CommandMethodWrapper):
+            raise TypeError(
+                f"Invalid middleware usage: @middleware must decorate a {CommandMethodWrapper.__name__} "
+                "object (produced by @command). Make sure @command is applied *before* @middleware."
+            )
+
+        command_wrapper.register_middleware(middleware or name, kwargs)
+        return command_wrapper
+
+    return decorator

wexample_cli-0.2.0/src/wexample_cli/decorator/option.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from wexample_helpers.const.types import AnyCallable
+    from wexample_helpers.validator.abstract_validator import AbstractValidator
+
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+
+
+def option(
+    name: str,
+    type: type,
+    short_name: str | bool | None = None,
+    description: str | None = None,
+    required: bool = False,
+    default: Any = None,
+    is_flag: bool = False,
+    multiple: bool = False,
+    always_list: bool = False,
+    validators: list[AbstractValidator] | None = None,
+) -> AnyCallable:
+    def decorator(command_wrapper: CommandMethodWrapper) -> CommandMethodWrapper:
+        from wexample_app.command.option import Option
+
+        command_wrapper.set_option(
+            Option(
+                name=name,
+                short_name=short_name,
+                type=type,
+                description=description,
+                required=required,
+                default=default,
+                is_flag=is_flag,
+                multiple=multiple,
+                always_list=always_list,
+                validators=validators or [],
+            )
+        )
+
+        return command_wrapper
+
+    return decorator

wexample_cli-0.2.0/src/wexample_cli/decorator/option_stop_on_failure.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from wexample_helpers.const.types import AnyCallable
+
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+
+OPTION_NAME_STOP_ON_FAILURE: str = "stop_on_failure"
+
+
+def option_stop_on_failure() -> AnyCallable:
+    def decorator(command_wrapper: CommandMethodWrapper) -> CommandMethodWrapper:
+        from wexample_app.command.option import Option
+
+        command_wrapper.set_option(
+            Option(
+                name=OPTION_NAME_STOP_ON_FAILURE,
+                type=bool,
+                description="Stop execution when exception occurs",
+                required=False,
+                default=False,
+                is_flag=True,
+            )
+        )
+
+        return command_wrapper
+
+    return decorator

wexample_cli-0.2.0/src/wexample_cli/decorator/webhook.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+
+
+def webhook() -> type[CommandMethodWrapper]:
+    """Mark a command as webhook-accessible.
+
+    Sets the ``_wex_webhook`` attribute on the underlying function so the
+    webhook system can discover it.  Token generation is explicit via
+    ``wex webhook/token-show``.
+
+    Usage::
+
+        @webhook()
+        @command(type=COMMAND_TYPE_ADDON)
+        def my__group__command(context): ...
+    """
+
+    def decorator(wrapper: CommandMethodWrapper) -> CommandMethodWrapper:
+        wrapper.webhook = True
+        return wrapper
+
+    return decorator  # type: ignore[return-value]

wexample_cli-0.2.0/src/wexample_cli/exception/abstract_command_option_exception.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wexample_helpers.exception.undefined_exception import UndefinedException
+
+
+class AbstractCommandOptionException(UndefinedException):
+    """Base exception class for command option related errors."""
+
+    error_code: str = "COMMAND_OPTION_ERROR"
+
+    def __init__(
+        self,
+        option_name: str,
+        message: str,
+        data: dict[str, Any] | None = None,
+        cause: Exception | None = None,
+        previous: Exception | None = None,
+    ) -> None:
+        # Merge provided data with base data
+        merged_data = {option_name: option_name}
+        if data:
+            merged_data.update(data)
+
+        # Store option_name as instance attribute
+        self.option_name = option_name
+
+        super().__init__(
+            message=message, data=merged_data, cause=cause, previous=previous
+        )

wexample_cli-0.2.0/src/wexample_cli/exception/command_option_missing_exception.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from wexample_cli.exception.abstract_command_option_exception import (
+    AbstractCommandOptionException,
+)
+
+
+class CommandOptionMissingException(AbstractCommandOptionException):
+    """Exception raised when a required command option is missing."""
+
+    error_code: str = "COMMAND_OPTION_MISSING"
+
+    def __init__(
+        self,
+        option_name: str,
+        cause: Exception | None = None,
+        previous: Exception | None = None,
+    ) -> None:
+        # Store option_name as instance attribute
+        self.option_name = option_name
+
+        super().__init__(
+            option_name=option_name,
+            message=f"Required option '{option_name}' is missing",
+            cause=cause,
+            previous=previous,
+        )

wexample_cli-0.2.0/src/wexample_cli/exception/command_option_validation_exception.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wexample_cli.exception.abstract_command_option_exception import (
+    AbstractCommandOptionException,
+)
+
+
+class CommandOptionValidationException(AbstractCommandOptionException):
+    def __init__(self, option_name: str, value: Any, error_message: str) -> None:
+        super().__init__(
+            message=f'Option "{option_name}" validation failed: {error_message}',
+            option_name=option_name,
+        )
+        self.value = value
+        self.error_message = error_message

wexample_cli-0.2.0/src/wexample_cli/middleware/abstract_middleware.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from wexample_helpers.classes.base_class import BaseClass
+from wexample_helpers.classes.field import public_field
+from wexample_helpers.classes.mixin.has_class_dependencies import HasClassDependencies
+from wexample_helpers.classes.mixin.has_snake_short_class_name_class_mixin import (
+    HasSnakeShortClassNameClassMixin,
+)
+from wexample_helpers.classes.mixin.has_two_steps_init import HasTwoStepInit
+from wexample_helpers.decorator.base_class import base_class
+
+if TYPE_CHECKING:
+    from wexample_app.command.option import Option
+    from wexample_app.common.command_request import CommandRequest
+    from wexample_helpers.const.types import Kwargs
+
+    from wexample_cli.common.command_method_wrapper import CommandMethodWrapper
+    from wexample_cli.context.execution_context import ExecutionContext
+
+
+@base_class
+class AbstractMiddleware(
+    HasSnakeShortClassNameClassMixin,
+    HasTwoStepInit,
+    HasClassDependencies,
+    BaseClass,
+):
+    max_iterations: int | None = public_field(
+        default=None,
+        description="Maximum number of iterations allowed for this middleware",
+    )
+    normalized_options: list[Option] = public_field(
+        factory=list,
+        description="List of normalized option objects for middleware configuration",
+    )
+    options: list[Option] = public_field(
+        factory=list,
+        description="Option objects provided to the middleware",
+    )
+    parallel: None | bool | str = public_field(
+        default=False,
+        description="Whether the middleware should run in parallel (bool, str, or None)",
+    )
+    show_progress: None | bool | str = public_field(
+        default=False,
+        description="Whether to display a progress indicator during execution",
+    )
+    stop_on_failure: None | bool | str = public_field(
+        default=False,
+        description="Whether to stop execution immediately if a failure occurs",
+    )
+
+    def __attrs_post_init__(self) -> None:
+        self.normalized_options = self._init_options()
+
+    @classmethod
+    def get_class_name_suffix(cls) -> str | None:
+        return "Middleware"
+
+    def append_options(
+        self, request: CommandRequest, command_wrapper: CommandMethodWrapper
+    ) -> None:
+        from wexample_app.command.option import Option
+
+        from wexample_cli.const.middleware import MIDDLEWARE_OPTION_VALUE_OPTIONAL
+
+        if self.parallel:
+            self.stop_on_failure = False
+            request.kernel.io.log(
+                'Option "stop_on_failure" will be ignored due to parallelization'
+            )
+
+        if self.parallel == MIDDLEWARE_OPTION_VALUE_OPTIONAL:
+            command_wrapper.set_option(
+                Option(
+                    name="parallel",
+                    short_name="pll",
+                    type=bool,
+                    description="Execute async when possible",
+                    default=False,
+                    is_flag=True,
+                )
+            )
+
+        if self.show_progress == MIDDLEWARE_OPTION_VALUE_OPTIONAL:
+            command_wrapper.set_option(
+                Option(
+                    name="progress",
+                    short_name="prgs",
+                    type=bool,
+                    description="Display progress bar",
+                    default=False,
+                    is_flag=True,
+                )
+            )
+
+        if self.stop_on_failure == MIDDLEWARE_OPTION_VALUE_OPTIONAL:
+            command_wrapper.set_option(
+                Option(
+                    name="stop-on-failure",
+                    short_name="sof",
+                    type=bool,
+                    description="Stop at first failure response if not async",
+                    default=False,
+                    is_flag=True,
+                )
+            )
+
+    def build_execution_contexts(
+        self,
+        command_wrapper: CommandMethodWrapper,
+        request: CommandRequest,
+        function_kwargs: Kwargs,
+    ) -> list[ExecutionContext]:
+        from wexample_cli.context.execution_context import ExecutionContext
+
+        self.validate_options(
+            command_wrapper=command_wrapper,
+            request=request,
+            function_kwargs=function_kwargs,
+        )
+
+        return [
+            ExecutionContext(
+                middleware=self,
+                command_wrapper=command_wrapper,
+                request=request,
+                function_kwargs=function_kwargs,
+            )
+        ]
+
+    def get_option_by_name(self, name: str) -> Option | None:
+        """Get an option by its name from the normalized options."""
+        for option in self.normalized_options:
+            if option.name == name:
+                return option
+        return None
+
+    def validate_options(
+        self,
+        command_wrapper: CommandMethodWrapper,
+        request: CommandRequest,
+        function_kwargs: Kwargs,
+    ) -> bool:
+        return True
+
+    def _get_middleware_options(self) -> list[Option]:
+        return []
+
+    def _init_options(self) -> list[Option]:
+        """Get middleware options."""
+        return self._get_middleware_options()