falyx 0.1.22__py3-none-any.whl → 0.1.24__py3-none-any.whl

falyx/init.py

@@ -1,30 +1,89 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""init.py"""
 from pathlib import Path
 
 from rich.console import Console
 
 TEMPLATE_TASKS = """\
-async def build():
-    print("🔨 Building project...")
-    return "Build complete!"
+# This file is used by falyx.yaml to define CLI actions.
+# You can run: falyx run [key] or falyx list to see available commands.
 
-async def test():
-    print("🧪 Running tests...")
-    return "Tests complete!"
+import asyncio
+import json
+
+from falyx.action import Action, ChainedAction
+from falyx.io_action import ShellAction
+from falyx.selection_action import SelectionAction
+
+
+post_ids = ["1", "2", "3", "4", "5"]
+
+pick_post = SelectionAction(
+    name="Pick Post ID",
+    selections=post_ids,
+    title="Choose a Post ID",
+    prompt_message="Select a post > ",
+)
+
+fetch_post = ShellAction(
+    name="Fetch Post via curl",
+    command_template="curl https://jsonplaceholder.typicode.com/posts/{}",
+)
+
+async def get_post_title(last_result):
+    return json.loads(last_result).get("title", "No title found")
+
+post_flow = ChainedAction(
+    name="Fetch and Parse Post",
+    actions=[pick_post, fetch_post, get_post_title],
+    auto_inject=True,
+)
+
+async def hello():
+    print("👋 Hello from Falyx!")
+    return "Hello Complete!"
+
+async def some_work():
+    await asyncio.sleep(2)
+    print("Work Finished!")
+    return "Work Complete!"
+
+work_action = Action(
+    name="Work Action",
+    action=some_work,
+)
 """
 
 TEMPLATE_CONFIG = """\
-- key: B
-  description: Build the project
-  action: tasks.build
-  aliases: [build]
-  spinner: true
-
-- key: T
-  description: Run tests
-  action: tasks.test
-  aliases: [test]
-  spinner: true
+# falyx.yaml — Config-driven CLI definition
+# Define your commands here and point to Python callables in tasks.py
+title: Sample CLI Project
+prompt:
+  - ["#61AFEF bold", "FALYX > "]
+columns: 3
+welcome_message: "🚀 Welcome to your new CLI project!"
+exit_message: "👋 See you next time!"
+commands:
+  - key: S
+    description: Say Hello
+    action: tasks.hello
+    aliases: [hi, hello]
+    tags: [example]
+
+  - key: P
+    description: Get Post Title
+    action: tasks.post_flow
+    aliases: [submit]
+    preview_before_confirm: true
+    confirm: true
+    tags: [demo, network]
+
+  - key: G
+    description: Do Some Work
+    action: tasks.work_action
+    aliases: [work]
+    spinner: true
+    spinner_message: "Working..."
 """
 
 GLOBAL_TEMPLATE_TASKS = """\
@@ -33,10 +92,12 @@ async def cleanup():
 """
 
 GLOBAL_CONFIG = """\
