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

falyx/__init__.py

@@ -12,7 +12,6 @@ from .command import Command
 from .context import ExecutionContext, SharedContext
 from .execution_registry import ExecutionRegistry
 from .falyx import Falyx
-from .hook_manager import HookType
 
 logger = logging.getLogger("falyx")
 

falyx/action/action.py

@@ -62,8 +62,7 @@ class BaseAction(ABC):
     inject_last_result (bool): Whether to inject the previous action's result
                                into kwargs.
     inject_into (str): The name of the kwarg key to inject the result as
-                                 (default: 'last_result').
-    _requires_injection (bool): Whether the action requires input injection.
+                       (default: 'last_result').
     """
 
     def __init__(
@@ -83,7 +82,6 @@ class BaseAction(ABC):
         self.inject_last_result: bool = inject_last_result
         self.inject_into: str = inject_into
         self._never_prompt: bool = never_prompt
-        self._requires_injection: bool = False
         self._skip_in_chain: bool = False
         self.console = Console(color_system="auto")
         self.options_manager: OptionsManager | None = None
@@ -103,7 +101,7 @@ class BaseAction(ABC):
         raise NotImplementedError("preview must be implemented by subclasses")
 
     @abstractmethod
-    def get_infer_target(self) -> Callable[..., Any] | None:
+    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
         """
         Returns the callable to be used for argument inference.
         By default, it returns None.
@@ -163,10 +161,6 @@ class BaseAction(ABC):
     async def _write_stdout(self, data: str) -> None:
         """Override in subclasses that produce terminal output."""
 
-    def requires_io_injection(self) -> bool:
-        """Checks to see if the action requires input injection."""
-        return self._requires_injection
-
     def __repr__(self) -> str:
         return str(self)
 
@@ -255,12 +249,12 @@ class Action(BaseAction):
         if policy.enabled:
             self.enable_retry()
 
-    def get_infer_target(self) -> Callable[..., Any]:
+    def get_infer_target(self) -> tuple[Callable[..., Any], None]:
         """
         Returns the callable to be used for argument inference.
         By default, it returns the action itself.
         """
-        return self.action
+        return self.action, None
 
     async def _run(self, *args, **kwargs) -> Any:
         combined_args = args + self.args
@@ -493,10 +487,10 @@ 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:
+    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
         if self.actions:
             return self.actions[0].get_infer_target()
-        return None
+        return None, None
 
     def _clear_args(self):
         return (), {}
@@ -690,7 +684,7 @@ 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:
+    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
         arg_defs = same_argument_definitions(self.actions)
         if arg_defs:
             return self.actions[0].get_infer_target()
@@ -698,7 +692,7 @@ class ActionGroup(BaseAction, ActionListMixin):
             "[%s] auto_args disabled: mismatched ActionGroup arguments",
             self.name,
         )
-        return None
+        return None, None
 
     async def _run(self, *args, **kwargs) -> list[tuple[str, Any]]:
         shared_context = SharedContext(name=self.name, action=self, is_parallel=True)
@@ -818,8 +812,8 @@ class ProcessAction(BaseAction):
         self.executor = executor or ProcessPoolExecutor()
         self.is_retryable = True
 
-    def get_infer_target(self) -> Callable[..., Any] | None:
-        return self.action
+    def get_infer_target(self) -> tuple[Callable[..., Any] | None, None]:
+        return self.action, None
 
     async def _run(self, *args, **kwargs) -> Any:
         if self.inject_last_result and self.shared_context:

falyx/action/action_factory.py

@@ -35,6 +35,8 @@ class ActionFactoryAction(BaseAction):
         *,
         inject_last_result: bool = False,
         inject_into: str = "last_result",
+        args: tuple[Any, ...] = (),
+        kwargs: dict[str, Any] | None = None,
         preview_args: tuple[Any, ...] = (),
         preview_kwargs: dict[str, Any] | None = None,
     ):
@@ -44,6 +46,8 @@ class ActionFactoryAction(BaseAction):
             inject_into=inject_into,
         )
         self.factory = factory
+        self.args = args
+        self.kwargs = kwargs or {}
         self.preview_args = preview_args
         self.preview_kwargs = preview_kwargs or {}
 
@@ -55,8 +59,8 @@ class ActionFactoryAction(BaseAction):
     def factory(self, value: ActionFactoryProtocol):
         self._factory = ensure_async(value)
 
-    def get_infer_target(self) -> Callable[..., Any]:
-        return self.factory
+    def get_infer_target(self) -> tuple[Callable[..., Any], None]:
+        return self.factory, None
 
     async def _run(self, *args, **kwargs) -> Any:
         updated_kwargs = self._maybe_inject_last_result(kwargs)

falyx/action/io_action.py

@@ -73,7 +73,6 @@ class BaseIOAction(BaseAction):
             inject_last_result=inject_last_result,
         )
         self.mode = mode
