falyx 0.1.51__tar.gz → 0.1.53__tar.gz

{falyx-0.1.51 → falyx-0.1.53}/PKG-INFO

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

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/__init__.py

@@ -8,11 +8,11 @@ Licensed under the MIT License. See LICENSE file for details.
 from .action import Action
 from .action_factory import ActionFactoryAction
 from .action_group import ActionGroup
-from .base import BaseAction
+from .base_action import BaseAction
 from .chained_action import ChainedAction
 from .fallback_action import FallbackAction
 from .http_action import HTTPAction
-from .io_action import BaseIOAction, ShellAction
+from .io_action import BaseIOAction
 from .literal_input_action import LiteralInputAction
 from .menu_action import MenuAction
 from .process_action import ProcessAction
@@ -20,6 +20,7 @@ from .process_pool_action import ProcessPoolAction
 from .prompt_menu_action import PromptMenuAction
 from .select_file_action import SelectFileAction
 from .selection_action import SelectionAction
+from .shell_action import ShellAction
 from .signal_action import SignalAction
 from .user_input_action import UserInputAction
 

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/action.py

@@ -6,7 +6,7 @@ from typing import Any, Callable
 
 from rich.tree import Tree
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookManager, HookType

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/action_factory.py

@@ -4,7 +4,7 @@ from typing import Any, Callable
 
 from rich.tree import Tree
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/action_group.py

@@ -1,11 +1,13 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""action_group.py"""
 import asyncio
 import random
-from typing import Any, Callable
+from typing import Any, Callable, Sequence
 
 from rich.tree import Tree
 
 from falyx.action.action import Action
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.action.mixins import ActionListMixin
 from falyx.context import ExecutionContext, SharedContext
 from falyx.execution_registry import ExecutionRegistry as er
@@ -52,7 +54,7 @@ class ActionGroup(BaseAction, ActionListMixin):
     def __init__(
         self,
         name: str,
-        actions: list[BaseAction] | None = None,
+        actions: Sequence[BaseAction | Callable[..., Any]] | None = None,
         *,
         hooks: HookManager | None = None,
         inject_last_result: bool = False,
@@ -68,7 +70,7 @@ class ActionGroup(BaseAction, ActionListMixin):
         if actions:
             self.set_actions(actions)
 
-    def _wrap_if_needed(self, action: BaseAction | Any) -> BaseAction:
+    def _wrap_if_needed(self, action: BaseAction | Callable[..., Any]) -> BaseAction:
         if isinstance(action, BaseAction):
             return action
         elif callable(action):
@@ -79,12 +81,18 @@ class ActionGroup(BaseAction, ActionListMixin):
                 f"{type(action).__name__}"
             )
 
-    def add_action(self, action: BaseAction | Any) -> None:
+    def add_action(self, action: BaseAction | Callable[..., Any]) -> None:
         action = self._wrap_if_needed(action)
         super().add_action(action)
         if hasattr(action, "register_teardown") and callable(action.register_teardown):
             action.register_teardown(self.hooks)
 
+    def set_actions(self, actions: Sequence[BaseAction | Callable[..., Any]]) -> None:
+        """Replaces the current action list with a new one."""
+        self.actions.clear()
+        for action in actions:
+            self.add_action(action)
+
     def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
         arg_defs = same_argument_definitions(self.actions)
         if arg_defs:

falyx-0.1.51/falyx/action/types.py → falyx-0.1.53/falyx/action/action_types.py

@@ -1,9 +1,11 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""types.py"""
 from __future__ import annotations
 
 from enum import Enum
 
 
-class FileReturnType(Enum):
+class FileType(Enum):
     """Enum for file return types."""
 
     TEXT = "text"
@@ -26,7 +28,7 @@ class FileReturnType(Enum):
         return aliases.get(value, value)
 
     @classmethod
-    def _missing_(cls, value: object) -> FileReturnType:
+    def _missing_(cls, value: object) -> FileType:
         if isinstance(value, str):
             normalized = value.lower()
             alias = cls._get_alias(normalized)
@@ -34,7 +36,7 @@ class FileReturnType(Enum):
                 if member.value == alias:
                     return member
         valid = ", ".join(member.value for member in cls)
-        raise ValueError(f"Invalid FileReturnType: '{value}'. Must be one of: {valid}")
+        raise ValueError(f"Invalid FileType: '{value}'. Must be one of: {valid}")
 
 
 class SelectionReturnType(Enum):

