falyx 0.1.27__py3-none-any.whl → 0.1.29__py3-none-any.whl

falyx/action/io_action.py

@@ -224,7 +224,10 @@ class ShellAction(BaseIOAction):
         # Replace placeholder in template, or use raw input as full command
         command = self.command_template.format(parsed_input)
         if self.safe_mode:
-            args = shlex.split(command)
+            try:
+                args = shlex.split(command)
+            except ValueError as error:
+                raise FalyxError(f"Invalid command template: {error}")
             result = subprocess.run(args, capture_output=True, text=True, check=True)
         else:
             result = subprocess.run(

falyx/command.py

@@ -18,6 +18,7 @@ in building robust interactive menus.
 """
 from __future__ import annotations
 
+import shlex
 from functools import cached_property
 from typing import Any, Callable
 
@@ -26,7 +27,13 @@ from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator
 from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action.action import Action, ActionGroup, BaseAction, ChainedAction
+from falyx.action.action import (
+    Action,
+    ActionGroup,
+    BaseAction,
+    ChainedAction,
+    ProcessAction,
+)
 from falyx.action.io_action import BaseIOAction
 from falyx.context import ExecutionContext
 from falyx.debug import register_debug_hooks
@@ -34,7 +41,13 @@ from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookManager, HookType
 from falyx.logger import logger
 from falyx.options_manager import OptionsManager
+from falyx.parsers import (
+    CommandArgumentParser,
+    infer_args_from_func,
+    same_argument_definitions,
+)
 from falyx.prompt_utils import confirm_async, should_prompt_user
+from falyx.protocols import ArgParserProtocol
 from falyx.retry import RetryPolicy
 from falyx.retry_utils import enable_retries_recursively
 from falyx.signals import CancelSignal
@@ -87,6 +100,11 @@ class Command(BaseModel):
         tags (list[str]): Organizational tags for the command.
         logging_hooks (bool): Whether to attach logging hooks automatically.
         requires_input (bool | None): Indicates if the action needs input.
+        options_manager (OptionsManager): Manages global command-line options.
+        arg_parser (CommandArgumentParser): Parses command arguments.
+        custom_parser (ArgParserProtocol | None): Custom argument parser.
+        custom_help (Callable[[], str | None] | None): Custom help message generator.
+        auto_args (bool): Automatically infer arguments from the action.
 
     Methods:
         __call__(): Executes the command, respecting hooks and retries.
@@ -98,12 +116,13 @@ class Command(BaseModel):
 
     key: str
     description: str
-    action: BaseAction | Callable[[], Any]
+    action: BaseAction | Callable[[Any], Any]
     args: tuple = ()
     kwargs: dict[str, Any] = Field(default_factory=dict)
     hidden: bool = False
     aliases: list[str] = Field(default_factory=list)
     help_text: str = ""
+    help_epilogue: str = ""
     style: str = OneColors.WHITE
     confirm: bool = False
     confirm_message: str = "Are you sure?"
@@ -121,11 +140,46 @@ class Command(BaseModel):
     logging_hooks: bool = False
     requires_input: bool | None = None
     options_manager: OptionsManager = Field(default_factory=OptionsManager)
+    arg_parser: CommandArgumentParser = Field(default_factory=CommandArgumentParser)
+    arguments: list[dict[str, Any]] = Field(default_factory=list)
+    argument_config: Callable[[CommandArgumentParser], None] | None = None
+    custom_parser: ArgParserProtocol | None = None
+    custom_help: Callable[[], str | None] | None = None
+    auto_args: bool = False
+    arg_metadata: dict[str, str | dict[str, Any]] = Field(default_factory=dict)
 
     _context: ExecutionContext | None = PrivateAttr(default=None)
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
+    def parse_args(
+        self, raw_args: list[str] | str, from_validate: bool = False
+    ) -> tuple[tuple, dict]:
+        if self.custom_parser:
+            if isinstance(raw_args, str):
+                try:
+                    raw_args = shlex.split(raw_args)
+                except ValueError:
+                    logger.warning(
+                        "[Command:%s] Failed to split arguments: %s",
+                        self.key,
+                        raw_args,
+                    )
+                    return ((), {})
+            return self.custom_parser(raw_args)
+
+        if isinstance(raw_args, str):
+            try:
+                raw_args = shlex.split(raw_args)
+            except ValueError:
+                logger.warning(
+                    "[Command:%s] Failed to split arguments: %s",
+                    self.key,
+                    raw_args,
+                )
+                return ((), {})
+        return self.arg_parser.parse_args_split(raw_args, from_validate=from_validate)
+
     @field_validator("action", mode="before")
     @classmethod
     def wrap_callable_as_async(cls, action: Any) -> Any:
@@ -135,6 +189,35 @@ class Command(BaseModel):
             return ensure_async(action)
         raise TypeError("Action must be a callable or an instance of BaseAction")
 
+    def get_argument_definitions(self) -> list[dict[str, Any]]:
+        if self.arguments:
+            return self.arguments
+        elif self.argument_config:
+            self.argument_config(self.arg_parser)
+        elif self.auto_args:
+            if isinstance(self.action, (Action, ProcessAction)):
+                return infer_args_from_func(self.action.action, self.arg_metadata)
+            elif isinstance(self.action, ChainedAction):
+                if self.action.actions:
+                    action = self.action.actions[0]
+                    if isinstance(action, Action):
+                        return infer_args_from_func(action.action, self.arg_metadata)
+                    elif callable(action):
+                        return infer_args_from_func(action, self.arg_metadata)
+            elif isinstance(self.action, ActionGroup):
+                arg_defs = same_argument_definitions(
+                    self.action.actions, self.arg_metadata
+                )
+                if arg_defs:
+                    return arg_defs
+                logger.debug(
+                    "[Command:%s] auto_args disabled: mismatched ActionGroup arguments",
+                    self.key,
+                )
+            elif callable(self.action):
+                return infer_args_from_func(self.action, self.arg_metadata)
+        return []
+
     def model_post_init(self, _: Any) -> None:
         """Post-initialization to set up the action and hooks."""
         if self.retry and isinstance(self.action, Action):
@@ -164,6 +247,9 @@ class Command(BaseModel):
         elif self.requires_input is None:
             self.requires_input = False
 
+        for arg_def in self.get_argument_definitions():
+            self.arg_parser.add_argument(*arg_def.pop("flags"), **arg_def)
+
     @cached_property
     def detect_requires_input(self) -> bool:
         """Detect if the action requires input based on its type."""
@@ -269,6 +355,18 @@ class Command(BaseModel):
         if self._context:
             self._context.log_summary()
 
+    def show_help(self) -> bool:
+        """Display the help message for the command."""
+        if self.custom_help:
+            output = self.custom_help()
+            if output:
+                console.print(output)
+            return True
+        if isinstance(self.arg_parser, CommandArgumentParser):
+            self.arg_parser.render_help()
+            return True
+        return False
+
     async def preview(self) -> None:
         label = f"[{OneColors.GREEN_b}]Command:[/] '{self.key}' — {self.description}"
 

falyx/exceptions.py

@@ -28,3 +28,7 @@ class CircuitBreakerOpen(FalyxError):
 
 class EmptyChainError(FalyxError):
     """Exception raised when the chain is empty."""
+
+
+class CommandArgumentError(FalyxError):
+    """Exception raised when there is an error in the command argument parser."""

falyx/falyx.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import shlex
 import sys
 from argparse import Namespace
 from difflib import get_close_matches
@@ -34,7 +35,8 @@ from prompt_toolkit import PromptSession
 from prompt_toolkit.completion import WordCompleter
 from prompt_toolkit.formatted_text import AnyFormattedText
 from prompt_toolkit.key_binding import KeyBindings
-from prompt_toolkit.validation import Validator
+from prompt_toolkit.patch_stdout import patch_stdout
+from prompt_toolkit.validation import ValidationError, Validator
 from rich import box
 from rich.console import Console
 from rich.markdown import Markdown
@@ -47,6 +49,7 @@ from falyx.context import ExecutionContext
 from falyx.debug import log_after, log_before, log_error, log_success
 from falyx.exceptions import (
     CommandAlreadyExistsError,
+    CommandArgumentError,
     FalyxError,
     InvalidActionError,
     NotAFalyxError,
@@ -55,21 +58,42 @@ from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import Hook, HookManager, HookType
 from falyx.logger import logger
 from falyx.options_manager import OptionsManager
-from falyx.parsers import get_arg_parsers
+from falyx.parsers import CommandArgumentParser, get_arg_parsers
+from falyx.protocols import ArgParserProtocol
 from falyx.retry import RetryPolicy
-from falyx.signals import BackSignal, CancelSignal, QuitSignal
+from falyx.signals import BackSignal, CancelSignal, FlowSignal, HelpSignal, QuitSignal
 from falyx.themes import OneColors, get_nord_theme
 from falyx.utils import CaseInsensitiveDict, _noop, chunks, get_program_invocation
 from falyx.version import __version__
 
 
-class FalyxMode(str, Enum):
+class FalyxMode(Enum):
     MENU = "menu"
     RUN = "run"
     PREVIEW = "preview"
     RUN_ALL = "run-all"
 
 
+class CommandValidator(Validator):
+    """Validator to check if the input is a valid command or toggle key."""
+
+    def __init__(self, falyx: Falyx, error_message: str) -> None:
+        super().__init__()
+        self.falyx = falyx
+        self.error_message = error_message
+
+    def validate(self, document) -> None:
+        text = document.text
+        is_preview, choice, _, __ = self.falyx.get_command(text, from_validate=True)
+        if is_preview:
+            return None
+        if not choice:
+            raise ValidationError(
+                message=self.error_message,
+                cursor_position=document.get_end_of_document_position(),
+            )
+
+
 class Falyx:
     """
     Main menu controller for Falyx CLI applications.
@@ -325,7 +349,7 @@ class Falyx:
             keys.extend(cmd.aliases)
         return WordCompleter(keys, ignore_case=True)
 
-    def _get_validator(self) -> Validator:
+    def _get_validator_error_message(self) -> str:
         """Validator to check if the input is a valid command or toggle key."""
         keys = {self.exit_command.key.upper()}
         keys.update({alias.upper() for alias in self.exit_command.aliases})
@@ -354,18 +378,7 @@ class Falyx:
         if toggle_keys:
             message_lines.append(f"  Toggles: {toggles_str}")
         error_message = " ".join(message_lines)
-
-        def validator(text):
-            is_preview, choice = self.get_command(text, from_validate=True)
-            if is_preview and choice is None:
-                return True
-            return bool(choice)
-
-        return Validator.from_callable(
-            validator,
-            error_message=error_message,
-            move_cursor_to_end=True,
-        )
+        return error_message
 
     def _invalidate_prompt_session_cache(self):
         """Forces the prompt session to be recreated on the next access."""
@@ -428,9 +441,11 @@ class Falyx:
                 multiline=False,
                 completer=self._get_completer(),
                 reserve_space_for_menu=1,
-                validator=self._get_validator(),
+                validator=CommandValidator(self, self._get_validator_error_message()),
                 bottom_toolbar=self._get_bottom_bar_render(),
                 key_bindings=self.key_bindings,
+                validate_while_typing=False,
+                interrupt_exception=FlowSignal,
             )
         return self._prompt_session
 