-        self._requires_injection = True
 
     def from_input(self, raw: str | bytes) -> Any:
         raise NotImplementedError
@@ -99,8 +98,8 @@ class BaseIOAction(BaseAction):
         )
         raise FalyxError("No input provided and no last result to inject.")
 
-    def get_infer_target(self) -> Callable[..., Any] | None:
-        return None
+    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
+        return None, None
 
     async def __call__(self, *args, **kwargs):
         context = ExecutionContext(
@@ -198,7 +197,6 @@ class ShellAction(BaseIOAction):
     - Captures stdout and stderr from shell execution
     - Raises on non-zero exit codes with stderr as the error
     - Result is returned as trimmed stdout string
-    - Compatible with ChainedAction and Command.requires_input detection
 
     Args:
         name (str): Name of the action.
@@ -223,10 +221,10 @@ class ShellAction(BaseIOAction):
             )
         return raw.strip() if isinstance(raw, str) else raw.decode("utf-8").strip()
 
-    def get_infer_target(self) -> Callable[..., Any] | None:
+    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
         if sys.stdin.isatty():
-            return self._run
-        return None
+            return self._run, {"parsed_input": {"help": self.command_template}}
+        return None, None
 
     async def _run(self, parsed_input: str) -> str:
         # Replace placeholder in template, or use raw input as full command

falyx/action/menu_action.py

@@ -73,8 +73,8 @@ class MenuAction(BaseAction):
             table.add_row(*row)
         return table
 
-    def get_infer_target(self) -> None:
-        return None
+    def get_infer_target(self) -> tuple[None, None]:
+        return None, None
 
     async def _run(self, *args, **kwargs) -> Any:
         kwargs = self._maybe_inject_last_result(kwargs)

falyx/action/select_file_action.py

@@ -25,6 +25,7 @@ from falyx.selection import (
     prompt_for_selection,
     render_selection_dict_table,
 )
+from falyx.signals import CancelSignal
 from falyx.themes import OneColors
 
 
@@ -121,8 +122,15 @@ class SelectFileAction(BaseAction):
                 logger.warning("[ERROR] Failed to parse %s: %s", file.name, error)
         return options
 
-    def get_infer_target(self) -> None:
-        return None
+    def _find_cancel_key(self, options) -> str:
+        """Return first numeric value not already used in the selection dict."""
+        for index in range(len(options)):
+            if str(index) not in options:
+                return str(index)
+        return str(len(options))
+
+    def get_infer_target(self) -> tuple[None, None]:
+        return None, None
 
     async def _run(self, *args, **kwargs) -> Any:
         context = ExecutionContext(name=self.name, args=args, kwargs=kwargs, action=self)
@@ -131,28 +139,38 @@ class SelectFileAction(BaseAction):
             await self.hooks.trigger(HookType.BEFORE, context)
 
             files = [
-                f
-                for f in self.directory.iterdir()
-                if f.is_file()
-                and (self.suffix_filter is None or f.suffix == self.suffix_filter)
+                file
+                for file in self.directory.iterdir()
+                if file.is_file()
+                and (self.suffix_filter is None or file.suffix == self.suffix_filter)
             ]
             if not files:
                 raise FileNotFoundError("No files found in directory.")
 
             options = self.get_options(files)
 
+            cancel_key = self._find_cancel_key(options)
+            cancel_option = {
+                cancel_key: SelectionOption(
+                    description="Cancel", value=CancelSignal(), style=OneColors.DARK_RED
+                )
+            }
+
             table = render_selection_dict_table(
-                title=self.title, selections=options, columns=self.columns
+                title=self.title, selections=options | cancel_option, columns=self.columns
             )
 
             key = await prompt_for_selection(
-                options.keys(),
+                (options | cancel_option).keys(),
                 table,
                 console=self.console,
                 prompt_session=self.prompt_session,
                 prompt_message=self.prompt_message,
             )
 
+            if key == cancel_key:
+                raise CancelSignal("User canceled the selection.")
+
             result = options[key].value
             context.result = result
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
@@ -179,11 +197,11 @@ class SelectFileAction(BaseAction):
         try:
             files = list(self.directory.iterdir())
             if self.suffix_filter:
-                files = [f for f in files if f.suffix == self.suffix_filter]
+                files = [file for file in files if file.suffix == self.suffix_filter]
             sample = files[:10]
             file_list = tree.add("[dim]Files:[/]")
-            for f in sample:
-                file_list.add(f"[dim]{f.name}[/]")
+            for file in sample:
+                file_list.add(f"[dim]{file.name}[/]")
             if len(files) > 10:
                 file_list.add(f"[dim]... ({len(files) - 10} more)[/]")
         except Exception as error:

falyx/action/selection_action.py

@@ -7,19 +7,21 @@ from rich.console import Console
 from rich.tree import Tree
 
 from falyx.action.action import BaseAction