falyx-0.1.51/falyx/action/base.py → falyx-0.1.53/falyx/action/base_action.py

@@ -1,5 +1,5 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""base.py
+"""base_action.py
 
 Core action system for Falyx.
 

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/chained_action.py

@@ -1,11 +1,13 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""chained_action.py"""
 from __future__ import annotations
 
-from typing import Any, Callable
+from typing import Any, Callable, Sequence
 
 from rich.tree import Tree
 
 from falyx.action.action import Action
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.action.fallback_action import FallbackAction
 from falyx.action.literal_input_action import LiteralInputAction
 from falyx.action.mixins import ActionListMixin
@@ -45,7 +47,7 @@ class ChainedAction(BaseAction, ActionListMixin):
     def __init__(
         self,
         name: str,
-        actions: list[BaseAction | Any] | None = None,
+        actions: Sequence[BaseAction | Callable[..., Any]] | None = None,
         *,
         hooks: HookManager | None = None,
         inject_last_result: bool = False,
@@ -65,7 +67,7 @@ class ChainedAction(BaseAction, ActionListMixin):
         if actions:
             self.set_actions(actions)
 
-    def _wrap_if_needed(self, action: BaseAction | Any) -> BaseAction:
+    def _wrap_if_needed(self, action: BaseAction | Callable[..., Any]) -> BaseAction:
         if isinstance(action, BaseAction):
             return action
         elif callable(action):
@@ -73,7 +75,7 @@ class ChainedAction(BaseAction, ActionListMixin):
         else:
             return LiteralInputAction(action)
 
-    def add_action(self, action: BaseAction | Any) -> None:
+    def add_action(self, action: BaseAction | Callable[..., Any]) -> None:
         action = self._wrap_if_needed(action)
         if self.actions and self.auto_inject and not action.inject_last_result:
             action.inject_last_result = True
@@ -81,6 +83,12 @@ class ChainedAction(BaseAction, ActionListMixin):
         if hasattr(action, "register_teardown") and callable(action.register_teardown):
             action.register_teardown(self.hooks)
 
+    def set_actions(self, actions: Sequence[BaseAction | Callable[..., Any]]) -> None:
+        """Replaces the current action list with a new one."""
+        self.actions.clear()
+        for action in actions:
+            self.add_action(action)
+
     def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
         if self.actions:
             return self.actions[0].get_infer_target()

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/fallback_action.py

@@ -1,3 +1,5 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""fallback_action.py"""
 from functools import cached_property
 from typing import Any
 

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/io_action.py

@@ -16,19 +16,15 @@ Common usage includes shell-like filters, input transformers, or any tool that
 needs to consume input from another process or pipeline.
 """
 import asyncio
-import shlex
-import subprocess
 import sys
 from typing import Any, Callable
 
 from rich.tree import Tree
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext
-from falyx.exceptions import FalyxError
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookManager, HookType
-from falyx.logger import logger
 from falyx.themes import OneColors
 
 
@@ -171,92 +167,3 @@ class BaseIOAction(BaseAction):
             parent.add("".join(label))
         else:
             self.console.print(Tree("".join(label)))
-
-
-class ShellAction(BaseIOAction):
-    """
-    ShellAction wraps a shell command template for CLI pipelines.
-
-    This Action takes parsed input (from stdin, literal, or last_result),
-    substitutes it into the provided shell command template, and executes
-    the command asynchronously using subprocess.
-
-    Designed for quick integration with shell tools like `grep`, `ping`, `jq`, etc.
-
-    ⚠️ Security Warning:
-    By default, ShellAction uses `shell=True`, which can be dangerous with
-    unsanitized input. To mitigate this, set `safe_mode=True` to use `shell=False`
-    with `shlex.split()`.
-
-    Features:
-    - Automatically handles input parsing (str/bytes)
-    - `safe_mode=True` disables shell interpretation and runs with `shell=False`
-    - 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
-
-    Args:
-        name (str): Name of the action.
-        command_template (str): Shell command to execute. Must include `{}` to include
-                                input. If no placeholder is present, the input is not
-                                included.
-        safe_mode (bool): If True, runs with `shell=False` using shlex parsing
-                          (default: False).
-    """
-
-    def __init__(
-        self, name: str, command_template: str, safe_mode: bool = False, **kwargs
-    ):
-        super().__init__(name=name, **kwargs)
-        self.command_template = command_template
-        self.safe_mode = safe_mode
-
-    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()
-
-    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
-        if sys.stdin.isatty():
-            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
-        command = self.command_template.format(parsed_input)
-        if self.safe_mode:
-            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(
-                command, shell=True, text=True, capture_output=True, check=True
-            )
-        if result.returncode != 0:
-            raise RuntimeError(result.stderr.strip())
-        return result.stdout.strip()
-
-    def to_output(self, result: str) -> str:
-        return result
-
-    async def preview(self, parent: Tree | None = None):
-        label = [f"[{OneColors.GREEN_b}]⚙ ShellAction[/] '{self.name}'"]
-        label.append(f"\n[dim]Template:[/] {self.command_template}")
-        label.append(
-            f"\n[dim]Safe mode:[/] {'Enabled' if self.safe_mode else 'Disabled'}"
-        )
-        if self.inject_last_result:
-            label.append(f" [dim](injects '{self.inject_into}')[/dim]")
-        tree = parent.add("".join(label)) if parent else Tree("".join(label))
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self):
-        return (
-            f"ShellAction(name={self.name!r}, command_template={self.command_template!r},"
-            f" safe_mode={self.safe_mode})"
-        )

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/literal_input_action.py