@@ -511,7 +526,7 @@ class Falyx:
         key: str = "X",
         description: str = "Exit",
         aliases: list[str] | None = None,
-        action: Callable[[], Any] | None = None,
+        action: Callable[[Any], Any] | None = None,
         style: str = OneColors.DARK_RED,
         confirm: bool = False,
         confirm_message: str = "Are you sure?",
@@ -565,13 +580,14 @@ class Falyx:
         self,
         key: str,
         description: str,
-        action: BaseAction | Callable[[], Any],
+        action: BaseAction | Callable[[Any], Any],
         *,
         args: tuple = (),
         kwargs: dict[str, Any] | None = None,
         hidden: bool = False,
         aliases: list[str] | None = None,
         help_text: str = "",
+        help_epilogue: str = "",
         style: str = OneColors.WHITE,
         confirm: bool = False,
         confirm_message: str = "Are you sure?",
@@ -593,9 +609,33 @@ class Falyx:
         retry_all: bool = False,
         retry_policy: RetryPolicy | None = None,
         requires_input: bool | None = None,
+        arg_parser: CommandArgumentParser | None = None,
+        arguments: list[dict[str, Any]] | None = None,
+        argument_config: Callable[[CommandArgumentParser], None] | None = None,
+        custom_parser: ArgParserProtocol | None = None,
+        custom_help: Callable[[], str | None] | None = None,
+        auto_args: bool = False,
+        arg_metadata: dict[str, str | dict[str, Any]] | None = None,
     ) -> Command:
         """Adds an command to the menu, preventing duplicates."""
         self._validate_command_key(key)
