falyx 0.1.28__py3-none-any.whl → 0.1.30__py3-none-any.whl

falyx/action/action.py

@@ -47,6 +47,7 @@ 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.utils import same_argument_definitions
 from falyx.retry import RetryHandler, RetryPolicy
 from falyx.themes import OneColors
 from falyx.utils import ensure_async
@@ -101,6 +102,14 @@ class BaseAction(ABC):
     async def preview(self, parent: Tree | None = None):
         raise NotImplementedError("preview must be implemented by subclasses")
 
+    @abstractmethod
+    def get_infer_target(self) -> Callable[..., Any] | None:
+        """
+        Returns the callable to be used for argument inference.
+        By default, it returns None.
+        """
+        raise NotImplementedError("get_infer_target must be implemented by subclasses")
+
     def set_options_manager(self, options_manager: OptionsManager) -> None:
         self.options_manager = options_manager
 
@@ -246,6 +255,13 @@ class Action(BaseAction):
         if policy.enabled:
             self.enable_retry()
 
+    def get_infer_target(self) -> Callable[..., Any]:
+        """
+        Returns the callable to be used for argument inference.
+        By default, it returns the action itself.
+        """
+        return self.action
+
     async def _run(self, *args, **kwargs) -> Any:
         combined_args = args + self.args
         combined_kwargs = self._maybe_inject_last_result({**self.kwargs, **kwargs})
@@ -477,6 +493,14 @@ class ChainedAction(BaseAction, ActionListMixin):
         if hasattr(action, "register_teardown") and callable(action.register_teardown):
             action.register_teardown(self.hooks)
 
+    def get_infer_target(self) -> Callable[..., Any] | None:
+        if self.actions:
+            return self.actions[0].get_infer_target()
+        return None
+
+    def _clear_args(self):
+        return (), {}
+
     async def _run(self, *args, **kwargs) -> list[Any]:
         if not self.actions:
             raise EmptyChainError(f"[{self.name}] No actions to execute.")
@@ -505,12 +529,8 @@ class ChainedAction(BaseAction, ActionListMixin):
                     continue
                 shared_context.current_index = index
                 prepared = action.prepare(shared_context, self.options_manager)
-                last_result = shared_context.last_result()
                 try:
-                    if self.requires_io_injection() and last_result is not None:
-                        result = await prepared(**{prepared.inject_into: last_result})
-                    else:
-                        result = await prepared(*args, **updated_kwargs)
+                    result = await prepared(*args, **updated_kwargs)
                 except Exception as error:
                     if index + 1 < len(self.actions) and isinstance(
                         self.actions[index + 1], FallbackAction
@@ -529,6 +549,7 @@ class ChainedAction(BaseAction, ActionListMixin):
                         fallback._skip_in_chain = True
                     else:
                         raise
+                args, updated_kwargs = self._clear_args()
                 shared_context.add_result(result)
                 context.extra["results"].append(result)
                 context.extra["rollback_stack"].append(prepared)
@@ -669,6 +690,16 @@ class ActionGroup(BaseAction, ActionListMixin):
         if hasattr(action, "register_teardown") and callable(action.register_teardown):
             action.register_teardown(self.hooks)
 
+    def get_infer_target(self) -> Callable[..., Any] | None:
+        arg_defs = same_argument_definitions(self.actions)
+        if arg_defs:
+            return self.actions[0].get_infer_target()
+        logger.debug(
+            "[%s] auto_args disabled: mismatched ActionGroup arguments",
+            self.name,
+        )
+        return None
+
     async def _run(self, *args, **kwargs) -> list[tuple[str, Any]]:
         shared_context = SharedContext(name=self.name, action=self, is_parallel=True)
         if self.shared_context:
@@ -787,8 +818,11 @@ class ProcessAction(BaseAction):
         self.executor = executor or ProcessPoolExecutor()
         self.is_retryable = True
 
-    async def _run(self, *args, **kwargs):
-        if self.inject_last_result:
+    def get_infer_target(self) -> Callable[..., Any] | None:
+        return self.action
+
+    async def _run(self, *args, **kwargs) -> Any:
+        if self.inject_last_result and self.shared_context:
             last_result = self.shared_context.last_result()
             if not self._validate_pickleable(last_result):
                 raise ValueError(

falyx/action/action_factory.py

@@ -1,6 +1,6 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 """action_factory.py"""
-from typing import Any
+from typing import Any, Callable
 
 from rich.tree import Tree
 
@@ -55,6 +55,9 @@ class ActionFactoryAction(BaseAction):
     def factory(self, value: ActionFactoryProtocol):
         self._factory = ensure_async(value)
 
+    def get_infer_target(self) -> Callable[..., Any]:
+        return self.factory
+
     async def _run(self, *args, **kwargs) -> Any:
         updated_kwargs = self._maybe_inject_last_result(kwargs)
         context = ExecutionContext(

falyx/action/io_action.py

@@ -19,7 +19,7 @@ import asyncio
 import shlex
 import subprocess
 import sys
-from typing import Any
+from typing import Any, Callable
 
 from rich.tree import Tree
 
@@ -81,15 +81,15 @@ class BaseIOAction(BaseAction):
     def to_output(self, result: Any) -> str | bytes:
         raise NotImplementedError
 
-    async def _resolve_input(self, kwargs: dict[str, Any]) -> str | bytes:
-        last_result = kwargs.pop(self.inject_into, None)
-
+    async def _resolve_input(
+        self, args: tuple[Any], kwargs: dict[str, Any]
+    ) -> str | bytes:
         data = await self._read_stdin()
         if data:
             return self.from_input(data)
 
-        if last_result is not None:
-            return last_result
+        if len(args) == 1:
+            return self.from_input(args[0])
 
         if self.inject_last_result and self.shared_context:
             return self.shared_context.last_result()
@@ -99,6 +99,9 @@ class BaseIOAction(BaseAction):
         )
         raise FalyxError("No input provided and no last result to inject.")
 
+    def get_infer_target(self) -> Callable[..., Any] | None:
+        return None
+
     async def __call__(self, *args, **kwargs):
         context = ExecutionContext(
             name=self.name,
@@ -117,8 +120,8 @@ class BaseIOAction(BaseAction):
                     pass
                 result = getattr(self, "_last_result", None)
             else:
-                parsed_input = await self._resolve_input(kwargs)
-                result = await self._run(parsed_input, *args, **kwargs)
+                parsed_input = await self._resolve_input(args, kwargs)
+                result = await self._run(parsed_input)
                 output = self.to_output(result)
                 await self._write_stdout(output)
             context.result = result
@@ -220,11 +223,19 @@ class ShellAction(BaseIOAction):
             )
         return raw.strip() if isinstance(raw, str) else raw.decode("utf-8").strip()
 
+    def get_infer_target(self) -> Callable[..., Any] | None:
+        if sys.stdin.isatty():
+            return self._run
+        return None
+
     async def _run(self, parsed_input: str) -> str:
         # 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/action/menu_action.py

@@ -73,6 +73,9 @@ class MenuAction(BaseAction):
             table.add_row(*row)
         return table
 
+    def get_infer_target(self) -> None:
+        return None
+
     async def _run(self, *args, **kwargs) -> Any:
         kwargs = self._maybe_inject_last_result(kwargs)
         context = ExecutionContext(

falyx/action/select_file_action.py

@@ -121,6 +121,9 @@ class SelectFileAction(BaseAction):
                 logger.warning("[ERROR] Failed to parse %s: %s", file.name, error)
         return options
 
+    def get_infer_target(self) -> None:
+        return None
+
     async def _run(self, *args, **kwargs) -> Any:
         context = ExecutionContext(name=self.name, args=args, kwargs=kwargs, action=self)
         context.start_timer()

falyx/action/selection_action.py

@@ -85,6 +85,9 @@ class SelectionAction(BaseAction):
                 f"got {type(value).__name__}"
             )
 
+    def get_infer_target(self) -> None:
+        return None
+
     async def _run(self, *args, **kwargs) -> Any:
         kwargs = self._maybe_inject_last_result(kwargs)
         context = ExecutionContext(

falyx/action/user_input_action.py

@@ -43,6 +43,9 @@ class UserInputAction(BaseAction):
         self.console = console or Console(color_system="auto")
         self.prompt_session = prompt_session or PromptSession()
 
+    def get_infer_target(self) -> None:
+        return None
+
     async def _run(self, *args, **kwargs) -> str:
         context = ExecutionContext(
             name=self.name,

falyx/command.py

@@ -29,13 +29,14 @@ from rich.tree import Tree
 
 from falyx.action.action import Action, ActionGroup, BaseAction, ChainedAction
 from falyx.action.io_action import BaseIOAction
-from falyx.argparse import CommandArgumentParser
 from falyx.context import ExecutionContext
 from falyx.debug import register_debug_hooks
 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.argparse import CommandArgumentParser
+from falyx.parsers.signature import infer_args_from_func
 from falyx.prompt_utils import confirm_async, should_prompt_user
 from falyx.protocols import ArgParserProtocol
 from falyx.retry import RetryPolicy
@@ -90,6 +91,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.
@@ -101,12 +107,13 @@ class Command(BaseModel):
 
     key: str
     description: str
-    action: BaseAction | Callable[[], Any]
+    action: BaseAction | Callable[..., 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?"
@@ -125,22 +132,44 @@ class Command(BaseModel):
     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 = True
+    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) -> tuple[tuple, dict]:
+    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):
-                raw_args = shlex.split(raw_args)
+                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):
-            raw_args = shlex.split(raw_args)
-        return self.arg_parser.parse_args_split(raw_args)
+            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
@@ -151,11 +180,22 @@ 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, BaseAction):
+                return infer_args_from_func(
+                    self.action.get_infer_target(), self.arg_metadata
+                )
+            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 isinstance(self.arg_parser, CommandArgumentParser):
-            self.arg_parser.command_description = self.description
-
         if self.retry and isinstance(self.action, Action):
             self.action.enable_retry()
         elif self.retry_policy and isinstance(self.action, Action):
@@ -183,6 +223,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."""

falyx/falyx.py

@@ -58,11 +58,12 @@ 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, HelpSignal, 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.utils import CaseInsensitiveDict, _noop, chunks
 from falyx.version import __version__
 
 
@@ -157,8 +158,8 @@ class Falyx:
         force_confirm: bool = False,
         cli_args: Namespace | None = None,
         options: OptionsManager | None = None,
-        render_menu: Callable[["Falyx"], None] | None = None,
-        custom_table: Callable[["Falyx"], Table] | Table | None = None,
+        render_menu: Callable[[Falyx], None] | None = None,
+        custom_table: Callable[[Falyx], Table] | Table | None = None,
     ) -> None:
         """Initializes the Falyx object."""
         self.title: str | Markdown = title
@@ -182,8 +183,8 @@ class Falyx:
         self._never_prompt: bool = never_prompt
         self._force_confirm: bool = force_confirm
         self.cli_args: Namespace | None = cli_args
-        self.render_menu: Callable[["Falyx"], None] | None = render_menu
-        self.custom_table: Callable[["Falyx"], Table] | Table | None = custom_table
+        self.render_menu: Callable[[Falyx], None] | None = render_menu
+        self.custom_table: Callable[[Falyx], Table] | Table | None = custom_table
         self.validate_options(cli_args, options)
         self._prompt_session: PromptSession | None = None
         self.mode = FalyxMode.MENU
@@ -444,6 +445,7 @@ class Falyx:
                 bottom_toolbar=self._get_bottom_bar_render(),
                 key_bindings=self.key_bindings,
                 validate_while_typing=False,
+                interrupt_exception=FlowSignal,
             )
         return self._prompt_session
 
@@ -524,7 +526,7 @@ class Falyx:
         key: str = "X",
         description: str = "Exit",
         aliases: list[str] | None = None,
-        action: Callable[[], Any] | None = None,
+        action: Callable[..., Any] | None = None,
         style: str = OneColors.DARK_RED,
         confirm: bool = False,
         confirm_message: str = "Are you sure?",
@@ -578,13 +580,14 @@ class Falyx:
         self,
         key: str,
         description: str,
-        action: BaseAction | Callable[[], Any],
+        action: BaseAction | Callable[..., 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?",
@@ -606,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 = True,
+        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,
@@ -618,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,
@@ -634,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:
@@ -715,7 +750,10 @@ class Falyx:
         """
         args = ()
         kwargs: dict[str, Any] = {}
-        choice, *input_args = shlex.split(raw_choices)
+        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
@@ -735,7 +773,7 @@ class Falyx:
                 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)