@@ -1,3 +1,5 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""literal_input_action.py"""
 from __future__ import annotations
 
 from functools import cached_property

falyx-0.1.53/falyx/action/load_file_action.py

@@ -0,0 +1,28 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""load_file_action.py"""
+from pathlib import Path
+
+from rich.tree import Tree
+
+from falyx.action.base_action import BaseAction
+
+
+class LoadFileAction(BaseAction):
+    """ """
+
+    def __init__(self, name: str, file_path: str):
+        super().__init__(name=name)
+        self.file_path = file_path
+
+    def get_infer_target(self) -> tuple[None, None]:
+        return None, None
+
+    async def _run(self, *args, **kwargs):
+        raise NotImplementedError(
+            "LoadFileAction is not finished yet... Use primatives instead..."
+        )
+
+    async def preview(self, parent: Tree | None = None): ...
+
+    def __str__(self) -> str:
+        return f"LoadFileAction(file_path={self.file_path})"

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/menu_action.py

@@ -7,7 +7,7 @@ from rich.console import Console
 from rich.table import Table
 from rich.tree import Tree
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/mixins.py

@@ -1,4 +1,8 @@
-from falyx.action.base import BaseAction
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""mixins.py"""
+from typing import Sequence
+
+from falyx.action.base_action import BaseAction
 
 
 class ActionListMixin:
@@ -7,7 +11,7 @@ class ActionListMixin:
     def __init__(self) -> None:
         self.actions: list[BaseAction] = []
 
-    def set_actions(self, actions: list[BaseAction]) -> None:
+    def set_actions(self, actions: Sequence[BaseAction]) -> None:
         """Replaces the current action list with a new one."""
         self.actions.clear()
         for action in actions:

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/process_action.py

@@ -1,3 +1,5 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""process_action.py"""
 from __future__ import annotations
 
 import asyncio
@@ -7,7 +9,7 @@ from typing import Any, Callable
 
 from rich.tree import Tree
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookManager, HookType

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/process_pool_action.py

@@ -1,3 +1,5 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""process_pool_action.py"""
 from __future__ import annotations
 
 import asyncio
@@ -9,7 +11,7 @@ from typing import Any, Callable
 
 from rich.tree import Tree
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext, SharedContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookManager, HookType

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/prompt_menu_action.py

@@ -7,7 +7,7 @@ from prompt_toolkit.formatted_text import FormattedText, merge_formatted_text
 from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType

falyx-0.1.53/falyx/action/save_file_action.py

@@ -0,0 +1,28 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""save_file_action.py"""
+from pathlib import Path
+
+from rich.tree import Tree
+
+from falyx.action.base_action import BaseAction
+
+
+class SaveFileAction(BaseAction):
+    """ """
+
+    def __init__(self, name: str, file_path: str):
+        super().__init__(name=name)
+        self.file_path = file_path
+
+    def get_infer_target(self) -> tuple[None, None]:
+        return None, None
+
+    async def _run(self, *args, **kwargs):
+        raise NotImplementedError(
+            "SaveFileAction is not finished yet... Use primitives instead..."
+        )
+
+    async def preview(self, parent: Tree | None = None): ...
+
+    def __str__(self) -> str:
+        return f"SaveFileAction(file_path={self.file_path})"

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/select_file_action.py

