falyx 0.1.19__tar.gz → 0.1.21__tar.gz

{falyx-0.1.19 → falyx-0.1.21}/PKG-INFO

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

{falyx-0.1.19 → falyx-0.1.21}/falyx/action.py

@@ -56,7 +56,7 @@ class BaseAction(ABC):
     be run independently or as part of Falyx.
 
     inject_last_result (bool): Whether to inject the previous action's result into kwargs.
-    inject_last_result_as (str): The name of the kwarg key to inject the result as
+    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.
     """
@@ -64,9 +64,10 @@ class BaseAction(ABC):
     def __init__(
         self,
         name: str,
+        *,
         hooks: HookManager | None = None,
         inject_last_result: bool = False,
-        inject_last_result_as: str = "last_result",
+        inject_into: str = "last_result",
         never_prompt: bool = False,
         logging_hooks: bool = False,
     ) -> None:
@@ -75,7 +76,7 @@ class BaseAction(ABC):
         self.is_retryable: bool = False
         self.shared_context: SharedContext | None = None
         self.inject_last_result: bool = inject_last_result
-        self.inject_last_result_as: str = inject_last_result_as
+        self.inject_into: str = inject_into
         self._never_prompt: bool = never_prompt
         self._requires_injection: bool = False
         self._skip_in_chain: bool = False
@@ -133,7 +134,7 @@ class BaseAction(ABC):
 
     def _maybe_inject_last_result(self, kwargs: dict[str, Any]) -> dict[str, Any]:
         if self.inject_last_result and self.shared_context:
-            key = self.inject_last_result_as
+            key = self.inject_into
             if key in kwargs:
                 logger.warning("[%s] ⚠️ Overriding '%s' with last_result", self.name, key)
             kwargs = dict(kwargs)
@@ -173,7 +174,7 @@ class Action(BaseAction):
         kwargs (dict, optional): Static keyword arguments.
         hooks (HookManager, optional): Hook manager for lifecycle events.
         inject_last_result (bool, optional): Enable last_result injection.
-        inject_last_result_as (str, optional): Name of injected key.
+        inject_into (str, optional): Name of injected key.
         retry (bool, optional): Enable retry logic.
         retry_policy (RetryPolicy, optional): Retry settings.
     """
@@ -182,16 +183,22 @@ class Action(BaseAction):
         self,
         name: str,
         action: Callable[..., Any],
+        *,
         rollback: Callable[..., Any] | None = None,
         args: tuple[Any, ...] = (),
         kwargs: dict[str, Any] | None = None,
         hooks: HookManager | None = None,
         inject_last_result: bool = False,
-        inject_last_result_as: str = "last_result",
+        inject_into: str = "last_result",
         retry: bool = False,
         retry_policy: RetryPolicy | None = None,
     ) -> None:
-        super().__init__(name, hooks, inject_last_result, inject_last_result_as)
+        super().__init__(
+            name,
+            hooks=hooks,
+            inject_last_result=inject_last_result,
+            inject_into=inject_into,
+        )
         self.action = action
         self.rollback = rollback
         self.args = args
@@ -257,7 +264,7 @@ class Action(BaseAction):
             if context.result is not None:
                 logger.info("[%s] ✅ Recovered: %s", self.name, self.name)
                 return context.result
-            raise error
+            raise
         finally:
             context.stop_timer()
             await self.hooks.trigger(HookType.AFTER, context)
@@ -267,7 +274,7 @@ class Action(BaseAction):
     async def preview(self, parent: Tree | None = None):
         label = [f"[{OneColors.GREEN_b}]⚙ Action[/] '{self.name}'"]
         if self.inject_last_result:
-            label.append(f" [dim](injects '{self.inject_last_result_as}')[/dim]")
+            label.append(f" [dim](injects '{self.inject_into}')[/dim]")
         if self.retry_policy.enabled:
             label.append(
                 f"\n[dim]↻ Retries:[/] {self.retry_policy.max_retries}x, "
@@ -413,7 +420,7 @@ class ChainedAction(BaseAction, ActionListMixin):
         actions (list): List of actions or literals to execute.
         hooks (HookManager, optional): Hooks for lifecycle events.
         inject_last_result (bool, optional): Whether to inject last results into kwargs by default.
-        inject_last_result_as (str, optional): Key name for injection.
+        inject_into (str, optional): Key name for injection.
         auto_inject (bool, optional): Auto-enable injection for subsequent actions.
         return_list (bool, optional): Whether to return a list of all results. False returns the last result.
     """
@@ -422,13 +429,19 @@ class ChainedAction(BaseAction, ActionListMixin):
         self,
         name: str,
         actions: list[BaseAction | Any] | None = None,
+        *,
         hooks: HookManager | None = None,
         inject_last_result: bool = False,
-        inject_last_result_as: str = "last_result",
+        inject_into: str = "last_result",
         auto_inject: bool = False,
         return_list: bool = False,
     ) -> None:
-        super().__init__(name, hooks, inject_last_result, inject_last_result_as)
+        super().__init__(
+            name,
+            hooks=hooks,
+            inject_last_result=inject_last_result,
+            inject_into=inject_into,
+        )
         ActionListMixin.__init__(self)
         self.auto_inject = auto_inject
         self.return_list = return_list
@@ -482,9 +495,7 @@ class ChainedAction(BaseAction, ActionListMixin):
                 last_result = shared_context.last_result()
                 try:
                     if self.requires_io_injection() and last_result is not None:
-                        result = await prepared(
-                            **{prepared.inject_last_result_as: last_result}
-                        )
+                        result = await prepared(**{prepared.inject_into: last_result})
                     else:
                         result = await prepared(*args, **updated_kwargs)
                 except Exception as error:
@@ -559,7 +570,7 @@ class ChainedAction(BaseAction, ActionListMixin):
     async def preview(self, parent: Tree | None = None):
         label = [f"[{OneColors.CYAN_b}]⛓ ChainedAction[/] '{self.name}'"]
         if self.inject_last_result:
-            label.append(f" [dim](injects '{self.inject_last_result_as}')[/dim]")
+            label.append(f" [dim](injects '{self.inject_into}')[/dim]")
         tree = parent.add("".join(label)) if parent else Tree("".join(label))
         for action in self.actions:
             await action.preview(parent=tree)
@@ -603,18 +614,24 @@ class ActionGroup(BaseAction, ActionListMixin):
         actions (list): List of actions or literals to execute.
         hooks (HookManager, optional): Hooks for lifecycle events.
         inject_last_result (bool, optional): Whether to inject last results into kwargs by default.
-        inject_last_result_as (str, optional): Key name for injection.
+        inject_into (str, optional): Key name for injection.
     """
 
     def __init__(
         self,
         name: str,
         actions: list[BaseAction] | None = None,
+        *,
         hooks: HookManager | None = None,
         inject_last_result: bool = False,
-        inject_last_result_as: str = "last_result",
+        inject_into: str = "last_result",
     ):
-        super().__init__(name, hooks, inject_last_result, inject_last_result_as)
+        super().__init__(
+            name,
+            hooks=hooks,
+            inject_last_result=inject_last_result,
+            inject_into=inject_into,
+        )
         ActionListMixin.__init__(self)
         if actions:
             self.set_actions(actions)
@@ -694,7 +711,7 @@ class ActionGroup(BaseAction, ActionListMixin):
     async def preview(self, parent: Tree | None = None):
         label = [f"[{OneColors.MAGENTA_b}]⏩ ActionGroup (parallel)[/] '{self.name}'"]
         if self.inject_last_result:
-            label.append(f" [dim](receives '{self.inject_last_result_as}')[/dim]")
+            label.append(f" [dim](receives '{self.inject_into}')[/dim]")
         tree = parent.add("".join(label)) if parent else Tree("".join(label))
         actions = self.actions.copy()
         random.shuffle(actions)
@@ -726,22 +743,28 @@ class ProcessAction(BaseAction):
         hooks (HookManager, optional): Hook manager for lifecycle events.
         executor (ProcessPoolExecutor, optional): Custom executor if desired.
         inject_last_result (bool, optional): Inject last result into the function.
-        inject_last_result_as (str, optional): Name of the injected key.
+        inject_into (str, optional): Name of the injected key.
     """
 
     def __init__(
         self,
         name: str,
-        func: Callable[..., Any],
+        action: Callable[..., Any],
+        *,
         args: tuple = (),
         kwargs: dict[str, Any] | None = None,
         hooks: HookManager | None = None,
         executor: ProcessPoolExecutor | None = None,
         inject_last_result: bool = False,
-        inject_last_result_as: str = "last_result",
+        inject_into: str = "last_result",
     ):
-        super().__init__(name, hooks, inject_last_result, inject_last_result_as)
-        self.func = func
+        super().__init__(
+            name,
+            hooks=hooks,
+            inject_last_result=inject_last_result,
+            inject_into=inject_into,
+        )
+        self.action = action
         self.args = args
         self.kwargs = kwargs or {}
         self.executor = executor or ProcessPoolExecutor()
@@ -769,7 +792,7 @@ class ProcessAction(BaseAction):
         try:
             await self.hooks.trigger(HookType.BEFORE, context)
             result = await loop.run_in_executor(
-                self.executor, partial(self.func, *combined_args, **combined_kwargs)
+                self.executor, partial(self.action, *combined_args, **combined_kwargs)
             )
             context.result = result
             await self.hooks.trigger(HookType.ON_SUCCESS, context)
@@ -800,7 +823,7 @@ class ProcessAction(BaseAction):
             f"[{OneColors.DARK_YELLOW_b}]🧠 ProcessAction (new process)[/] '{self.name}'"
         ]
         if self.inject_last_result:
-            label.append(f" [dim](injects '{self.inject_last_result_as}')[/dim]")
+            label.append(f" [dim](injects '{self.inject_into}')[/dim]")
         if parent:
             parent.add("".join(label))
         else:
@@ -808,6 +831,6 @@ class ProcessAction(BaseAction):
 
     def __str__(self) -> str:
         return (
-            f"ProcessAction(name={self.name!r}, func={getattr(self.func, '__name__', repr(self.func))}, "
+            f"ProcessAction(name={self.name!r}, action={getattr(self.action, '__name__', repr(self.action))}, "
             f"args={self.args!r}, kwargs={self.kwargs!r})"
         )

falyx-0.1.21/falyx/action_factory.py

@@ -0,0 +1,95 @@
+from typing import Any
+
+from rich.tree import Tree
+
+from falyx.action import BaseAction
+from falyx.context import ExecutionContext
+from falyx.execution_registry import ExecutionRegistry as er
+from falyx.hook_manager import HookType
+from falyx.protocols import ActionFactoryProtocol
+from falyx.themes.colors import OneColors
+
+
+class ActionFactoryAction(BaseAction):
+    """
+    Dynamically creates and runs another Action at runtime using a factory function.
+
+    This is useful for generating context-specific behavior (e.g., dynamic HTTPActions)
+    where the structure of the next action depends on runtime values.
+
+    Args:
+        name (str): Name of the action.
+        factory (Callable): A function that returns a BaseAction given args/kwargs.
+        inject_last_result (bool): Whether to inject last_result into the factory.
+        inject_into (str): The name of the kwarg to inject last_result as.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        factory: ActionFactoryProtocol,
+        *,
+        inject_last_result: bool = False,
+        inject_into: str = "last_result",
+        preview_args: tuple[Any, ...] = (),
+        preview_kwargs: dict[str, Any] = {},
+    ):
+        super().__init__(
+            name=name,
+            inject_last_result=inject_last_result,
+            inject_into=inject_into,
+        )
+        self.factory = factory
+        self.preview_args = preview_args
+        self.preview_kwargs = preview_kwargs
+
+    async def _run(self, *args, **kwargs) -> Any:
+        updated_kwargs = self._maybe_inject_last_result(kwargs)
+        context = ExecutionContext(
+            name=f"{self.name} (factory)",
+            args=args,
+            kwargs=updated_kwargs,
+            action=self,
+        )
+        context.start_timer()
+        try:
+            await self.hooks.trigger(HookType.BEFORE, context)
+            generated_action = self.factory(*args, **updated_kwargs)
+            if not isinstance(generated_action, BaseAction):
+                raise TypeError(
+                    f"[{self.name}] Factory must return a BaseAction, got {type(generated_action).__name__}"
+                )
+            if self.shared_context:
+                generated_action.set_shared_context(self.shared_context)
+            if self.options_manager:
+                generated_action.set_options_manager(self.options_manager)
+            context.result = await generated_action(*args, **kwargs)
+            await self.hooks.trigger(HookType.ON_SUCCESS, context)
+            return context.result
+        except Exception as error:
+            context.exception = error
+            await self.hooks.trigger(HookType.ON_ERROR, context)
+            raise
+        finally:
+            context.stop_timer()
+            await self.hooks.trigger(HookType.AFTER, context)
+            await self.hooks.trigger(HookType.ON_TEARDOWN, context)
+            er.record(context)
+
+    async def preview(self, parent: Tree | None = None):
+        label = f"[{OneColors.CYAN_b}]🏗️ ActionFactory[/] '{self.name}'"
+        tree = parent.add(label) if parent else Tree(label)
+
+        try:
+            generated = self.factory(*self.preview_args, **self.preview_kwargs)
+            if isinstance(generated, BaseAction):
+                await generated.preview(parent=tree)
+            else:
+                tree.add(
+                    f"[{OneColors.DARK_RED}]⚠️ Factory did not return a BaseAction[/]"
+                )
+        except Exception as error:
+            tree.add(f"[{OneColors.DARK_RED}]⚠️ Preview failed: {error}[/]")
+
+        if not parent:
+            self.console.print(tree)