+
+        if arg_parser:
+            if not isinstance(arg_parser, CommandArgumentParser):
+                raise NotAFalyxError(
+                    "arg_parser must be an instance of CommandArgumentParser."
+                )
+            arg_parser = arg_parser
+        else:
+            arg_parser = CommandArgumentParser(
+                command_key=key,
+                command_description=description,
+                command_style=style,
+                help_text=help_text,
+                help_epilogue=help_epilogue,
+                aliases=aliases,
+            )
+
         command = Command(
             key=key,
             description=description,
@@ -605,6 +645,7 @@ class Falyx:
             hidden=hidden,
             aliases=aliases if aliases else [],
             help_text=help_text,
+            help_epilogue=help_epilogue,
             style=style,
             confirm=confirm,
             confirm_message=confirm_message,
@@ -621,6 +662,13 @@ class Falyx:
             retry_policy=retry_policy or RetryPolicy(),
             requires_input=requires_input,
             options_manager=self.options,
+            arg_parser=arg_parser,
+            arguments=arguments or [],
+            argument_config=argument_config,
+            custom_parser=custom_parser,
+            custom_help=custom_help,
+            auto_args=auto_args,
+            arg_metadata=arg_metadata or {},
         )
 
         if hooks:
@@ -694,32 +742,57 @@ class Falyx:
         return False, input_str.strip()
 
     def get_command(
-        self, choice: str, from_validate=False
-    ) -> tuple[bool, Command | None]:
+        self, raw_choices: str, from_validate=False
+    ) -> tuple[bool, Command | None, tuple, dict[str, Any]]:
         """
         Returns the selected command based on user input.
         Supports keys, aliases, and abbreviations.
         """