+from falyx.action.types import SelectionReturnType
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
 from falyx.logger import logger
 from falyx.selection import (
     SelectionOption,
+    SelectionOptionMap,
     prompt_for_index,
     prompt_for_selection,
     render_selection_dict_table,
     render_selection_indexed_table,
 )
+from falyx.signals import CancelSignal
 from falyx.themes import OneColors
-from falyx.utils import CaseInsensitiveDict
 
 
 class SelectionAction(BaseAction):
@@ -34,7 +36,13 @@ class SelectionAction(BaseAction):
     def __init__(
         self,
         name: str,
-        selections: list[str] | set[str] | tuple[str, ...] | dict[str, SelectionOption],
+        selections: (
+            list[str]
+            | set[str]
+            | tuple[str, ...]
+            | dict[str, SelectionOption]
+            | dict[str, Any]
+        ),
         *,
         title: str = "Select an option",
         columns: int = 5,
@@ -42,7 +50,7 @@ class SelectionAction(BaseAction):
         default_selection: str = "",
         inject_last_result: bool = False,
         inject_into: str = "last_result",
-        return_key: bool = False,
+        return_type: SelectionReturnType | str = "value",
         console: Console | None = None,
         prompt_session: PromptSession | None = None,
         never_prompt: bool = False,
@@ -55,8 +63,8 @@ class SelectionAction(BaseAction):
             never_prompt=never_prompt,
         )
         # Setter normalizes to correct type, mypy can't infer that
-        self.selections: list[str] | CaseInsensitiveDict = selections  # type: ignore[assignment]
-        self.return_key = return_key
+        self.selections: list[str] | SelectionOptionMap = selections  # type: ignore[assignment]
+        self.return_type: SelectionReturnType = self._coerce_return_type(return_type)
         self.title = title
         self.columns = columns
         self.console = console or Console(color_system="auto")
@@ -65,8 +73,15 @@ class SelectionAction(BaseAction):
         self.prompt_message = prompt_message
         self.show_table = show_table
 
+    def _coerce_return_type(
+        self, return_type: SelectionReturnType | str
+    ) -> SelectionReturnType:
+        if isinstance(return_type, SelectionReturnType):
+            return return_type
+        return SelectionReturnType(return_type)
+
     @property
-    def selections(self) -> list[str] | CaseInsensitiveDict:
+    def selections(self) -> list[str] | SelectionOptionMap:
         return self._selections
 
     @selections.setter
@@ -74,19 +89,40 @@ class SelectionAction(BaseAction):
         self, value: list[str] | set[str] | tuple[str, ...] | dict[str, SelectionOption]
     ):
         if isinstance(value, (list, tuple, set)):
-            self._selections: list[str] | CaseInsensitiveDict = list(value)
+            self._selections: list[str] | SelectionOptionMap = list(value)
         elif isinstance(value, dict):
-            cid = CaseInsensitiveDict()
-            cid.update(value)
-            self._selections = cid
+            som = SelectionOptionMap()
+            if all(isinstance(key, str) for key in value) and all(
+                not isinstance(value[key], SelectionOption) for key in value
+            ):
+                som.update(
+                    {
+                        str(index): SelectionOption(key, option)
+                        for index, (key, option) in enumerate(value.items())
+                    }
+                )
+            elif all(isinstance(key, str) for key in value) and all(
+                isinstance(value[key], SelectionOption) for key in value
+            ):
+                som.update(value)
+            else:
+                raise ValueError("Invalid dictionary format. Keys must be strings")
+            self._selections = som
         else:
             raise TypeError(
                 "'selections' must be a list[str] or dict[str, SelectionOption], "
                 f"got {type(value).__name__}"
             )
 
-    def get_infer_target(self) -> None:
-        return None
+    def _find_cancel_key(self) -> str:
+        """Return first numeric value not already used in the selection dict."""
+        for index in range(len(self.selections)):
+            if str(index) not in self.selections:
+                return str(index)
+        return str(len(self.selections))
+
+    def get_infer_target(self) -> tuple[None, None]:
+        return None, None
 
     async def _run(self, *args, **kwargs) -> Any:
         kwargs = self._maybe_inject_last_result(kwargs)
@@ -128,16 +164,17 @@ class SelectionAction(BaseAction):
 
         context.start_timer()
         try:
+            cancel_key = self._find_cancel_key()
             await self.hooks.trigger(HookType.BEFORE, context)
             if isinstance(self.selections, list):
                 table = render_selection_indexed_table(
                     title=self.title,
-                    selections=self.selections,
+                    selections=self.selections + ["Cancel"],
                     columns=self.columns,
                 )
                 if not self.never_prompt:
                     index = await prompt_for_index(
-                        len(self.selections) - 1,
+                        len(self.selections),
                         table,
                         default_selection=effective_default,
                         console=self.console,
@@ -147,14 +184,23 @@ class SelectionAction(BaseAction):
                     )
                 else:
                     index = effective_default