{falyx-0.1.19 → falyx-0.1.21}/falyx/bottom_bar.py

@@ -30,7 +30,7 @@ class BottomBar:
         key_validator: Callable[[str], bool] | None = None,
     ) -> None:
         self.columns = columns
-        self.console = Console()
+        self.console = Console(color_system="auto")
         self._named_items: dict[str, Callable[[], HTML]] = {}
         self._value_getters: dict[str, Callable[[], Any]] = CaseInsensitiveDict()
         self.toggle_keys: list[str] = []

{falyx-0.1.19 → falyx-0.1.21}/falyx/command.py

@@ -40,7 +40,7 @@ from falyx.retry_utils import enable_retries_recursively
 from falyx.themes.colors import OneColors
 from falyx.utils import _noop, confirm_async, ensure_async, logger
 
-console = Console()
+console = Console(color_system="auto")
 
 
 class Command(BaseModel):

{falyx-0.1.19 → falyx-0.1.21}/falyx/execution_registry.py

@@ -15,7 +15,7 @@ from falyx.utils import logger
 class ExecutionRegistry:
     _store_by_name: Dict[str, List[ExecutionContext]] = defaultdict(list)
     _store_all: List[ExecutionContext] = []
-    _console = Console(color_system="truecolor")
+    _console = Console(color_system="auto")
 
     @classmethod
     def record(cls, context: ExecutionContext):