+        args = ()
+        kwargs: dict[str, Any] = {}
+        try:
+            choice, *input_args = shlex.split(raw_choices)
+        except ValueError:
+            return False, None, args, kwargs
         is_preview, choice = self.parse_preview_command(choice)
         if is_preview and not choice and self.help_command:
             is_preview = False
             choice = "?"
         elif is_preview and not choice:
+            # No help command enabled
             if not from_validate:
                 self.console.print(
                     f"[{OneColors.DARK_RED}]❌ You must enter a command for preview mode."
                 )
-            return is_preview, None
+            return is_preview, None, args, kwargs
 
         choice = choice.upper()
         name_map = self._name_map
-
         if choice in name_map:
-            return is_preview, name_map[choice]
+            if not from_validate:
+                logger.info("Command '%s' selected.", choice)
+            if input_args and name_map[choice].arg_parser:
+                try:
+                    args, kwargs = name_map[choice].parse_args(input_args, from_validate)
+                except CommandArgumentError as error:
+                    if not from_validate:
+                        if not name_map[choice].show_help():
+                            self.console.print(
+                                f"[{OneColors.DARK_RED}]❌ Invalid arguments for '{choice}': {error}"
+                            )
+                    else:
+                        name_map[choice].show_help()
+                        raise ValidationError(
+                            message=str(error), cursor_position=len(raw_choices)
+                        )
+                    return is_preview, None, args, kwargs
+                except HelpSignal:
+                    return True, None, args, kwargs
+            return is_preview, name_map[choice], args, kwargs
 
         prefix_matches = [cmd for key, cmd in name_map.items() if key.startswith(choice)]
         if len(prefix_matches) == 1:
-            return is_preview, prefix_matches[0]
+            return is_preview, prefix_matches[0], args, kwargs
 
         fuzzy_matches = get_close_matches(choice, list(name_map.keys()), n=3, cutoff=0.7)
         if fuzzy_matches:
@@ -736,7 +809,7 @@ class Falyx:
                 self.console.print(
                     f"[{OneColors.LIGHT_YELLOW}]⚠️ Unknown command '{choice}'[/]"
                 )
-        return is_preview, None
+        return is_preview, None, args, kwargs
 
     def _create_context(self, selected_command: Command) -> ExecutionContext:
         """Creates a context dictionary for the selected command."""