+                    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():
@@ -748,6 +786,8 @@ class Falyx:
                             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)]
@@ -804,15 +844,6 @@ class Falyx:
             await selected_command.preview()
             return True
 
-        if selected_command.requires_input:
-            program = get_program_invocation()
-            self.console.print(
-                f"[{OneColors.LIGHT_YELLOW}]⚠️ Command '{selected_command.key}' requires"
-                f" input and must be run via [{OneColors.MAGENTA}]'{program} run"
-                f"'[{OneColors.LIGHT_YELLOW}] with proper piping or arguments.[/]"
-            )
-            return True
-
         self.last_run_command = selected_command
 
         if selected_command == self.exit_command:
@@ -823,7 +854,6 @@ class Falyx:
         context.start_timer()
         try:
             await self.hooks.trigger(HookType.BEFORE, context)
-            print(args, kwargs)
             result = await selected_command(*args, **kwargs)
             context.result = result
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
@@ -964,8 +994,6 @@ class Falyx:
                     logger.info("BackSignal received.")
                 except CancelSignal:
                     logger.info("CancelSignal received.")
-                except HelpSignal:
-                    logger.info("HelpSignal received.")
         finally:
             logger.info("Exiting menu: %s", self.get_title())
             if self.exit_message:
@@ -995,7 +1023,7 @@ 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":

falyx/parsers/__init__.py