-                result = self.selections[int(index)]
+                if index == cancel_key:
+                    raise CancelSignal("User cancelled the selection.")
+                result: Any = self.selections[int(index)]
             elif isinstance(self.selections, dict):
+                cancel_option = {
+                    cancel_key: SelectionOption(
+                        description="Cancel", value=CancelSignal, style=OneColors.DARK_RED
+                    )
+                }
                 table = render_selection_dict_table(
-                    title=self.title, selections=self.selections, columns=self.columns
+                    title=self.title,
+                    selections=self.selections | cancel_option,
+                    columns=self.columns,
                 )
                 if not self.never_prompt:
                     key = await prompt_for_selection(
-                        self.selections.keys(),
+                        (self.selections | cancel_option).keys(),
                         table,
                         default_selection=effective_default,
                         console=self.console,
@@ -164,10 +210,25 @@ class SelectionAction(BaseAction):
                     )
                 else:
                     key = effective_default
-                result = key if self.return_key else self.selections[key].value
+                if key == cancel_key:
+                    raise CancelSignal("User cancelled the selection.")
+                if self.return_type == SelectionReturnType.KEY:
+                    result = key
+                elif self.return_type == SelectionReturnType.VALUE:
+                    result = self.selections[key].value
+                elif self.return_type == SelectionReturnType.ITEMS:
+                    result = {key: self.selections[key]}
+                elif self.return_type == SelectionReturnType.DESCRIPTION:
+                    result = self.selections[key].description
+                elif self.return_type == SelectionReturnType.DESCRIPTION_VALUE:
+                    result = {
+                        self.selections[key].description: self.selections[key].value
+                    }
+                else:
+                    raise ValueError(f"Unsupported return type: {self.return_type}")
             else:
                 raise TypeError(
-                    "'selections' must be a list[str] or dict[str, tuple[str, Any]], "
+                    "'selections' must be a list[str] or dict[str, Any], "
                     f"got {type(self.selections).__name__}"
                 )
             context.result = result
@@ -206,7 +267,7 @@ class SelectionAction(BaseAction):
             return
 
         tree.add(f"[dim]Default:[/] '{self.default_selection or self.last_result}'")
-        tree.add(f"[dim]Return:[/] {'Key' if self.return_key else 'Value'}")
+        tree.add(f"[dim]Return:[/] {self.return_type.name.capitalize()}")
         tree.add(f"[dim]Prompt:[/] {'Disabled' if self.never_prompt else 'Enabled'}")
 
         if not parent:
@@ -221,6 +282,6 @@ class SelectionAction(BaseAction):
         return (
             f"SelectionAction(name={self.name!r}, type={selection_type}, "
             f"default_selection={self.default_selection!r}, "
-            f"return_key={self.return_key}, "
+            f"return_type={self.return_type!r}, "
             f"prompt={'off' if self.never_prompt else 'on'})"
         )

falyx/action/types.py

@@ -35,3 +35,18 @@ class FileReturnType(Enum):
                     return member
         valid = ", ".join(member.value for member in cls)
         raise ValueError(f"Invalid FileReturnType: '{value}'. Must be one of: {valid}")
+
+
+class SelectionReturnType(Enum):
+    """Enum for dictionary return types."""
+
+    KEY = "key"
+    VALUE = "value"
+    DESCRIPTION = "description"
+    DESCRIPTION_VALUE = "description_value"
+    ITEMS = "items"
+
+    @classmethod
+    def _missing_(cls, value: object) -> SelectionReturnType:
+        valid = ", ".join(member.value for member in cls)
+        raise ValueError(f"Invalid DictReturnType: '{value}'. Must be one of: {valid}")

falyx/action/user_input_action.py

@@ -43,8 +43,8 @@ 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
+    def get_infer_target(self) -> tuple[None, None]:
+        return None, None
 
     async def _run(self, *args, **kwargs) -> str:
         context = ExecutionContext(

falyx/command.py

@@ -19,7 +19,6 @@ in building robust interactive menus.
 from __future__ import annotations
 
 import shlex
-from functools import cached_property
 from typing import Any, Callable
 
 from prompt_toolkit.formatted_text import FormattedText
@@ -27,8 +26,7 @@ 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.io_action import BaseIOAction
+from falyx.action.action import Action, BaseAction
 from falyx.context import ExecutionContext
 from falyx.debug import register_debug_hooks
 from falyx.execution_registry import ExecutionRegistry as er
@@ -90,7 +88,6 @@ class Command(BaseModel):
         retry_policy (RetryPolicy): Retry behavior configuration.
         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.
@@ -129,7 +126,6 @@ class Command(BaseModel):
     retry_policy: RetryPolicy = Field(default_factory=RetryPolicy)
     tags: list[str] = Field(default_factory=list)
     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)
@@ -146,7 +142,7 @@ class Command(BaseModel):
     def parse_args(
         self, raw_args: list[str] | str, from_validate: bool = False
     ) -> tuple[tuple, dict]:
-        if self.custom_parser:
+        if callable(self.custom_parser):
             if isinstance(raw_args, str):
                 try:
                     raw_args = shlex.split(raw_args)
@@ -183,13 +179,15 @@ class Command(BaseModel):
     def get_argument_definitions(self) -> list[dict[str, Any]]:
         if self.arguments:
             return self.arguments
-        elif self.argument_config:
+        elif callable(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
-                )
+                infer_target, maybe_metadata = self.action.get_infer_target()
+                # merge metadata with the action's metadata if not already in self.arg_metadata
+                if maybe_metadata:
+                    self.arg_metadata = {**maybe_metadata, **self.arg_metadata}
+                return infer_args_from_func(infer_target, self.arg_metadata)
             elif callable(self.action):
                 return infer_args_from_func(self.action, self.arg_metadata)
         return []
@@ -217,30 +215,9 @@ class Command(BaseModel):
         if self.logging_hooks and isinstance(self.action, BaseAction):
             register_debug_hooks(self.action.hooks)
 
-        if self.requires_input is None and self.detect_requires_input:
-            self.requires_input = True
-            self.hidden = True
-        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."""
-        if isinstance(self.action, BaseIOAction):
-            return True
-        elif isinstance(self.action, ChainedAction):
-            return (
-                isinstance(self.action.actions[0], BaseIOAction)
-                if self.action.actions
-                else False
-            )
-        elif isinstance(self.action, ActionGroup):
-            return any(isinstance(action, BaseIOAction) for action in self.action.actions)
-        return False
-
     def _inject_options_manager(self) -> None:
         """Inject the options manager into the action if applicable."""
         if isinstance(self.action, BaseAction):
@@ -333,7 +310,7 @@ class Command(BaseModel):
 
     def show_help(self) -> bool:
         """Display the help message for the command."""
-        if self.custom_help:
+        if callable(self.custom_help):
             output = self.custom_help()
             if output:
                 console.print(output)

falyx/config.py

@@ -98,7 +98,6 @@ class RawCommand(BaseModel):
     retry: bool = False
     retry_all: bool = False
     retry_policy: RetryPolicy = Field(default_factory=RetryPolicy)
-    requires_input: bool | None = None
     hidden: bool = False
     help_text: str = ""
 

falyx/falyx.py

@@ -61,7 +61,7 @@ from falyx.options_manager import OptionsManager
 from falyx.parsers import CommandArgumentParser, get_arg_parsers
 from falyx.protocols import ArgParserProtocol
 from falyx.retry import RetryPolicy
-from falyx.signals import BackSignal, CancelSignal, FlowSignal, HelpSignal, QuitSignal
+from falyx.signals import BackSignal, CancelSignal, HelpSignal, QuitSignal
 from falyx.themes import OneColors, get_nord_theme
 from falyx.utils import CaseInsensitiveDict, _noop, chunks
 from falyx.version import __version__
@@ -90,7 +90,7 @@ class CommandValidator(Validator):
         if not choice:
             raise ValidationError(
                 message=self.error_message,
-                cursor_position=document.get_end_of_document_position(),
+                cursor_position=len(text),
             )
 
 
@@ -111,6 +111,8 @@ class Falyx:
     - Submenu nesting and action chaining
     - History tracking, help generation, and run key execution modes
     - Seamless CLI argument parsing and integration via argparse
+    - Declarative option management with OptionsManager
+    - Command level argument parsing and validation
     - Extensible with user-defined hooks, bottom bars, and custom layouts
 
     Args:
@@ -126,7 +128,7 @@ class Falyx:
         never_prompt (bool): Seed default for `OptionsManager["never_prompt"]`
         force_confirm (bool): Seed default for `OptionsManager["force_confirm"]`
         cli_args (Namespace | None): Parsed CLI arguments, usually from argparse.
-        options (OptionsManager | None): Declarative option mappings.
+        options (OptionsManager | None): Declarative option mappings for global state.
         custom_table (Callable[[Falyx], Table] | Table | None): Custom menu table
                                                                 generator.
 
@@ -160,6 +162,7 @@ class Falyx:
         options: OptionsManager | None = None,
         render_menu: Callable[[Falyx], None] | None = None,
         custom_table: Callable[[Falyx], Table] | Table | None = None,
+        hide_menu_table: bool = False,
     ) -> None:
         """Initializes the Falyx object."""
         self.title: str | Markdown = title
@@ -185,6 +188,7 @@ class Falyx:
         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.hide_menu_table: bool = hide_menu_table
         self.validate_options(cli_args, options)
         self._prompt_session: PromptSession | None = None
         self.mode = FalyxMode.MENU
@@ -287,8 +291,6 @@ class Falyx:
 
         for command in self.commands.values():
             help_text = command.help_text or command.description
-            if command.requires_input:
-                help_text += " [dim](requires input)[/dim]"
             table.add_row(
                 f"[{command.style}]{command.key}[/]",
                 ", ".join(command.aliases) if command.aliases else "",
@@ -445,7 +447,6 @@ 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
 
@@ -608,7 +609,6 @@ class Falyx:
         retry: bool = False,
         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,
@@ -660,7 +660,6 @@ class Falyx:
             retry=retry,
             retry_all=retry_all,
             retry_policy=retry_policy or RetryPolicy(),
-            requires_input=requires_input,
             options_manager=self.options,
             arg_parser=arg_parser,
             arguments=arguments or [],
@@ -768,26 +767,27 @@ class Falyx:
 
         choice = choice.upper()
         name_map = self._name_map
-        if choice in name_map:
+        if name_map.get(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)
+            if is_preview:
+                return True, name_map[choice], args, kwargs
+            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}"
                         )
-                    return is_preview, None, args, kwargs
-                except HelpSignal:
-                    return True, None, args, kwargs
+                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)]
@@ -975,10 +975,11 @@ class Falyx:
             self.print_message(self.welcome_message)
         try:
             while True:
-                if callable(self.render_menu):
-                    self.render_menu(self)
-                else:
-                    self.console.print(self.table, justify="center")
+                if not self.hide_menu_table:
+                    if callable(self.render_menu):
+                        self.render_menu(self)
+                    else:
+                        self.console.print(self.table, justify="center")
                 try:
                     task = asyncio.create_task(self.process_command())
                     should_continue = await task

falyx/hook_manager.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import inspect
 from enum import Enum
-from typing import Awaitable, Callable, Dict, List, Optional, Union
+from typing import Awaitable, Callable, Union
 
 from falyx.context import ExecutionContext
 from falyx.logger import logger
@@ -24,7 +24,7 @@ class HookType(Enum):
     ON_TEARDOWN = "on_teardown"
 
     @classmethod
-    def choices(cls) -> List[HookType]:
+    def choices(cls) -> list[HookType]:
         """Return a list of all hook type choices."""
         return list(cls)
 
@@ -37,16 +37,17 @@ class HookManager:
     """HookManager"""
 
     def __init__(self) -> None:
-        self._hooks: Dict[HookType, List[Hook]] = {
+        self._hooks: dict[HookType, list[Hook]] = {
             hook_type: [] for hook_type in HookType
         }
 
-    def register(self, hook_type: HookType, hook: Hook):
-        if hook_type not in HookType:
-            raise ValueError(f"Unsupported hook type: {hook_type}")
+    def register(self, hook_type: HookType | str, hook: Hook):
+        """Raises ValueError if the hook type is not supported."""
+        if not isinstance(hook_type, HookType):
+            hook_type = HookType(hook_type)
         self._hooks[hook_type].append(hook)
 
-    def clear(self, hook_type: Optional[HookType] = None):
+    def clear(self, hook_type: HookType | None = None):
         if hook_type:
             self._hooks[hook_type] = []
         else:

falyx/menu.py

@@ -33,7 +33,7 @@ class MenuOptionMap(CaseInsensitiveDict):
     and special signal entries like Quit and Back.
     """
 