-- key: C
-  description: Cleanup temp files
-  action: tasks.cleanup
-  aliases: [clean, cleanup]
+title: Global Falyx Config
+commands:
+  - key: C
+    description: Cleanup temp files
+    action: tasks.cleanup
+    aliases: [clean, cleanup]
 """
 
 console = Console(color_system="auto")
@@ -56,7 +117,7 @@ def init_project(name: str = ".") -> None:
     tasks_path.write_text(TEMPLATE_TASKS)
     config_path.write_text(TEMPLATE_CONFIG)
 
-    print(f"✅ Initialized Falyx project in {target}")
+    console.print(f"✅ Initialized Falyx project in {target}")
 
 
 def init_global() -> None:

falyx/io_action.py

@@ -16,6 +16,7 @@ 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
@@ -27,8 +28,8 @@ 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.colors import OneColors
-from falyx.utils import logger
 
 
 class BaseIOAction(BaseAction):
@@ -77,7 +78,7 @@ class BaseIOAction(BaseAction):
     def from_input(self, raw: str | bytes) -> Any:
         raise NotImplementedError
 
-    def to_output(self, data: Any) -> str | bytes:
+    def to_output(self, result: Any) -> str | bytes:
         raise NotImplementedError
 
     async def _resolve_input(self, kwargs: dict[str, Any]) -> str | bytes:
@@ -112,7 +113,7 @@ class BaseIOAction(BaseAction):
         try:
             if self.mode == "stream":
                 line_gen = await self._read_stdin_stream()
-                async for line in self._stream_lines(line_gen, args, kwargs):
+                async for _ in self._stream_lines(line_gen, args, kwargs):
                     pass
                 result = getattr(self, "_last_result", None)
             else:
@@ -183,13 +184,14 @@ class ShellAction(BaseIOAction):
 
     Designed for quick integration with shell tools like `grep`, `ping`, `jq`, etc.
 
-    ⚠️ Warning:
-    Be cautious when using ShellAction with untrusted user input. Since it uses
-    `shell=True`, unsanitized input can lead to command injection vulnerabilities.
-    Avoid passing raw user input directly unless the template or use case is secure.
+    ⚠️ 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
@@ -197,13 +199,19 @@ class ShellAction(BaseIOAction):
 
     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.
+        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, **kwargs):
+    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)):
@@ -215,7 +223,13 @@ class ShellAction(BaseIOAction):
     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)
-        result = subprocess.run(command, shell=True, text=True, capture_output=True)
+        if self.safe_mode:
+            args = shlex.split(command)
+            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()
@@ -225,14 +239,18 @@ class ShellAction(BaseIOAction):
 
     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]")
-        if parent:
-            parent.add("".join(label))
-        else:
-            self.console.print(Tree("".join(label)))
+        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"ShellAction(name={self.name!r}, command_template={self.command_template!r},"
+            f" safe_mode={self.safe_mode})"
         )

falyx/logger.py

@@ -0,0 +1,5 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""logger.py"""
+import logging
+
+logger = logging.getLogger("falyx")

falyx/menu_action.py

@@ -12,15 +12,18 @@ 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.logger import logger
 from falyx.selection import prompt_for_selection, render_table_base
 from falyx.signal_action import SignalAction
 from falyx.signals import BackSignal, QuitSignal
 from falyx.themes.colors import OneColors
-from falyx.utils import CaseInsensitiveDict, chunks, logger
+from falyx.utils import CaseInsensitiveDict, chunks
 
 
 @dataclass
 class MenuOption:
+    """Represents a single menu option with a description and an action to execute."""
+
     description: str
     action: BaseAction
     style: str = OneColors.WHITE
@@ -93,6 +96,8 @@ class MenuOptionMap(CaseInsensitiveDict):
 
 
 class MenuAction(BaseAction):
+    """MenuAction class for creating single use menu actions."""
+
     def __init__(
         self,
         name: str,
@@ -162,7 +167,8 @@ class MenuAction(BaseAction):
 
         if self.never_prompt and not effective_default:
             raise ValueError(
-                f"[{self.name}] 'never_prompt' is True but no valid default_selection was provided."
+                f"[{self.name}] 'never_prompt' is True but no valid default_selection"
+                " was provided."
             )
 
         context.start_timer()

falyx/options_manager.py

@@ -5,12 +5,14 @@ from argparse import Namespace
 from collections import defaultdict
 from typing import Any, Callable
 
-from falyx.utils import logger
+from falyx.logger import logger
 
 
 class OptionsManager:
+    """OptionsManager"""
+
     def __init__(self, namespaces: list[tuple[str, Namespace]] | None = None) -> None:
-        self.options: defaultdict = defaultdict(lambda: Namespace())
+        self.options: defaultdict = defaultdict(Namespace)
         if namespaces:
             for namespace_name, namespace in namespaces:
                 self.from_namespace(namespace, namespace_name)
@@ -42,7 +44,9 @@ class OptionsManager:
                 f"Cannot toggle non-boolean option: '{option_name}' in '{namespace_name}'"
             )
         self.set(option_name, not current, namespace_name=namespace_name)