@@ -0,0 +1,17 @@
+"""
+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
+
+__all__ = [
+    "Argument",
+    "ArgumentAction",
+    "CommandArgumentParser",
+    "get_arg_parsers",
+    "FalyxParsers",
+]

falyx/{argparse.py → parsers/argparse.py}

@@ -5,7 +5,8 @@ from enum import Enum
 from typing import Any, Iterable
 
 from rich.console import Console
-from rich.table import Table
+from rich.markup import escape
+from rich.text import Text
 
 from falyx.exceptions import CommandArgumentError
 from falyx.signals import HelpSignal
@@ -40,6 +41,70 @@ class Argument:
     nargs: int | str = 1  # int, '?', '*', '+'
     positional: bool = False  # True if no leading - or -- in flags
 
+    def get_positional_text(self) -> str:
+        """Get the positional text for the argument."""
+        text = ""
+        if self.positional:
+            if self.choices:
+                text = f"{{{','.join([str(choice) for choice in self.choices])}}}"
+            else:
+                text = self.dest
+        return text
+
+    def get_choice_text(self) -> str:
+        """Get the choice text for the argument."""
+        choice_text = ""
+        if self.choices:
+            choice_text = f"{{{','.join([str(choice) for choice in self.choices])}}}"
+        elif (
+            self.action
+            in (
+                ArgumentAction.STORE,
+                ArgumentAction.APPEND,
+                ArgumentAction.EXTEND,
+            )
+            and not self.positional
+        ):
+            choice_text = self.dest.upper()
+        elif isinstance(self.nargs, str):
+            choice_text = self.dest
+
+        if self.nargs == "?":
+            choice_text = f"[{choice_text}]"
+        elif self.nargs == "*":
+            choice_text = f"[{choice_text} ...]"
+        elif self.nargs == "+":
+            choice_text = f"{choice_text} [{choice_text} ...]"
+        return choice_text
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Argument):
+            return False
+        return (
+            self.flags == other.flags
+            and self.dest == other.dest
+            and self.action == other.action
+            and self.type == other.type
+            and self.choices == other.choices
+            and self.required == other.required
+            and self.nargs == other.nargs
+            and self.positional == other.positional
+        )
+
+    def __hash__(self) -> int:
+        return hash(
+            (
+                tuple(self.flags),
+                self.dest,
+                self.action,
+                self.type,
+                tuple(self.choices or []),
+                self.required,
+                self.nargs,
+                self.positional,
+            )
+        )
+
 
 class CommandArgumentParser:
     """