{falyx-0.1.19 → falyx-0.1.21}/falyx/falyx.py

@@ -24,6 +24,7 @@ import logging
 import sys
 from argparse import Namespace
 from difflib import get_close_matches
+from enum import Enum
 from functools import cached_property
 from typing import Any, Callable
 
@@ -59,6 +60,13 @@ from falyx.utils import CaseInsensitiveDict, chunks, get_program_invocation, log
 from falyx.version import __version__
 
 
+class FalyxMode(str, Enum):
+    MENU = "menu"
+    RUN = "run"
+    PREVIEW = "preview"
+    RUN_ALL = "run-all"
+
+
 class Falyx:
     """
     Main menu controller for Falyx CLI applications.
@@ -102,12 +110,12 @@ class Falyx:
         register_all_hooks(): Register hooks across all commands and submenus.
         debug_hooks(): Log hook registration for debugging.
         build_default_table(): Construct the standard Rich table layout.
-
     """
 
     def __init__(
         self,
         title: str | Markdown = "Menu",
+        *,
         prompt: str | AnyFormattedText = "> ",
         columns: int = 3,
         bottom_bar: BottomBar | str | Callable[[], Any] | None = None,
@@ -135,7 +143,7 @@ class Falyx:
         self.help_command: Command | None = (
             self._get_help_command() if include_help_command else None
         )
-        self.console: Console = Console(color_system="truecolor", theme=get_nord_theme())
+        self.console: Console = Console(color_system="auto", theme=get_nord_theme())
         self.welcome_message: str | Markdown | dict[str, Any] = welcome_message
         self.exit_message: str | Markdown | dict[str, Any] = exit_message
         self.hooks: HookManager = HookManager()
@@ -149,6 +157,7 @@ class Falyx:
         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
 
     def validate_options(
         self,
@@ -272,6 +281,11 @@ class Falyx:
             )
 
         self.console.print(table, justify="center")
+        if self.mode == FalyxMode.MENU:
+            self.console.print(
+                f"📦 Tip: Type '[{OneColors.LIGHT_YELLOW}]?[KEY][/]' to preview a command before running it.\n",
+                justify="center",
+            )
 
     def _get_help_command(self) -> Command:
         """Returns the help command for the menu."""
@@ -329,7 +343,8 @@ class Falyx:
         error_message = " ".join(message_lines)
 
         def validator(text):
-            return True if self.get_command(text, from_validate=True) else False
+            _, choice = self.get_command(text, from_validate=True)
+            return True if choice else False
 
         return Validator.from_callable(
             validator,
@@ -534,7 +549,7 @@ class Falyx:
         )
 
     def add_submenu(
-        self, key: str, description: str, submenu: "Falyx", style: str = OneColors.CYAN
+        self, key: str, description: str, submenu: "Falyx", *, style: str = OneColors.CYAN
     ) -> None:
         """Adds a submenu to the menu."""
         if not isinstance(submenu, Falyx):
@@ -553,6 +568,7 @@ class Falyx:
         key: str,
         description: str,
         action: BaseAction | Callable[[], Any],
+        *,
         args: tuple = (),
         kwargs: dict[str, Any] = {},
         hidden: bool = False,
@@ -668,17 +684,25 @@ class Falyx:
         else:
             return self.build_default_table()
 
-    def get_command(self, choice: str, from_validate=False) -> Command | None:
+    def parse_preview_command(self, input_str: str) -> tuple[bool, str]:
+        if input_str.startswith("?"):
+            return True, input_str[1:].strip()
+        return False, input_str.strip()
+
+    def get_command(
+        self, choice: str, from_validate=False
+    ) -> tuple[bool, Command | None]:
         """Returns the selected command based on user input. Supports keys, aliases, and abbreviations."""
+        is_preview, choice = self.parse_preview_command(choice)
         choice = choice.upper()
         name_map = self._name_map
 
         if choice in name_map:
-            return name_map[choice]
+            return is_preview, name_map[choice]
 
         prefix_matches = [cmd for key, cmd in name_map.items() if key.startswith(choice)]
         if len(prefix_matches) == 1:
-            return prefix_matches[0]
+            return is_preview, prefix_matches[0]
 
         fuzzy_matches = get_close_matches(choice, list(name_map.keys()), n=3, cutoff=0.7)
         if fuzzy_matches:
@@ -694,7 +718,7 @@ class Falyx:
                 self.console.print(
                     f"[{OneColors.LIGHT_YELLOW}]⚠️ Unknown command '{choice}'[/]"
                 )
-        return None
+        return is_preview, None
 
     def _create_context(self, selected_command: Command) -> ExecutionContext:
         """Creates a context dictionary for the selected command."""
@@ -718,11 +742,16 @@ class Falyx:
     async def process_command(self) -> bool:
         """Processes the action of the selected command."""
         choice = await self.prompt_session.prompt_async()
-        selected_command = self.get_command(choice)
+        is_preview, selected_command = self.get_command(choice)
         if not selected_command:
             logger.info(f"Invalid command '{choice}'.")
             return True
 
+        if is_preview:
+            logger.info(f"Preview command '{selected_command.key}' selected.")
+            await selected_command.preview()
+            return True
+
         if selected_command.requires_input:
             program = get_program_invocation()
             self.console.print(
@@ -759,7 +788,7 @@ class Falyx:
     async def run_key(self, command_key: str, return_context: bool = False) -> Any:
         """Run a command by key without displaying the menu (non-interactive mode)."""
         self.debug_hooks()
-        selected_command = self.get_command(command_key)
+        _, selected_command = self.get_command(command_key)
         self.last_run_command = selected_command
 
         if not selected_command:
@@ -899,7 +928,8 @@ class Falyx:
             sys.exit(0)
 
         if self.cli_args.command == "preview":
-            command = self.get_command(self.cli_args.name)
+            self.mode = FalyxMode.PREVIEW
+            _, command = self.get_command(self.cli_args.name)
             if not command:
                 self.console.print(
                     f"[{OneColors.DARK_RED}]❌ Command '{self.cli_args.name}' not found.[/]"
@@ -912,7 +942,8 @@ class Falyx:
             sys.exit(0)
 
         if self.cli_args.command == "run":
-            command = self.get_command(self.cli_args.name)
+            self.mode = FalyxMode.RUN
+            _, command = self.get_command(self.cli_args.name)
             if not command:
                 self.console.print(
                     f"[{OneColors.DARK_RED}]❌ Command '{self.cli_args.name}' not found.[/]"
@@ -927,6 +958,7 @@ class Falyx:
             sys.exit(0)
 
         if self.cli_args.command == "run-all":
+            self.mode = FalyxMode.RUN_ALL
             matching = [
                 cmd
                 for cmd in self.commands.values()

{falyx-0.1.19 → falyx-0.1.21}/falyx/http_action.py

@@ -56,7 +56,7 @@ class HTTPAction(Action):
         data (Any, optional): Raw data or form-encoded body.
         hooks (HookManager, optional): Hook manager for lifecycle events.
         inject_last_result (bool): Enable last_result injection.
-        inject_last_result_as (str): Name of injected key.
+        inject_into (str): Name of injected key.
         retry (bool): Enable retry logic.
         retry_policy (RetryPolicy): Retry settings.
     """
@@ -74,7 +74,7 @@ class HTTPAction(Action):
         data: Any = None,
         hooks=None,
         inject_last_result: bool = False,
-        inject_last_result_as: str = "last_result",
+        inject_into: str = "last_result",
         retry: bool = False,
         retry_policy=None,
     ):
@@ -92,7 +92,7 @@ class HTTPAction(Action):
             kwargs={},
             hooks=hooks,
             inject_last_result=inject_last_result,
-            inject_last_result_as=inject_last_result_as,
+            inject_into=inject_into,
             retry=retry,
             retry_policy=retry_policy,
         )
@@ -138,7 +138,7 @@ class HTTPAction(Action):
             f"\n[dim]URL:[/] {self.url}",
         ]
         if self.inject_last_result:
-            label.append(f"\n[dim]Injects:[/] '{self.inject_last_result_as}'")
+            label.append(f"\n[dim]Injects:[/] '{self.inject_into}'")
         if self.retry_policy and self.retry_policy.enabled:
             label.append(
                 f"\n[dim]↻ Retries:[/] {self.retry_policy.max_retries}x, "

{falyx-0.1.19 → falyx-0.1.21}/falyx/io_action.py

@@ -20,7 +20,6 @@ import subprocess
 import sys
 from typing import Any
 
-from rich.console import Console
 from rich.tree import Tree
 
 from falyx.action import BaseAction
@@ -31,8 +30,6 @@ from falyx.hook_manager import HookManager, HookType
 from falyx.themes.colors import OneColors
 from falyx.utils import logger
 
-console = Console()
-
 
 class BaseIOAction(BaseAction):
     """
@@ -83,7 +80,7 @@ class BaseIOAction(BaseAction):
         raise NotImplementedError
 
     async def _resolve_input(self, kwargs: dict[str, Any]) -> str | bytes:
-        last_result = kwargs.pop(self.inject_last_result_as, None)
+        last_result = kwargs.pop(self.inject_into, None)
 
         data = await self._read_stdin()
         if data:
@@ -168,26 +165,11 @@ class BaseIOAction(BaseAction):
     async def preview(self, parent: Tree | None = None):
         label = [f"[{OneColors.GREEN_b}]⚙ IOAction[/] '{self.name}'"]
         if self.inject_last_result:
-            label.append(f" [dim](injects '{self.inject_last_result_as}')[/dim]")
+            label.append(f" [dim](injects '{self.inject_into}')[/dim]")
         if parent:
             parent.add("".join(label))
         else:
-            console.print(Tree("".join(label)))
-
-
-class UppercaseIO(BaseIOAction):
-    def from_input(self, raw: str | bytes) -> str:
-        if not isinstance(raw, (str, bytes)):
-            raise TypeError(
-                f"{self.name} expected str or bytes input, got {type(raw).__name__}"
-            )
-        return raw.strip() if isinstance(raw, str) else raw.decode("utf-8").strip()
-
-    async def _run(self, parsed_input: str, *args, **kwargs) -> str:
-        return parsed_input.upper()
-
-    def to_output(self, data: str) -> str:
-        return data + "\n"
+            self.console.print(Tree("".join(label)))
 
 
 class ShellAction(BaseIOAction):
@@ -243,45 +225,13 @@ class ShellAction(BaseIOAction):
     async def preview(self, parent: Tree | None = None):
         label = [f"[{OneColors.GREEN_b}]⚙ ShellAction[/] '{self.name}'"]
         if self.inject_last_result:
-            label.append(f" [dim](injects '{self.inject_last_result_as}')[/dim]")
+            label.append(f" [dim](injects '{self.inject_into}')[/dim]")
         if parent:
             parent.add("".join(label))
         else:
-            console.print(Tree("".join(label)))
+            self.console.print(Tree("".join(label)))
 
     def __str__(self):
         return (
             f"ShellAction(name={self.name!r}, command_template={self.command_template!r})"
         )
-
-
-class GrepAction(BaseIOAction):
-    def __init__(self, name: str, pattern: str, **kwargs):
-        super().__init__(name=name, **kwargs)
-        self.pattern = pattern
-
-    def from_input(self, raw: str | bytes) -> str:
-        if not isinstance(raw, (str, bytes)):
-            raise TypeError(
-                f"{self.name} expected str or bytes input, got {type(raw).__name__}"
-            )
-        return raw.strip() if isinstance(raw, str) else raw.decode("utf-8").strip()
-
-    async def _run(self, parsed_input: str) -> str:
-        command = ["grep", "-n", self.pattern]
-        process = subprocess.Popen(
-            command,
-            stdin=subprocess.PIPE,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            text=True,
-        )
-        stdout, stderr = process.communicate(input=parsed_input)
-        if process.returncode == 1:
-            return ""
-        if process.returncode != 0:
-            raise RuntimeError(stderr.strip())
-        return stdout.strip()
-
-    def to_output(self, result: str) -> str:
-        return result

{falyx-0.1.19 → falyx-0.1.21}/falyx/menu_action.py

@@ -45,7 +45,9 @@ class MenuOptionMap(CaseInsensitiveDict):
     RESERVED_KEYS = {"Q", "B"}
 
     def __init__(
-        self, options: dict[str, MenuOption] | None = None, allow_reserved: bool = False
+        self,
+        options: dict[str, MenuOption] | None = None,
+        allow_reserved: bool = False,
     ):
         super().__init__()
         self.allow_reserved = allow_reserved
@@ -101,7 +103,7 @@ class MenuAction(BaseAction):
         prompt_message: str = "Select > ",
         default_selection: str = "",
         inject_last_result: bool = False,
-        inject_last_result_as: str = "last_result",
+        inject_into: str = "last_result",
         console: Console | None = None,
         prompt_session: PromptSession | None = None,
         never_prompt: bool = False,
@@ -111,7 +113,7 @@ class MenuAction(BaseAction):
         super().__init__(
             name,
             inject_last_result=inject_last_result,
-            inject_last_result_as=inject_last_result_as,
+            inject_into=inject_into,
             never_prompt=never_prompt,
         )
         self.menu_options = menu_options

falyx-0.1.21/falyx/protocols.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from falyx.action import BaseAction
+
+
+class ActionFactoryProtocol(Protocol):
+    def __call__(self, *args: Any, **kwargs: Any) -> BaseAction: ...

falyx-0.1.21/falyx/select_file_action.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import csv
+import json
+import xml.etree.ElementTree as ET
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import toml
+import yaml
+from prompt_toolkit import PromptSession
+from rich.console import Console
+from rich.tree import Tree
+
+from falyx.action import BaseAction
+from falyx.context import ExecutionContext
+from falyx.execution_registry import ExecutionRegistry as er
+from falyx.hook_manager import HookType
+from falyx.selection import (
+    SelectionOption,
+    prompt_for_selection,
+    render_selection_dict_table,
+)
+from falyx.themes.colors import OneColors
+from falyx.utils import logger
+
+
+class FileReturnType(Enum):
+    TEXT = "text"
+    PATH = "path"
+    JSON = "json"
+    TOML = "toml"
+    YAML = "yaml"
+    CSV = "csv"
+    XML = "xml"
+
+
+class SelectFileAction(BaseAction):
+    """
+    SelectFileAction allows users to select a file from a directory and return:
+    - file content (as text, JSON, CSV, etc.)
+    - or the file path itself.
+
+    Supported formats: text, json, yaml, toml, csv, xml.
+
+    Useful for:
+    - dynamically loading config files
+    - interacting with user-selected data
+    - chaining file contents into workflows
+
+    Args:
+        name (str): Name of the action.
+        directory (Path | str): Where to search for files.
+        title (str): Title of the selection menu.
+        columns (int): Number of columns in the selection menu.
+        prompt_message (str): Message to display when prompting for selection.
+        style (str): Style for the selection options.
+        suffix_filter (str | None): Restrict to certain file types.
+        return_type (FileReturnType): What to return (path, content, parsed).
+        console (Console | None): Console instance for output.
+        prompt_session (PromptSession | None): Prompt session for user input.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        directory: Path | str = ".",
+        *,
+        title: str = "Select a file",
+        columns: int = 3,
+        prompt_message: str = "Choose > ",
+        style: str = OneColors.WHITE,
+        suffix_filter: str | None = None,
+        return_type: FileReturnType = FileReturnType.PATH,
+        console: Console | None = None,
+        prompt_session: PromptSession | None = None,
+    ):
+        super().__init__(name)
+        self.directory = Path(directory).resolve()
+        self.title = title
+        self.columns = columns
+        self.prompt_message = prompt_message
+        self.suffix_filter = suffix_filter
+        self.style = style
+        self.return_type = return_type
+        self.console = console or Console(color_system="auto")
+        self.prompt_session = prompt_session or PromptSession()
+
+    def get_options(self, files: list[Path]) -> dict[str, SelectionOption]:
+        value: Any
+        options = {}
+        for index, file in enumerate(files):
+            try:
+                if self.return_type == FileReturnType.TEXT:
+                    value = file.read_text(encoding="UTF-8")
+                elif self.return_type == FileReturnType.PATH:
+                    value = file
+                elif self.return_type == FileReturnType.JSON:
+                    value = json.loads(file.read_text(encoding="UTF-8"))
+                elif self.return_type == FileReturnType.TOML:
+                    value = toml.loads(file.read_text(encoding="UTF-8"))
+                elif self.return_type == FileReturnType.YAML:
+                    value = yaml.safe_load(file.read_text(encoding="UTF-8"))
+                elif self.return_type == FileReturnType.CSV:
+                    with open(file, newline="", encoding="UTF-8") as csvfile:
+                        reader = csv.reader(csvfile)
+                        value = list(reader)
+                elif self.return_type == FileReturnType.XML:
+                    tree = ET.parse(file, parser=ET.XMLParser(encoding="UTF-8"))
+                    root = tree.getroot()
+                    value = ET.tostring(root, encoding="unicode")
+                else:
+                    raise ValueError(f"Unsupported return type: {self.return_type}")
+
+                options[str(index)] = SelectionOption(
+                    description=file.name, value=value, style=self.style
+                )
+            except Exception as error:
+                logger.warning("[ERROR] Failed to parse %s: %s", file.name, error)
+        return options
+
+    async def _run(self, *args, **kwargs) -> Any:
+        context = ExecutionContext(name=self.name, args=args, kwargs=kwargs, action=self)
+        context.start_timer()
+        try:
+            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)
+            ]
+            if not files:
+                raise FileNotFoundError("No files found in directory.")
+
+            options = self.get_options(files)
+
+            table = render_selection_dict_table(self.title, options, self.columns)
+
+            key = await prompt_for_selection(
+                options.keys(),
+                table,
+                console=self.console,
+                prompt_session=self.prompt_session,
+                prompt_message=self.prompt_message,
+            )
+
+            result = options[key].value
+            context.result = result
+            await self.hooks.trigger(HookType.ON_SUCCESS, context)
+            return result
+        except Exception as error:
+            context.exception = error
+            await self.hooks.trigger(HookType.ON_ERROR, context)
+            raise
+        finally:
+            context.stop_timer()
+            await self.hooks.trigger(HookType.AFTER, context)
+            await self.hooks.trigger(HookType.ON_TEARDOWN, context)
+            er.record(context)
+
+    async def preview(self, parent: Tree | None = None):
+        label = f"[{OneColors.GREEN}]📁 SelectFilesAction[/] '{self.name}'"
+        tree = parent.add(label) if parent else Tree(label)
+
+        tree.add(f"[dim]Directory:[/] {str(self.directory)}")
+        tree.add(f"[dim]Suffix filter:[/] {self.suffix_filter or 'None'}")
+        tree.add(f"[dim]Return type:[/] {self.return_type}")
+        tree.add(f"[dim]Prompt:[/] {self.prompt_message}")
+        tree.add(f"[dim]Columns:[/] {self.columns}")
+        try:
+            files = list(self.directory.iterdir())
+            if self.suffix_filter:
+                files = [f for f in files if f.suffix == self.suffix_filter]
+            sample = files[:10]
+            file_list = tree.add("[dim]Files:[/]")
+            for f in sample:
+                file_list.add(f"[dim]{f.name}[/]")
+            if len(files) > 10:
+                file_list.add(f"[dim]... ({len(files) - 10} more)[/]")
+        except Exception as error:
+            tree.add(f"[bold red]⚠️ Error scanning directory: {error}[/]")
+
+        if not parent:
+            self.console.print(tree)
+
+    def __str__(self) -> str:
+        return (
+            f"SelectFilesAction(name={self.name!r}, dir={str(self.directory)!r}, "
+            f"suffix_filter={self.suffix_filter!r}, return_type={self.return_type})"
+        )

{falyx-0.1.19 → falyx-0.1.21}/falyx/selection_action.py

@@ -33,7 +33,7 @@ class SelectionAction(BaseAction):
         prompt_message: str = "Select > ",
         default_selection: str = "",
         inject_last_result: bool = False,
-        inject_last_result_as: str = "last_result",
+        inject_into: str = "last_result",
         return_key: bool = False,
         console: Console | None = None,
         prompt_session: PromptSession | None = None,
@@ -43,7 +43,7 @@ class SelectionAction(BaseAction):
         super().__init__(
             name,
             inject_last_result=inject_last_result,
-            inject_last_result_as=inject_last_result_as,
+            inject_into=inject_into,
             never_prompt=never_prompt,
         )
         self.selections: list[str] | CaseInsensitiveDict = selections

falyx-0.1.21/falyx/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.21"

{falyx-0.1.19 → falyx-0.1.21}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "falyx"
-version = "0.1.19"
+version = "0.1.21"
 description = "Reliable and introspectable async CLI action framework."
 authors = ["Roland Thomas Jr <roland@rtj.dev>"]
 license = "MIT"

falyx-0.1.19/falyx/action_factory.py

@@ -1,23 +0,0 @@
-from typing import Callable
-
-from falyx.action import BaseAction
-
-
-class ActionFactoryAction(BaseAction):
-    def __init__(
-        self,
-        name: str,
-        factory: Callable[[dict], BaseAction],
-        *,
-        inject_last_result: bool = False,
-        inject_last_result_as: str = "last_result",
-    ):
-        super().__init__(name, inject_last_result=inject_last_result, inject_last_result_as=inject_last_result_as)
-        self.factory = factory
-
-    async def _run(self, *args, **kwargs) -> BaseAction:
-        kwargs = self._maybe_inject_last_result(kwargs)
-        action = self.factory(kwargs)
-        if not isinstance(action, BaseAction):
-            raise TypeError(f"[{self.name}] Factory did not return a valid BaseAction.")
-        return action

falyx-0.1.19/falyx/select_files_action.py

@@ -1,68 +0,0 @@
-
-class SelectFilesAction(BaseAction):
-    def __init__(
-        self,
-        name: str,
-        directory: Path | str = ".",
-        title: str = "Select a file",
-        prompt_message: str = "Choose > ",
-        style: str = OneColors.WHITE,
-        suffix_filter: str | None = None,
-        return_path: bool = True,
-        console: Console | None = None,
-        prompt_session: PromptSession | None = None,
-    ):
-        super().__init__(name)
-        self.directory = Path(directory).resolve()
-        self.title = title
-        self.prompt_message = prompt_message
-        self.suffix_filter = suffix_filter
-        self.style = style
-        self.return_path = return_path
-        self.console = console or Console()
-        self.prompt_session = prompt_session or PromptSession()
-
-    async def _run(self, *args, **kwargs) -> Any:
-        context = ExecutionContext(name=self.name, args=args, kwargs=kwargs, action=self)
-        context.start_timer()
-        try:
-            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)
-            ]
-            if not files:
-                raise FileNotFoundError("No files found in directory.")
-
-            options = {
-                str(i): SelectionOption(
-                    f.name, f if self.return_path else f.read_text(), self.style
-                )
-                for i, f in enumerate(files)
-            }
-            table = render_selection_dict_table(self.title, options)
-
-            key = await prompt_for_selection(
-                options.keys(),
-                table,
-                console=self.console,
-                prompt_session=self.prompt_session,
-                prompt_message=self.prompt_message,
-            )
-
-            result = options[key].value
-            context.result = result
-            await self.hooks.trigger(HookType.ON_SUCCESS, context)
-            return result
-        except Exception as error:
-            context.exception = error
-            await self.hooks.trigger(HookType.ON_ERROR, context)
-            raise
-        finally:
-            context.stop_timer()
-            await self.hooks.trigger(HookType.AFTER, context)
-            await self.hooks.trigger(HookType.ON_TEARDOWN, context)
-            er.record(context)

falyx-0.1.19/falyx/version.py

@@ -1 +0,0 @@
-__version__ = "0.1.19"