-        logger.debug(f"Toggled '{option_name}' in '{namespace_name}' to {not current}")
+        logger.debug(
+            "Toggled '%s' in '%s' to %s", option_name, namespace_name, not current
+        )
 
     def get_value_getter(
         self, option_name: str, namespace_name: str = "cli_args"

falyx/parsers.py

@@ -39,7 +39,7 @@ def get_arg_parsers(
     epilog: (
         str | None
     ) = "Tip: Use 'falyx run ?[COMMAND]' to preview any command from the CLI.",
-    parents: Sequence[ArgumentParser] = [],
+    parents: Sequence[ArgumentParser] | None = None,
     prefix_chars: str = "-",
     fromfile_prefix_chars: str | None = None,
     argument_default: Any = None,
@@ -54,7 +54,7 @@ def get_arg_parsers(
         usage=usage,
         description=description,
         epilog=epilog,
-        parents=parents,
+        parents=parents if parents else [],
         prefix_chars=prefix_chars,
         fromfile_prefix_chars=fromfile_prefix_chars,
         argument_default=argument_default,

falyx/prompt_utils.py

@@ -1,4 +1,15 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""prompt_utils.py"""
+from prompt_toolkit import PromptSession
+from prompt_toolkit.formatted_text import (
+    AnyFormattedText,
+    FormattedText,
+    merge_formatted_text,
+)
+
 from falyx.options_manager import OptionsManager
+from falyx.themes.colors import OneColors
+from falyx.validators import yes_no_validator
 
 
 def should_prompt_user(
@@ -7,7 +18,10 @@ def should_prompt_user(
     options: OptionsManager,
     namespace: str = "cli_args",
 ):
-    """Determine whether to prompt the user for confirmation based on command and global options."""
+    """
+    Determine whether to prompt the user for confirmation based on command
+    and global options.
+    """
     never_prompt = options.get("never_prompt", False, namespace)
     force_confirm = options.get("force_confirm", False, namespace)
     skip_confirm = options.get("skip_confirm", False, namespace)
@@ -16,3 +30,19 @@ def should_prompt_user(
         return False
 
     return confirm or force_confirm
+
+
+async def confirm_async(
+    message: AnyFormattedText = "Are you sure?",
+    prefix: AnyFormattedText = FormattedText([(OneColors.CYAN, "❓ ")]),
+    suffix: AnyFormattedText = FormattedText([(OneColors.LIGHT_YELLOW_b, " [Y/n] > ")]),
+    session: PromptSession | None = None,
+) -> bool:
+    """Prompt the user with a yes/no async confirmation and return True for 'Y'."""
+    session = session or PromptSession()
+    merged_message: AnyFormattedText = merge_formatted_text([prefix, message, suffix])
+    answer = await session.prompt_async(
+        merged_message,
+        validator=yes_no_validator(),
+    )
+    return answer.upper() == "Y"

falyx/protocols.py

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

falyx/retry.py

@@ -8,10 +8,12 @@ import random
 from pydantic import BaseModel, Field
 
 from falyx.context import ExecutionContext
-from falyx.utils import logger
+from falyx.logger import logger
 
 
 class RetryPolicy(BaseModel):
+    """RetryPolicy"""
+
     max_retries: int = Field(default=3, ge=0)
     delay: float = Field(default=1.0, ge=0.0)
     backoff: float = Field(default=2.0, ge=1.0)
@@ -34,6 +36,8 @@ class RetryPolicy(BaseModel):
 
 
 class RetryHandler:
+    """RetryHandler class to manage retry policies for actions."""
+
     def __init__(self, policy: RetryPolicy = RetryPolicy()):
         self.policy = policy
 
@@ -49,7 +53,7 @@ class RetryHandler:
         self.policy.delay = delay
         self.policy.backoff = backoff
         self.policy.jitter = jitter
-        logger.info(f"🔄 Retry policy enabled: {self.policy}")
+        logger.info("🔄 Retry policy enabled: %s", self.policy)
 
     async def retry_on_error(self, context: ExecutionContext) -> None:
         from falyx.action import Action
@@ -63,21 +67,21 @@ class RetryHandler:
         last_error = error
 
         if not target:
-            logger.warning(f"[{name}] ⚠️ No action target. Cannot retry.")
+            logger.warning("[%s] ⚠️ No action target. Cannot retry.", name)
             return None
 
         if not isinstance(target, Action):
             logger.warning(
-                f"[{name}] ❌ RetryHandler only supports only supports Action objects."
+                "[%s] ❌ RetryHandler only supports only supports Action objects.", name
             )
             return None
 
         if not getattr(target, "is_retryable", False):
-            logger.warning(f"[{name}] ❌ Not retryable.")
+            logger.warning("[%s] ❌ Not retryable.", name)
             return None
 
         if not self.policy.enabled:
-            logger.warning(f"[{name}] ❌ Retry policy is disabled.")
+            logger.warning("[%s] ❌ Retry policy is disabled.", name)
             return None
 
         while retries_done < self.policy.max_retries:
@@ -88,23 +92,30 @@ class RetryHandler:
                 sleep_delay += random.uniform(-self.policy.jitter, self.policy.jitter)
 
             logger.info(
-                f"[{name}] 🔄 Retrying ({retries_done}/{self.policy.max_retries}) "
-                f"in {current_delay}s due to '{last_error}'..."
+                "[%s] 🔄 Retrying (%s/%s) in %ss due to '%s'...",
+                name,
+                retries_done,
+                self.policy.max_retries,
+                current_delay,
+                last_error,
             )
             await asyncio.sleep(current_delay)
             try:
                 result = await target.action(*context.args, **context.kwargs)
                 context.result = result
                 context.exception = None
-                logger.info(f"[{name}] ✅ Retry succeeded on attempt {retries_done}.")
+                logger.info("[%s] ✅ Retry succeeded on attempt %s.", name, retries_done)
                 return None
             except Exception as retry_error:
                 last_error = retry_error
                 current_delay *= self.policy.backoff
                 logger.warning(
-                    f"[{name}] ⚠️ Retry attempt {retries_done}/{self.policy.max_retries} "
-                    f"failed due to '{retry_error}'."
+                    "[%s] ⚠️ Retry attempt %s/%s failed due to '%s'.",
+                    name,
+                    retries_done,
+                    self.policy.max_retries,
+                    retry_error,
                 )
 
         context.exception = last_error
-        logger.error(f"[{name}] ❌ All {self.policy.max_retries} retries failed.")
+        logger.error("[%s] ❌ All %s retries failed.", name, self.policy.max_retries)

falyx/retry_utils.py

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

falyx/select_file_action.py

@@ -1,3 +1,5 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""select_file_action.py"""
 from __future__ import annotations
 
 import csv
@@ -17,24 +19,48 @@ 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.logger import logger
 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):
+    """Enum for file return types."""
+
     TEXT = "text"
     PATH = "path"
     JSON = "json"
     TOML = "toml"
     YAML = "yaml"
     CSV = "csv"
+    TSV = "tsv"
     XML = "xml"
 
+    @classmethod
+    def _get_alias(cls, value: str) -> str:
+        aliases = {
+            "yml": "yaml",
+            "txt": "text",
+            "file": "path",
+            "filepath": "path",
+        }
+        return aliases.get(value, value)
+
+    @classmethod
+    def _missing_(cls, value: object) -> FileReturnType:
+        if isinstance(value, str):
+            normalized = value.lower()
+            alias = cls._get_alias(normalized)
+            for member in cls:
+                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}")
+
 
 class SelectFileAction(BaseAction):
     """
@@ -42,7 +68,7 @@ class SelectFileAction(BaseAction):
     - file content (as text, JSON, CSV, etc.)
     - or the file path itself.
 
-    Supported formats: text, json, yaml, toml, csv, xml.
+    Supported formats: text, json, yaml, toml, csv, tsv, xml.
 
     Useful for:
     - dynamically loading config files
@@ -72,7 +98,7 @@ class SelectFileAction(BaseAction):
         prompt_message: str = "Choose > ",
         style: str = OneColors.WHITE,
         suffix_filter: str | None = None,
-        return_type: FileReturnType = FileReturnType.PATH,
+        return_type: FileReturnType | str = FileReturnType.PATH,
         console: Console | None = None,
         prompt_session: PromptSession | None = None,
     ):
@@ -83,9 +109,14 @@ class SelectFileAction(BaseAction):
         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()
+        self.return_type = self._coerce_return_type(return_type)
+
+    def _coerce_return_type(self, return_type: FileReturnType | str) -> FileReturnType:
+        if isinstance(return_type, FileReturnType):
+            return return_type
+        return FileReturnType(return_type)
 
     def get_options(self, files: list[Path]) -> dict[str, SelectionOption]:
         value: Any
@@ -106,6 +137,10 @@ class SelectFileAction(BaseAction):
                     with open(file, newline="", encoding="UTF-8") as csvfile:
                         reader = csv.reader(csvfile)
                         value = list(reader)
+                elif self.return_type == FileReturnType.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:
                     tree = ET.parse(file, parser=ET.XMLParser(encoding="UTF-8"))
                     root = tree.getroot()
@@ -183,7 +218,7 @@ class SelectFileAction(BaseAction):
             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}[/]")
+            tree.add(f"[{OneColors.DARK_RED_b}]⚠️ Error scanning directory: {error}[/]")
 
         if not parent:
             self.console.print(tree)

falyx/selection.py

@@ -16,6 +16,8 @@ from falyx.validators import int_range_validator, key_validator
 
 @dataclass
 class SelectionOption:
+    """Represents a single selection option with a description and a value."""
+
     description: str
     value: Any
     style: str = OneColors.WHITE
@@ -26,7 +28,8 @@ class SelectionOption:
 
     def render(self, key: str) -> str:
         """Render the selection option for display."""
-        return f"[{OneColors.WHITE}][{key}][/] [{self.style}]{self.description}[/]"
+        key = escape(f"[{key}]")
+        return f"[{OneColors.WHITE}]{key}[/] [{self.style}]{self.description}[/]"
 
 
 def render_table_base(
@@ -194,7 +197,8 @@ def render_selection_dict_table(
         row = []
         for key, option in chunk:
             row.append(
-                f"[{OneColors.WHITE}][{key.upper()}] [{option.style}]{option.description}[/]"
+                f"[{OneColors.WHITE}][{key.upper()}] "
+                f"[{option.style}]{option.description}[/]"
             )
         table.add_row(*row)
 
@@ -216,7 +220,7 @@ async def prompt_for_index(
     console = console or Console(color_system="auto")
 
     if show_table:
-        console.print(table)
+        console.print(table, justify="center")
 
     selection = await prompt_session.prompt_async(
         message=prompt_message,
@@ -318,7 +322,7 @@ async def select_key_from_dict(
     prompt_session = prompt_session or PromptSession()
     console = console or Console(color_system="auto")
 
-    console.print(table)
+    console.print(table, justify="center")
 
     return await prompt_for_selection(
         selections.keys(),
@@ -343,7 +347,7 @@ async def select_value_from_dict(
     prompt_session = prompt_session or PromptSession()
     console = console or Console(color_system="auto")
 
-    console.print(table)
+    console.print(table, justify="center")
 
     selection_key = await prompt_for_selection(
         selections.keys(),