@@ -61,10 +126,25 @@ class CommandArgumentParser:
     - Render Help using Rich library.
     """
 
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        command_key: str = "",
+        command_description: str = "",
+        command_style: str = "bold",
+        help_text: str = "",
+        help_epilogue: str = "",
+        aliases: list[str] | None = None,
+    ) -> None:
         """Initialize the CommandArgumentParser."""
-        self.command_description: str = ""
+        self.command_key: str = command_key
+        self.command_description: str = command_description
+        self.command_style: str = command_style
+        self.help_text: str = help_text
+        self.help_epilogue: str = help_epilogue
+        self.aliases: list[str] = aliases or []
         self._arguments: list[Argument] = []
+        self._positional: list[Argument] = []
+        self._keyword: list[Argument] = []
         self._flag_map: dict[str, Argument] = {}
         self._dest_set: set[str] = set()
         self._add_help()
@@ -73,10 +153,10 @@ class CommandArgumentParser:
     def _add_help(self):
         """Add help argument to the parser."""
         self.add_argument(
-            "--help",
             "-h",
+            "--help",
             action=ArgumentAction.HELP,
-            help="Show this help message and exit.",
+            help="Show this help message.",
             dest="help",
         )
 
@@ -304,10 +384,31 @@ class CommandArgumentParser:
                 )
             self._flag_map[flag] = argument
         self._arguments.append(argument)
+        if positional:
+            self._positional.append(argument)
+        else:
+            self._keyword.append(argument)
 
     def get_argument(self, dest: str) -> Argument | None:
         return next((a for a in self._arguments if a.dest == dest), None)
 
+    def to_definition_list(self) -> list[dict[str, Any]]:
+        defs = []
+        for arg in self._arguments:
+            defs.append(
+                {
+                    "flags": arg.flags,
+                    "dest": arg.dest,
+                    "action": arg.action,
+                    "type": arg.type,
+                    "choices": arg.choices,
+                    "required": arg.required,
+                    "nargs": arg.nargs,
+                    "positional": arg.positional,
+                }
+            )
+        return defs
+
     def _consume_nargs(
         self, args: list[str], start: int, spec: Argument
     ) -> tuple[list[str], int]:
@@ -405,7 +506,9 @@ class CommandArgumentParser:
 
         return i
 
-    def parse_args(self, args: list[str] | None = None) -> dict[str, Any]:
+    def parse_args(
+        self, args: list[str] | None = None, from_validate: bool = False
+    ) -> dict[str, Any]:
         """Parse Falyx Command arguments."""
         if args is None:
             args = []
@@ -423,7 +526,8 @@ class CommandArgumentParser:
                 action = spec.action
 
                 if action == ArgumentAction.HELP:
-                    self.render_help()
+                    if not from_validate:
+                        self.render_help()
                     raise HelpSignal()
                 elif action == ArgumentAction.STORE_TRUE:
                     result[spec.dest] = True
@@ -550,13 +654,15 @@ class CommandArgumentParser:
         result.pop("help", None)
         return result
 
-    def parse_args_split(self, args: list[str]) -> tuple[tuple[Any, ...], dict[str, Any]]:
+    def parse_args_split(
+        self, args: list[str], from_validate: bool = False
+    ) -> tuple[tuple[Any, ...], dict[str, Any]]:
         """
         Returns:
             tuple[args, kwargs] - Positional arguments in defined order,
             followed by keyword argument mapping.
         """
-        parsed = self.parse_args(args)
+        parsed = self.parse_args(args, from_validate)
         args_list = []
         kwargs_dict = {}
         for arg in self._arguments:
@@ -568,20 +674,74 @@ class CommandArgumentParser:
                 kwargs_dict[arg.dest] = parsed[arg.dest]
         return tuple(args_list), kwargs_dict
 
-    def render_help(self):
-        table = Table(title=f"{self.command_description} Help")
-        table.add_column("Flags")
-        table.add_column("Help")
-        for arg in self._arguments:
-            if arg.dest == "help":
-                continue
-            flag_str = ", ".join(arg.flags) if not arg.positional else arg.dest
-            table.add_row(flag_str, arg.help or "")
-        table.add_section()
-        arg = self.get_argument("help")
-        flag_str = ", ".join(arg.flags) if not arg.positional else arg.dest
-        table.add_row(flag_str, arg.help or "")
-        self.console.print(table)
+    def render_help(self) -> None:
+        # Options
+        # Add all keyword arguments to the options list
+        options_list = []
+        for arg in self._keyword:
+            choice_text = arg.get_choice_text()
+            if choice_text:
+                options_list.extend([f"[{arg.flags[0]} {choice_text}]"])
+            else:
+                options_list.extend([f"[{arg.flags[0]}]"])
+
+        # Add positional arguments to the options list
+        for arg in self._positional:
+            choice_text = arg.get_choice_text()
+            if isinstance(arg.nargs, int):
+                choice_text = " ".join([choice_text] * arg.nargs)
+            options_list.append(escape(choice_text))
+
+        options_text = " ".join(options_list)
+        command_keys = " | ".join(
+            [f"[{self.command_style}]{self.command_key}[/{self.command_style}]"]
+            + [
+                f"[{self.command_style}]{alias}[/{self.command_style}]"
+                for alias in self.aliases
+            ]
+        )
+
+        usage = f"usage: {command_keys} {options_text}"
+        self.console.print(f"[bold]{usage}[/bold]\n")
+
+        # Description
+        if self.help_text:
+            self.console.print(self.help_text + "\n")
+
+        # Arguments
+        if self._arguments:
+            if self._positional:
+                self.console.print("[bold]positional:[/bold]")
+                for arg in self._positional:
+                    flags = arg.get_positional_text()
+                    arg_line = Text(f"  {flags:<30} ")
+                    help_text = arg.help or ""
+                    arg_line.append(help_text)
+                    self.console.print(arg_line)
+            self.console.print("[bold]options:[/bold]")
+            for arg in self._keyword:
+                flags = ", ".join(arg.flags)
+                flags_choice = f"{flags} {arg.get_choice_text()}"
+                arg_line = Text(f"  {flags_choice:<30} ")
+                help_text = arg.help or ""
+                arg_line.append(help_text)
+                self.console.print(arg_line)
+
+        # Epilogue
+        if self.help_epilogue:
+            self.console.print("\n" + self.help_epilogue, style="dim")
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, CommandArgumentParser):
+            return False
+
+        def sorted_args(parser):
+            return sorted(parser._arguments, key=lambda a: a.dest)
+
+        return sorted_args(self) == sorted_args(other)
+
+    def __hash__(self) -> int:
+        return hash(tuple(sorted(self._arguments, key=lambda a: a.dest)))
 
     def __str__(self) -> str:
         positional = sum(arg.positional for arg in self._arguments)

falyx/parsers/signature.py

@@ -0,0 +1,74 @@
+import inspect
+from typing import Any, Callable
+
+from falyx.logger import logger
+
+
+def infer_args_from_func(
+    func: Callable[[Any], Any] | None,
+    arg_metadata: dict[str, str | dict[str, Any]] | None = None,
+) -> list[dict[str, Any]]:
+    """
+    Infer argument definitions from a callable's signature.
+    Returns a list of kwargs suitable for CommandArgumentParser.add_argument.
+    """
+    if not callable(func):
+        logger.debug("Provided argument is not callable: %s", func)
+        return []
+    arg_metadata = arg_metadata or {}
+    signature = inspect.signature(func)
+    arg_defs = []
+
+    for name, param in signature.parameters.items():
+        raw_metadata = arg_metadata.get(name, {})
+        metadata = (
+            {"help": raw_metadata} if isinstance(raw_metadata, str) else raw_metadata
+        )
+
+        if param.kind not in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.KEYWORD_ONLY,
+        ):
+            continue
+
+        arg_type = (
+            param.annotation if param.annotation is not inspect.Parameter.empty else str
+        )
+        default = param.default if param.default is not inspect.Parameter.empty else None
+        is_required = param.default is inspect.Parameter.empty
+        if is_required:
+            flags = [f"{name.replace('_', '-')}"]
+        else:
+            flags = [f"--{name.replace('_', '-')}"]
+        action = "store"
+        nargs: int | str = 1
+
+        if arg_type is bool:
+            if param.default is False:
+                action = "store_true"
+            else:
+                action = "store_false"
+
+        if arg_type is list:
+            action = "append"
+            if is_required:
+                nargs = "+"
+            else:
+                nargs = "*"
+
+        arg_defs.append(
+            {
+                "flags": flags,
+                "dest": name,
+                "type": arg_type,
+                "default": default,
+                "required": is_required,
+                "nargs": nargs,
+                "action": action,
+                "help": metadata.get("help", ""),
+                "choices": metadata.get("choices"),
+            }
+        )
+
+    return arg_defs

falyx/parsers/utils.py

@@ -0,0 +1,27 @@
+from typing import Any
+
+from falyx import logger
+from falyx.parsers.signature import infer_args_from_func
+
+
+def same_argument_definitions(
+    actions: list[Any],
+    arg_metadata: dict[str, str | dict[str, Any]] | None = None,
+) -> list[dict[str, Any]] | None:
+    from falyx.action.action import BaseAction
+
+    arg_sets = []
+    for action in actions:
+        if isinstance(action, BaseAction):
+            arg_defs = infer_args_from_func(action.get_infer_target(), arg_metadata)
+        elif callable(action):
+            arg_defs = infer_args_from_func(action, arg_metadata)
+        else:
+            logger.debug("Auto args unsupported for action: %s", action)
+            return None
+        arg_sets.append(arg_defs)
+
+    first = arg_sets[0]
+    if all(arg_set == first for arg_set in arg_sets[1:]):
+        return first
+    return None

falyx/version.py

@@ -1 +1 @@
-__version__ = "0.1.28"
+__version__ = "0.1.30"

{falyx-0.1.28.dist-info → falyx-0.1.30.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: falyx
-Version: 0.1.28
+Version: 0.1.30
 Summary: Reliable and introspectable async CLI action framework.
 License: MIT
 Author: Roland Thomas Jr

{falyx-0.1.28.dist-info → falyx-0.1.30.dist-info}/RECORD

@@ -1,34 +1,38 @@
 falyx/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 falyx/__init__.py,sha256=L40665QyjAqHQxHdxxY2_yPeDa4p0LE7Nu_2dkm08Ls,650
 falyx/__main__.py,sha256=g_LwJieofK3DJzCYtpkAMEeOXhzSLQenb7pRVUqcf-Y,2152
+falyx/action/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 falyx/action/__init__.py,sha256=zpOK5g4DybydV8d3QI0Zq52aWaKFPYi-J6szAQTsQ2c,974
-falyx/action/action.py,sha256=CJB9eeeEqBGkZHjMpG24eXHRjouKSfESCI1zWzoE7JQ,32488
-falyx/action/action_factory.py,sha256=qNtEnsbKsNl-WijChbTQYfdI3k14fN-1bzDsGFx8yZI,4517
+falyx/action/action.py,sha256=f1u7emC3Qa5JUaUsqOFTXMgc5JCv72-MZzckk1N_VO8,33537
+falyx/action/action_factory.py,sha256=ex2Wxpe5mW23FnHuTChzbbw4hmXYuDHKJ330iLBQKIQ,4610
 falyx/action/http_action.py,sha256=aIieGHyZSkz1ZGay-fwgDYZ0QF17XypAWtKeVAYp5f4,5806
-falyx/action/io_action.py,sha256=zdDq07zSLlaShBQ3ztXTRC6aZL0JoERNZSmvHy1V22w,9718
-falyx/action/menu_action.py,sha256=cboCpXyl0fZUxpFsvEPu0dGhFfr_vdfllceQnICA0gU,5683
-falyx/action/select_file_action.py,sha256=hHLhmTSacWaUXhRTeIIiXt8gR7zbjkXJ2MAkKQYCpp4,7799
-falyx/action/selection_action.py,sha256=22rF7UqRrQAMjGIheDqAbUizVMBg9aCl9e4VOLLZZJo,8811
+falyx/action/io_action.py,sha256=TAa3keVfhCCDgXsp0hWGPx2-B6TKxlvkUGaAD7K-25Q,10051
+falyx/action/menu_action.py,sha256=S_Y_hmyALHrZkfkPXtBKY2qwczfNugAA4M0xOAgOTrM,5744
+falyx/action/select_file_action.py,sha256=5kzN2Kx6wN86Sl5tSLdUs1bAlbSG9AGAi3x1p5HlP6A,7860
+falyx/action/selection_action.py,sha256=aEoCdinMfiKL7tnVOPJ8b56oZ1X51mGfV9rkn_DJKtc,8872
 falyx/action/signal_action.py,sha256=5UMqvzy7fBnLANGwYUWoe1VRhrr7e-yOVeLdOnCBiJo,1350
 falyx/action/types.py,sha256=iVD-bHm1GRXOTIlHOeT_KcDBRZm4Hz5Xzl_BOalvEf4,961
-falyx/action/user_input_action.py,sha256=LSTzC_3TfsfXdz-qV3GlOIGpZWAOgO9J5DnNsHO7ee8,3398
-falyx/argparse.py,sha256=kI_tLYD6KOiWvXEHEvOi8bprx5sQm9KTrgens2_nWKU,24498
+falyx/action/user_input_action.py,sha256=ne9ytu96QVnuM4jOjjAzB_dd6XS162961uNURtJIRXU,3459
 falyx/bottom_bar.py,sha256=iWxgOKWgn5YmREeZBuGA50FzqzEfz1-Vnqm0V_fhldc,7383
-falyx/command.py,sha256=Vr5YHehZB6GavBbHe9diNbdeXNWfnWTkuDZ-NfymcFo,13437
+falyx/command.py,sha256=BT_zl_R0nYPYKjD_n-ww73zLBmKQB9MmDuWk8ndR4VU,15345
 falyx/config.py,sha256=8dkQfL-Ro-vWw1AcO2fD1PGZ92Cyfnwl885ZlpLkp4Y,9636
-falyx/config_schema.py,sha256=j5GQuHVlaU-VLxLF9t8idZRjqOP9MIKp1hyd9NhpAGU,3124
 falyx/context.py,sha256=FNF-IS7RMDxel2l3kskEqQImZ0mLO6zvGw_xC9cIzgI,10338
 falyx/debug.py,sha256=oWWTLOF8elrx_RGZ1G4pbzfFr46FjB0woFXpVU2wmjU,1567
 falyx/exceptions.py,sha256=kK9k1v7LVNjJSwYztRa9Krhr3ZOI-6Htq2ZjlYICPKg,922
 falyx/execution_registry.py,sha256=rctsz0mrIHPToLZqylblVjDdKWdq1x_JBc8GwMP5sJ8,4710
-falyx/falyx.py,sha256=3OrmQ0p7ZOpjLaH5mqTYVEZ96KKTygSLYlPqg3eH5eM,43061
+falyx/falyx.py,sha256=7luGMkM692puSAQ0j0NE3Pox9QbM3Lc2IFvI0D-3UWc,44137
 falyx/hook_manager.py,sha256=GuGxVVz9FXrU39Tk220QcsLsMXeut7ZDkGW3hU9GcwQ,2952
 falyx/hooks.py,sha256=IV2nbj5FjY2m3_L7x4mYBnaRDG45E8tWQU90i4butlw,2940
 falyx/init.py,sha256=abcSlPmxVeByLIHdUkNjqtO_tEkO3ApC6f9WbxsSEWg,3393
 falyx/logger.py,sha256=1Mfb_vJFJ1tQwziuyU2p-cSMi2Js8N2byniFEnI6vOQ,132
 falyx/menu.py,sha256=faxGgocqQYY6HtzVbenHaFj8YqsmycBEyziC8Ahzqjo,2870
 falyx/options_manager.py,sha256=dFAnQw543tQ6Xupvh1PwBrhiSWlSACHw8K-sHP_lUh4,2842
-falyx/parsers.py,sha256=KsDFEmJLM86d2X4Kh4SHA9mBbUk351NjLhhFYzQkaPk,5762
+falyx/parsers/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+falyx/parsers/__init__.py,sha256=l0QMf89uJHhTpOqQfiV3tx7aAHvELqDFWAyjCbwEgBQ,370
+falyx/parsers/argparse.py,sha256=ElWg4nl1ygkDY9Q4lTfjj4KMXI0FKDLVdc08eiGw4AQ,29889
+falyx/parsers/parsers.py,sha256=KsDFEmJLM86d2X4Kh4SHA9mBbUk351NjLhhFYzQkaPk,5762
+falyx/parsers/signature.py,sha256=kniazHBDFIY-cb4JC-gxPL4fviAsoYf8wX0AmWKetGM,2252
+falyx/parsers/utils.py,sha256=g9C_8eJm-2A52SfAL-qyow0VmJXwI-YeRve0phoFiFk,845
 falyx/prompt_utils.py,sha256=qgk0bXs7mwzflqzWyFhEOTpKQ_ZtMIqGhKeg-ocwNnE,1542
 falyx/protocols.py,sha256=mesdq5CjPF_5Kyu7Evwr6qMT71tUHlw0SjjtmnggTZw,495
 falyx/retry.py,sha256=UUzY6FlKobr84Afw7yJO9rj3AIQepDk2fcWs6_1gi6Q,3788
@@ -40,9 +44,9 @@ falyx/themes/__init__.py,sha256=1CZhEUCin9cUk8IGYBUFkVvdHRNNJBEFXccHwpUKZCA,284
 falyx/themes/colors.py,sha256=4aaeAHJetmeNInI0Zytg4E3YqKfPFelpf04vtjSvsS8,19776
 falyx/utils.py,sha256=u3puR4Bh-unNBw9a0V9sw7PDTIzRaNLolap0oz5bVIk,6718
 falyx/validators.py,sha256=t5iyzVpY8tdC4rfhr4isEfWpD5gNTzjeX_Hbi_Uq6sA,1328
-falyx/version.py,sha256=MWZDdAHrdUZS0c3VlLqX4O1eaxPodI7irMtEvknKQ94,23
-falyx-0.1.28.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
-falyx-0.1.28.dist-info/METADATA,sha256=n-VK44OFgjFxyRn1-LdysM1ciDF8RKxlKfAy_0Yz_Zc,5521
-falyx-0.1.28.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-falyx-0.1.28.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
-falyx-0.1.28.dist-info/RECORD,,
+falyx/version.py,sha256=2GUJJyX8g8EAXKUqyj7DGVzG-jNXOGaqVSWilvGYuX8,23
+falyx-0.1.30.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
+falyx-0.1.30.dist-info/METADATA,sha256=U_0NoWJB6xbD0oxYzA8wwVEuIFJvgIB6D4UrgOyt9pc,5521
+falyx-0.1.30.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+falyx-0.1.30.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
+falyx-0.1.30.dist-info/RECORD,,

falyx/config_schema.py

@@ -1,76 +0,0 @@
-FALYX_CONFIG_SCHEMA = {
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "title": "Falyx CLI Config",
-    "type": "object",
-    "properties": {
-        "title": {"type": "string", "description": "Title shown at top of menu"},
-        "prompt": {
-            "oneOf": [
-                {"type": "string"},
-                {
-                    "type": "array",
-                    "items": {
-                        "type": "array",
-                        "prefixItems": [
-                            {
-                                "type": "string",
-                                "description": "Style string (e.g., 'bold #ff0000 italic')",
-                            },
-                            {"type": "string", "description": "Text content"},
-                        ],
-                        "minItems": 2,
-                        "maxItems": 2,
-                    },
-                },
-            ]
-        },
-        "columns": {
-            "type": "integer",
-            "minimum": 1,
-            "description": "Number of menu columns",
-        },
-        "welcome_message": {"type": "string"},
-        "exit_message": {"type": "string"},
-        "commands": {
-            "type": "array",
-            "items": {
-                "type": "object",
-                "required": ["key", "description", "action"],
-                "properties": {
-                    "key": {"type": "string", "minLength": 1},
-                    "description": {"type": "string"},
-                    "action": {
-                        "type": "string",
-                        "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*(\\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
-                        "description": "Dotted import path (e.g., mymodule.task)",
-                    },
-                    "args": {"type": "array"},
-                    "kwargs": {"type": "object"},
-                    "aliases": {"type": "array", "items": {"type": "string"}},
-                    "tags": {"type": "array", "items": {"type": "string"}},
-                    "style": {"type": "string"},
-                    "confirm": {"type": "boolean"},
-                    "confirm_message": {"type": "string"},
-                    "preview_before_confirm": {"type": "boolean"},
-                    "spinner": {"type": "boolean"},
-                    "spinner_message": {"type": "string"},
-                    "spinner_type": {"type": "string"},
-                    "spinner_style": {"type": "string"},
-                    "logging_hooks": {"type": "boolean"},
-                    "retry": {"type": "boolean"},
-                    "retry_all": {"type": "boolean"},
-                    "retry_policy": {
-                        "type": "object",
-                        "properties": {
-                            "enabled": {"type": "boolean"},
-                            "max_retries": {"type": "integer"},
-                            "delay": {"type": "number"},
-                            "backoff": {"type": "number"},
-                        },
-                    },
-                },
-            },
-        },
-    },
-    "required": ["commands"],
-}