@@ -759,8 +832,9 @@ class Falyx:
 
     async def process_command(self) -> bool:
         """Processes the action of the selected command."""
-        choice = await self.prompt_session.prompt_async()
-        is_preview, selected_command = self.get_command(choice)
+        with patch_stdout(raw=True):
+            choice = await self.prompt_session.prompt_async()
+        is_preview, selected_command, args, kwargs = self.get_command(choice)
         if not selected_command:
             logger.info("Invalid command '%s'.", choice)
             return True
@@ -789,8 +863,7 @@ class Falyx:
         context.start_timer()
         try:
             await self.hooks.trigger(HookType.BEFORE, context)
-
-            result = await selected_command()
+            result = await selected_command(*args, **kwargs)
             context.result = result
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
         except Exception as error:
@@ -803,10 +876,18 @@ class Falyx:
             await self.hooks.trigger(HookType.ON_TEARDOWN, context)
         return True
 
-    async def run_key(self, command_key: str, return_context: bool = False) -> Any:
+    async def run_key(
+        self,
+        command_key: str,
+        return_context: bool = False,
+        args: tuple = (),
+        kwargs: dict[str, Any] | None = None,
+    ) -> Any:
         """Run a command by key without displaying the menu (non-interactive mode)."""
         self.debug_hooks()
-        is_preview, selected_command = self.get_command(command_key)
+        is_preview, selected_command, _, __ = self.get_command(command_key)
+        kwargs = kwargs or {}
+
         self.last_run_command = selected_command
 
         if not selected_command:
@@ -827,7 +908,7 @@ class Falyx:
         context.start_timer()
         try:
             await self.hooks.trigger(HookType.BEFORE, context)
-            result = await selected_command()
+            result = await selected_command(*args, **kwargs)
             context.result = result
 
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
@@ -951,12 +1032,12 @@ class Falyx:
             sys.exit(0)
 
         if self.cli_args.command == "version" or self.cli_args.version:
-            self.console.print(f"[{OneColors.GREEN_b}]Falyx CLI v{__version__}[/]")
+            self.console.print(f"[{OneColors.BLUE_b}]Falyx CLI v{__version__}[/]")
             sys.exit(0)
 
         if self.cli_args.command == "preview":
             self.mode = FalyxMode.PREVIEW
-            _, command = self.get_command(self.cli_args.name)
+            _, command, args, kwargs = self.get_command(self.cli_args.name)
             if not command:
                 self.console.print(
                     f"[{OneColors.DARK_RED}]❌ Command '{self.cli_args.name}' not found."
@@ -970,7 +1051,7 @@ class Falyx:
 
         if self.cli_args.command == "run":
             self.mode = FalyxMode.RUN
-            is_preview, command = self.get_command(self.cli_args.name)
+            is_preview, command, _, __ = self.get_command(self.cli_args.name)
             if is_preview:
                 if command is None:
                     sys.exit(1)
@@ -981,7 +1062,11 @@ class Falyx:
                 sys.exit(1)
             self._set_retry_policy(command)
             try:
-                await self.run_key(self.cli_args.name)
+                args, kwargs = command.parse_args(self.cli_args.command_args)
+            except HelpSignal:
+                sys.exit(0)
+            try:
+                await self.run_key(self.cli_args.name, args=args, kwargs=kwargs)
             except FalyxError as error:
                 self.console.print(f"[{OneColors.DARK_RED}]❌ Error: {error}[/]")
                 sys.exit(1)

falyx/parsers/__init__.py

@@ -0,0 +1,21 @@
+"""
+Falyx CLI Framework
+
+Copyright (c) 2025 rtj.dev LLC.
+Licensed under the MIT License. See LICENSE file for details.
+"""
+
+from .argparse import Argument, ArgumentAction, CommandArgumentParser
+from .parsers import FalyxParsers, get_arg_parsers
+from .signature import infer_args_from_func
+from .utils import same_argument_definitions
+
+__all__ = [
+    "Argument",
+    "ArgumentAction",
+    "CommandArgumentParser",
+    "get_arg_parsers",
+    "FalyxParsers",
+    "infer_args_from_func",
+    "same_argument_definitions",
+]