-    RESERVED_KEYS = {"Q", "B"}
+    RESERVED_KEYS = {"B", "X"}
 
     def __init__(
         self,
@@ -49,14 +49,14 @@ class MenuOptionMap(CaseInsensitiveDict):
     def _inject_reserved_defaults(self):
         from falyx.action import SignalAction
 
-        self._add_reserved(
-            "Q",
-            MenuOption("Exit", SignalAction("Quit", QuitSignal()), OneColors.DARK_RED),
-        )
         self._add_reserved(
             "B",
             MenuOption("Back", SignalAction("Back", BackSignal()), OneColors.DARK_YELLOW),
         )
+        self._add_reserved(
+            "X",
+            MenuOption("Exit", SignalAction("Quit", QuitSignal()), OneColors.DARK_RED),
+        )
 
     def _add_reserved(self, key: str, option: MenuOption) -> None:
         """Add a reserved key, bypassing validation."""
@@ -78,8 +78,20 @@ class MenuOptionMap(CaseInsensitiveDict):
             raise ValueError(f"Cannot delete reserved option '{key}'.")
         super().__delitem__(key)
 
+    def update(self, other=None, **kwargs):
+        """Update the selection options with another dictionary."""
+        if other:
+            for key, option in other.items():
+                if not isinstance(option, MenuOption):
+                    raise TypeError(f"Value for key '{key}' must be a SelectionOption.")
+                self[key] = option
+        for key, option in kwargs.items():
+            if not isinstance(option, MenuOption):
+                raise TypeError(f"Value for key '{key}' must be a SelectionOption.")
+            self[key] = option
+
     def items(self, include_reserved: bool = True):
-        for k, v in super().items():
-            if not include_reserved and k in self.RESERVED_KEYS:
+        for key, option in super().items():
+            if not include_reserved and key in self.RESERVED_KEYS:
                 continue
-            yield k, v
+            yield key, option

falyx/parsers/argparse.py

@@ -1,4 +1,6 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+from __future__ import annotations
+
 from copy import deepcopy
 from dataclasses import dataclass
 from enum import Enum
@@ -23,6 +25,15 @@ class ArgumentAction(Enum):
     COUNT = "count"
     HELP = "help"
 
+    @classmethod
+    def choices(cls) -> list[ArgumentAction]:
+        """Return a list of all argument actions."""
+        return list(cls)
+
+    def __str__(self) -> str:
+        """Return the string representation of the argument action."""
+        return self.value
+
 
 @dataclass
 class Argument:

falyx/parsers/utils.py

@@ -13,7 +13,8 @@ def same_argument_definitions(
     arg_sets = []
     for action in actions:
         if isinstance(action, BaseAction):
-            arg_defs = infer_args_from_func(action.get_infer_target(), arg_metadata)
+            infer_target, _ = action.get_infer_target()
+            arg_defs = infer_args_from_func(infer_target, arg_metadata)
         elif callable(action):
             arg_defs = infer_args_from_func(action, arg_metadata)
         else:

falyx/selection.py

@@ -10,7 +10,7 @@ from rich.markup import escape
 from rich.table import Table
 
 from falyx.themes import OneColors
-from falyx.utils import chunks
+from falyx.utils import CaseInsensitiveDict, chunks
 from falyx.validators import int_range_validator, key_validator
 
 
@@ -32,6 +32,62 @@ class SelectionOption:
         return f"[{OneColors.WHITE}]{key}[/] [{self.style}]{self.description}[/]"
 
 
+class SelectionOptionMap(CaseInsensitiveDict):
+    """
+    Manages selection options including validation and reserved key protection.
+    """
+
+    RESERVED_KEYS: set[str] = set()
+
+    def __init__(
+        self,
+        options: dict[str, SelectionOption] | None = None,
+        allow_reserved: bool = False,
+    ):
+        super().__init__()
+        self.allow_reserved = allow_reserved
+        if options:
+            self.update(options)
+
+    def _add_reserved(self, key: str, option: SelectionOption) -> None:
+        """Add a reserved key, bypassing validation."""
+        norm_key = key.upper()
+        super().__setitem__(norm_key, option)
+
+    def __setitem__(self, key: str, option: SelectionOption) -> None:
+        if not isinstance(option, SelectionOption):
+            raise TypeError(f"Value for key '{key}' must be a SelectionOption.")
+        norm_key = key.upper()
+        if norm_key in self.RESERVED_KEYS and not self.allow_reserved:
+            raise ValueError(
+                f"Key '{key}' is reserved and cannot be used in SelectionOptionMap."
+            )
+        super().__setitem__(norm_key, option)
+
+    def __delitem__(self, key: str) -> None:
+        if key.upper() in self.RESERVED_KEYS and not self.allow_reserved:
+            raise ValueError(f"Cannot delete reserved option '{key}'.")
+        super().__delitem__(key)
+
+    def update(self, other=None, **kwargs):
+        """Update the selection options with another dictionary."""
+        if other:
+            for key, option in other.items():
+                if not isinstance(option, SelectionOption):
+                    raise TypeError(f"Value for key '{key}' must be a SelectionOption.")
+                self[key] = option
+        for key, option in kwargs.items():
+            if not isinstance(option, SelectionOption):
+                raise TypeError(f"Value for key '{key}' must be a SelectionOption.")
+            self[key] = option
+
+    def items(self, include_reserved: bool = True):
+        for k, v in super().items():
+            if not include_reserved and k in self.RESERVED_KEYS:
+                continue
+            yield k, v
+
+
 def render_table_base(
     title: str,
     *,

falyx/version.py

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

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

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

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

@@ -1,52 +1,52 @@
 falyx/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-falyx/__init__.py,sha256=L40665QyjAqHQxHdxxY2_yPeDa4p0LE7Nu_2dkm08Ls,650
+falyx/__init__.py,sha256=MZzno-7HvIYM6pDjDP4t22aN7OaBTTlQYOb7W3Gw_7g,615
 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=f1u7emC3Qa5JUaUsqOFTXMgc5JCv72-MZzckk1N_VO8,33537
-falyx/action/action_factory.py,sha256=ex2Wxpe5mW23FnHuTChzbbw4hmXYuDHKJ330iLBQKIQ,4610
+falyx/action/action.py,sha256=GWVkkbIJBPeS75YXJS9lEYdZD6LXdyMr8yU5KWkt_m4,33389
+falyx/action/action_factory.py,sha256=UuEkx7x0khUe8V4vZhhXQbqkc-V0hYef1Yb3eHIIvjw,4771
 falyx/action/http_action.py,sha256=aIieGHyZSkz1ZGay-fwgDYZ0QF17XypAWtKeVAYp5f4,5806
-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/io_action.py,sha256=tQVonWst44ZXR_87H6-aQ62DZf7qfpbBiKE1oTp9qVA,10061
+falyx/action/menu_action.py,sha256=Qv8iUqlQeXMT6lCXg99YuRGswGWS_tkU8VeuqkC_uQA,5763
+falyx/action/select_file_action.py,sha256=VZkz4H17-XbGooniBMN9ZG406GLerHOrI_BS7hZkkTI,8615
+falyx/action/selection_action.py,sha256=i0CWS70wlhnfRCCBbmHpsytHL0FynIfxc-VQqOao5g8,11608
 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=ne9ytu96QVnuM4jOjjAzB_dd6XS162961uNURtJIRXU,3459
+falyx/action/types.py,sha256=NfZz1ufZuvCgp-he2JIItbnjX7LjOUadjtKbjpRlSIY,1399
+falyx/action/user_input_action.py,sha256=TQ7BlH9lQ5h_t28q6UXCH0hbr2b0vJP7syJmM-okwS0,3478
 falyx/bottom_bar.py,sha256=iWxgOKWgn5YmREeZBuGA50FzqzEfz1-Vnqm0V_fhldc,7383
-falyx/command.py,sha256=BT_zl_R0nYPYKjD_n-ww73zLBmKQB9MmDuWk8ndR4VU,15345
-falyx/config.py,sha256=8dkQfL-Ro-vWw1AcO2fD1PGZ92Cyfnwl885ZlpLkp4Y,9636
+falyx/command.py,sha256=TstVl5bkStISfVfGhOyKP9FpL6glbxXVqPw1lssMCUk,14564
+falyx/config.py,sha256=sApU53PHM8h8eV9YIuTDM1qSGp24AbNy_jJ6GAZhjEo,9597
 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=7luGMkM692puSAQ0j0NE3Pox9QbM3Lc2IFvI0D-3UWc,44137
-falyx/hook_manager.py,sha256=GuGxVVz9FXrU39Tk220QcsLsMXeut7ZDkGW3hU9GcwQ,2952
+falyx/falyx.py,sha256=s5EMkM2EOpS8Uljf-BpEfcJtVshwb3slVuvnZmbIZ_0,44105
+falyx/hook_manager.py,sha256=LRRoVG3gomxI6C9HnLa24WOSZtA-UP9HmpnkT2nvBRo,2986
 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/menu.py,sha256=vZCboxLOfQfUAzTY7Y6wIwoOyRHEPq9rgEelbJ_yNaM,3452
 falyx/options_manager.py,sha256=dFAnQw543tQ6Xupvh1PwBrhiSWlSACHw8K-sHP_lUh4,2842
 falyx/parsers/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 falyx/parsers/__init__.py,sha256=l0QMf89uJHhTpOqQfiV3tx7aAHvELqDFWAyjCbwEgBQ,370
-falyx/parsers/argparse.py,sha256=ElWg4nl1ygkDY9Q4lTfjj4KMXI0FKDLVdc08eiGw4AQ,29889
+falyx/parsers/argparse.py,sha256=rg4S5rJNM25ZzlTgkvV9glOcXYCsdBWSioJvbQXXpUA,30195
 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/parsers/utils.py,sha256=_DUrqOdHDBZdeAqSLCFGnfNljbXTBS0d2T5MDqxGbWQ,888
 falyx/prompt_utils.py,sha256=qgk0bXs7mwzflqzWyFhEOTpKQ_ZtMIqGhKeg-ocwNnE,1542
 falyx/protocols.py,sha256=mesdq5CjPF_5Kyu7Evwr6qMT71tUHlw0SjjtmnggTZw,495
 falyx/retry.py,sha256=UUzY6FlKobr84Afw7yJO9rj3AIQepDk2fcWs6_1gi6Q,3788
 falyx/retry_utils.py,sha256=EAzc-ECTu8AxKkmlw28ioOW9y-Y9tLQ0KasvSkBRYgs,694
-falyx/selection.py,sha256=l2LLISqgP8xfHdcTAEbTTqs_Bae4-LVUKMN7VQH7tM0,10731
+falyx/selection.py,sha256=oVc2xSDnNi6BYOT7I7p24dS3CYHsLBOMcQt6bkz77B0,12887
 falyx/signals.py,sha256=Y_neFXpfHs7qY0syw9XcfR9WeAGRcRw1nG_2L1JJqKE,1083
 falyx/tagged_table.py,sha256=4SV-SdXFrAhy1JNToeBCvyxT-iWVf6cWY7XETTys4n8,1067
 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=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/version.py,sha256=i-fDEsQ0iAiPKXFaj9eERDqcxl3BqNnavaCEqpNxmVI,23
+falyx-0.1.31.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
+falyx-0.1.31.dist-info/METADATA,sha256=IFXJ3n8MaZDsO53drqGeltDS4dqWI_QUqYihQbFCwhI,5521
+falyx-0.1.31.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+falyx-0.1.31.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
+falyx-0.1.31.dist-info/RECORD,,