@@ -14,8 +14,8 @@ from prompt_toolkit import PromptSession
 from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action.base import BaseAction
-from falyx.action.types import FileReturnType
+from falyx.action.action_types import FileType
+from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
@@ -50,7 +50,7 @@ class SelectFileAction(BaseAction):
         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).
+        return_type (FileType): What to return (path, content, parsed).
         console (Console | None): Console instance for output.
         prompt_session (PromptSession | None): Prompt session for user input.
     """
@@ -65,7 +65,7 @@ class SelectFileAction(BaseAction):
         prompt_message: str = "Choose > ",
         style: str = OneColors.WHITE,
         suffix_filter: str | None = None,
-        return_type: FileReturnType | str = FileReturnType.PATH,
+        return_type: FileType | str = FileType.PATH,
         number_selections: int | str = 1,
         separator: str = ",",
         allow_duplicates: bool = False,
@@ -104,35 +104,35 @@ class SelectFileAction(BaseAction):
         else:
             raise ValueError("number_selections must be a positive integer or one of '*'")
 
-    def _coerce_return_type(self, return_type: FileReturnType | str) -> FileReturnType:
-        if isinstance(return_type, FileReturnType):
+    def _coerce_return_type(self, return_type: FileType | str) -> FileType:
+        if isinstance(return_type, FileType):
             return return_type
-        return FileReturnType(return_type)
+        return FileType(return_type)
 
     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:
+                if self.return_type == FileType.TEXT:
                     value = file.read_text(encoding="UTF-8")
-                elif self.return_type == FileReturnType.PATH:
+                elif self.return_type == FileType.PATH:
                     value = file
-                elif self.return_type == FileReturnType.JSON:
+                elif self.return_type == FileType.JSON:
                     value = json.loads(file.read_text(encoding="UTF-8"))
-                elif self.return_type == FileReturnType.TOML:
+                elif self.return_type == FileType.TOML:
                     value = toml.loads(file.read_text(encoding="UTF-8"))
-                elif self.return_type == FileReturnType.YAML:
+                elif self.return_type == FileType.YAML:
                     value = yaml.safe_load(file.read_text(encoding="UTF-8"))
-                elif self.return_type == FileReturnType.CSV:
+                elif self.return_type == FileType.CSV:
                     with open(file, newline="", encoding="UTF-8") as csvfile:
                         reader = csv.reader(csvfile)
                         value = list(reader)
-                elif self.return_type == FileReturnType.TSV:
+                elif self.return_type == FileType.TSV:
                     with open(file, newline="", encoding="UTF-8") as tsvfile:
                         reader = csv.reader(tsvfile, delimiter="\t")
                         value = list(reader)
-                elif self.return_type == FileReturnType.XML:
+                elif self.return_type == FileType.XML:
                     tree = ET.parse(file, parser=ET.XMLParser(encoding="UTF-8"))
                     root = tree.getroot()
                     value = ET.tostring(root, encoding="unicode")

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/selection_action.py

@@ -6,8 +6,8 @@ from prompt_toolkit import PromptSession
 from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action.base import BaseAction
-from falyx.action.types import SelectionReturnType
+from falyx.action.action_types import SelectionReturnType
+from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType

falyx-0.1.53/falyx/action/shell_action.py

@@ -0,0 +1,105 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""shell_action.py
+Execute shell commands with input substitution."""
+
+from __future__ import annotations
+
+import shlex
+import subprocess
+import sys
+from typing import Any, Callable
+
+from rich.tree import Tree
+
+from falyx.action.io_action import BaseIOAction
+from falyx.exceptions import FalyxError
+from falyx.themes import OneColors
+
+
+class ShellAction(BaseIOAction):
+    """
+    ShellAction wraps a shell command template for CLI pipelines.
+
+    This Action takes parsed input (from stdin, literal, or last_result),
+    substitutes it into the provided shell command template, and executes
+    the command asynchronously using subprocess.
+
+    Designed for quick integration with shell tools like `grep`, `ping`, `jq`, etc.
+
+    ⚠️ Security Warning:
+    By default, ShellAction uses `shell=True`, which can be dangerous with
+    unsanitized input. To mitigate this, set `safe_mode=True` to use `shell=False`
+    with `shlex.split()`.
+
+    Features:
+    - Automatically handles input parsing (str/bytes)
+    - `safe_mode=True` disables shell interpretation and runs with `shell=False`
+    - 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
+
+    Args:
+        name (str): Name of the action.
+        command_template (str): Shell command to execute. Must include `{}` to include
+                                input. If no placeholder is present, the input is not
+                                included.
+        safe_mode (bool): If True, runs with `shell=False` using shlex parsing
+                          (default: False).
+    """
+
+    def __init__(
+        self, name: str, command_template: str, safe_mode: bool = False, **kwargs
+    ):
+        super().__init__(name=name, **kwargs)
+        self.command_template = command_template
+        self.safe_mode = safe_mode
+
+    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()
+
+    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
+        if sys.stdin.isatty():
+            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
+        command = self.command_template.format(parsed_input)
+        if self.safe_mode:
+            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(
+                command, shell=True, text=True, capture_output=True, check=True
+            )
+        if result.returncode != 0:
+            raise RuntimeError(result.stderr.strip())
+        return result.stdout.strip()
+
+    def to_output(self, result: str) -> str:
+        return result
+
+    async def preview(self, parent: Tree | None = None):
+        label = [f"[{OneColors.GREEN_b}]⚙ ShellAction[/] '{self.name}'"]
+        label.append(f"\n[dim]Template:[/] {self.command_template}")
+        label.append(
+            f"\n[dim]Safe mode:[/] {'Enabled' if self.safe_mode else 'Disabled'}"
+        )
+        if self.inject_last_result:
+            label.append(f" [dim](injects '{self.inject_into}')[/dim]")
+        tree = parent.add("".join(label)) if parent else Tree("".join(label))
+        if not parent:
+            self.console.print(tree)
+
+    def __str__(self):
+        return (
+            f"ShellAction(name={self.name!r}, command_template={self.command_template!r},"
+            f" safe_mode={self.safe_mode})"
+        )

{falyx-0.1.51 → falyx-0.1.53}/falyx/action/user_input_action.py

@@ -1,9 +1,11 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""user_input_action.py"""
 from prompt_toolkit import PromptSession
 from prompt_toolkit.validation import Validator
 from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType

{falyx-0.1.51 → falyx-0.1.53}/falyx/command.py

@@ -27,14 +27,14 @@ from rich.console import Console
 from rich.tree import Tree
 
 from falyx.action.action import Action
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 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.parser.argparse import CommandArgumentParser
+from falyx.parser.command_argument_parser import CommandArgumentParser
 from falyx.parser.signature import infer_args_from_func
 from falyx.prompt_utils import confirm_async, should_prompt_user
 from falyx.protocols import ArgParserProtocol

{falyx-0.1.51 → falyx-0.1.53}/falyx/config.py

@@ -14,7 +14,7 @@ from pydantic import BaseModel, Field, field_validator, model_validator
 from rich.console import Console
 
 from falyx.action.action import Action
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.command import Command
 from falyx.falyx import Falyx
 from falyx.logger import logger

{falyx-0.1.51 → falyx-0.1.53}/falyx/falyx.py

@@ -43,7 +43,7 @@ from rich.markdown import Markdown
 from rich.table import Table
 
 from falyx.action.action import Action
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.bottom_bar import BottomBar
 from falyx.command import Command
 from falyx.context import ExecutionContext
@@ -346,7 +346,6 @@ class Falyx:
             aliases=["HISTORY"],
             action=Action(name="View Execution History", action=er.summary),
             style=OneColors.DARK_YELLOW,
-            simple_help_signature=True,
             arg_parser=parser,
             help_text="View the execution history of commands.",
         )
@@ -1152,7 +1151,7 @@ class Falyx:
             sys.exit(0)
 
         if self.cli_args.command == "version" or self.cli_args.version:
-            self.console.print(f"[{self.version_style}]{self.program} v{__version__}[/]")
+            self.console.print(f"[{self.version_style}]{self.program} v{self.version}[/]")
             sys.exit(0)
 
         if self.cli_args.command == "preview":

{falyx-0.1.51 → falyx-0.1.53}/falyx/menu.py

@@ -4,7 +4,7 @@ from dataclasses import dataclass
 
 from prompt_toolkit.formatted_text import FormattedText
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.signals import BackSignal, QuitSignal
 from falyx.themes import OneColors
 from falyx.utils import CaseInsensitiveDict

{falyx-0.1.51 → falyx-0.1.53}/falyx/parser/__init__.py

@@ -5,7 +5,9 @@ Copyright (c) 2025 rtj.dev LLC.
 Licensed under the MIT License. See LICENSE file for details.
 """
 
-from .argparse import Argument, ArgumentAction, CommandArgumentParser
+from .argument import Argument
+from .argument_action import ArgumentAction
+from .command_argument_parser import CommandArgumentParser
 from .parsers import FalyxParsers, get_arg_parsers, get_root_parser, get_subparsers
 
 __all__ = [

falyx-0.1.53/falyx/parser/argument.py

@@ -0,0 +1,98 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""argument.py"""
+from dataclasses import dataclass
+from typing import Any
+
+from falyx.action.base_action import BaseAction
+from falyx.parser.argument_action import ArgumentAction
+
+
+@dataclass
+class Argument:
+    """Represents a command-line argument."""
+
+    flags: tuple[str, ...]
+    dest: str  # Destination name for the argument
+    action: ArgumentAction = (
+        ArgumentAction.STORE
+    )  # Action to be taken when the argument is encountered
+    type: Any = str  # Type of the argument (e.g., str, int, float) or callable
+    default: Any = None  # Default value if the argument is not provided
+    choices: list[str] | None = None  # List of valid choices for the argument
+    required: bool = False  # True if the argument is required
+    help: str = ""  # Help text for the argument
+    nargs: int | str | None = None  # int, '?', '*', '+', None
+    positional: bool = False  # True if no leading - or -- in flags
+    resolver: BaseAction | None = None  # Action object for the argument
+
+    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 self.action in (
+            ArgumentAction.STORE,
+            ArgumentAction.APPEND,
+            ArgumentAction.EXTEND,
+        ) or 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
+            and self.default == other.default
+            and self.help == other.help
+        )
+
+    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,
+                self.default,
+                self.help,
+            )
+        )

falyx-0.1.53/falyx/parser/argument_action.py

@@ -0,0 +1,27 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""argument_action.py"""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ArgumentAction(Enum):
+    """Defines the action to be taken when the argument is encountered."""
+
+    ACTION = "action"
+    STORE = "store"
+    STORE_TRUE = "store_true"
+    STORE_FALSE = "store_false"
+    APPEND = "append"
+    EXTEND = "extend"
+    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

falyx-0.1.51/falyx/parser/argparse.py → falyx-0.1.53/falyx/parser/command_argument_parser.py

@@ -1,134 +1,22 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""command_argument_parser.py"""
 from __future__ import annotations
 
 from copy import deepcopy
-from dataclasses import dataclass
-from enum import Enum
 from typing import Any, Iterable
 
 from rich.console import Console
 from rich.markup import escape
 from rich.text import Text
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.exceptions import CommandArgumentError
+from falyx.parser.argument import Argument
+from falyx.parser.argument_action import ArgumentAction
 from falyx.parser.utils import coerce_value
 from falyx.signals import HelpSignal
 
 
-class ArgumentAction(Enum):
-    """Defines the action to be taken when the argument is encountered."""
-
-    ACTION = "action"
-    STORE = "store"
-    STORE_TRUE = "store_true"
-    STORE_FALSE = "store_false"
-    APPEND = "append"
-    EXTEND = "extend"
-    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:
-    """Represents a command-line argument."""
-
-    flags: tuple[str, ...]
-    dest: str  # Destination name for the argument
-    action: ArgumentAction = (
-        ArgumentAction.STORE
-    )  # Action to be taken when the argument is encountered
-    type: Any = str  # Type of the argument (e.g., str, int, float) or callable
-    default: Any = None  # Default value if the argument is not provided
-    choices: list[str] | None = None  # List of valid choices for the argument
-    required: bool = False  # True if the argument is required
-    help: str = ""  # Help text for the argument
-    nargs: int | str | None = None  # int, '?', '*', '+', None
-    positional: bool = False  # True if no leading - or -- in flags
-    resolver: BaseAction | None = None  # Action object for the argument
-
-    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 self.action in (
-            ArgumentAction.STORE,
-            ArgumentAction.APPEND,
-            ArgumentAction.EXTEND,
-        ) or 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
-            and self.default == other.default
-            and self.help == other.help
-        )
-
-    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,
-                self.default,
-                self.help,
-            )
-        )
-
-
 class CommandArgumentParser:
     """
     Custom argument parser for Falyx Commands.

{falyx-0.1.51 → falyx-0.1.53}/falyx/parser/parsers.py

@@ -76,14 +76,14 @@ def get_root_parser(
         help="Run in non-interactive mode with all prompts bypassed.",
     )
     parser.add_argument(
-        "-v", "--verbose", action="store_true", help="Enable debug logging for Falyx."
+        "-v", "--verbose", action="store_true", help=f"Enable debug logging for {prog}."
     )
     parser.add_argument(
         "--debug-hooks",
         action="store_true",
         help="Enable default lifecycle debug logging",
     )
-    parser.add_argument("--version", action="store_true", help="Show Falyx version")
+    parser.add_argument("--version", action="store_true", help=f"Show {prog} version")
     return parser
 
 
@@ -98,7 +98,6 @@ def get_subparsers(
     subparsers = parser.add_subparsers(
         title=title,
         description=description,
-        metavar="COMMAND",
         dest="command",
     )
     return subparsers
@@ -124,6 +123,8 @@ def get_arg_parsers(
     subparsers: _SubParsersAction | None = None,
 ) -> FalyxParsers:
     """Returns the argument parser for the CLI."""
+    if epilog is None:
+        epilog = f"Tip: Use '{prog} run ?[COMMAND]' to preview any command from the CLI."
     if root_parser is None:
         parser = get_root_parser(
             prog=prog,
@@ -145,7 +146,14 @@ def get_arg_parsers(
         parser = root_parser
 
     if subparsers is None:
-        subparsers = get_subparsers(parser)
+        if prog == "falyx":
+            subparsers = get_subparsers(
+                parser,
+                title="Falyx Commands",
+                description="Available commands for the Falyx CLI.",
+            )
+        else:
+            subparsers = get_subparsers(parser, title="subcommands", description=None)
     if not isinstance(subparsers, _SubParsersAction):
         raise TypeError("subparsers must be an instance of _SubParsersAction")
 
@@ -154,10 +162,10 @@ def get_arg_parsers(
     if isinstance(commands, dict):
         for command in commands.values():
             run_description.append(command.usage)
-            command_description = command.description or command.help_text
+            command_description = command.help_text or command.description
             run_description.append(f"{' '*24}{command_description}")
     run_epilog = (
-        "Tip: Use 'falyx run ?[COMMAND]' to preview commands by their key or alias."
+        f"Tip: Use '{prog} run ?[COMMAND]' to preview commands by their key or alias."
     )
     run_parser = subparsers.add_parser(
         "run",
@@ -259,7 +267,7 @@ def get_arg_parsers(
         "-t", "--tag", help="Filter commands by tag (case-insensitive)", default=None
     )
 
-    version_parser = subparsers.add_parser("version", help="Show the Falyx version")
+    version_parser = subparsers.add_parser("version", help=f"Show {prog} version")
 
     return FalyxParsers(
         root=parser,

{falyx-0.1.51 → falyx-0.1.53}/falyx/parser/signature.py

@@ -1,3 +1,4 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 import inspect
 from typing import Any, Callable
 

{falyx-0.1.51 → falyx-0.1.53}/falyx/parser/utils.py

@@ -1,3 +1,4 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 import types
 from datetime import datetime
 from enum import EnumMeta
@@ -5,7 +6,7 @@ from typing import Any, Literal, Union, get_args, get_origin
 
 from dateutil import parser as date_parser
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.logger import logger
 from falyx.parser.signature import infer_args_from_func
 

{falyx-0.1.51 → falyx-0.1.53}/falyx/protocols.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Any, Awaitable, Protocol, runtime_checkable
 
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 
 
 @runtime_checkable

{falyx-0.1.51 → falyx-0.1.53}/falyx/retry_utils.py

@@ -1,7 +1,7 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 """retry_utils.py"""
 from falyx.action.action import Action
-from falyx.action.base import BaseAction
+from falyx.action.base_action import BaseAction
 from falyx.hook_manager import HookType
 from falyx.retry import RetryHandler, RetryPolicy
 

falyx-0.1.53/falyx/version.py

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

{falyx-0.1.51 → falyx-0.1.53}/pyproject.toml

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

falyx-0.1.51/falyx/version.py

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