falyx 0.1.21__py3-none-any.whl → 0.1.23__py3-none-any.whl

falyx/init.py

@@ -4,27 +4,85 @@ 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 +91,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 +116,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
@@ -59,6 +60,7 @@ class BaseIOAction(BaseAction):
     def __init__(
         self,
         name: str,
+        *,
         hooks: HookManager | None = None,
         mode: str = "buffered",
         logging_hooks: bool = True,
@@ -182,13 +184,13 @@ 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
@@ -198,11 +200,15 @@ class ShellAction(BaseIOAction):
         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, **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)):
@@ -214,7 +220,11 @@ 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)
+        else:
+            result = subprocess.run(command, shell=True, text=True, capture_output=True)
         if result.returncode != 0:
             raise RuntimeError(result.stderr.strip())
         return result.stdout.strip()
@@ -224,14 +234,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/parsers.py

@@ -36,7 +36,9 @@ def get_arg_parsers(
     prog: str | None = "falyx",
     usage: str | None = None,
     description: str | None = "Falyx CLI - Run structured async command workflows.",
-    epilog: str | None = None,
+    epilog: (
+        str | None
+    ) = "Tip: Use 'falyx run ?[COMMAND]' to preview any command from the CLI.",
     parents: Sequence[ArgumentParser] = [],
     prefix_chars: str = "-",
     fromfile_prefix_chars: str | None = None,
@@ -79,6 +81,11 @@ def get_arg_parsers(
 
     run_parser = subparsers.add_parser("run", help="Run a specific command")
     run_parser.add_argument("name", help="Key, alias, or description of the command")
+    run_parser.add_argument(
+        "--summary",
+        action="store_true",
+        help="Print an execution summary after command completes",
+    )
     run_parser.add_argument(
         "--retries", type=int, help="Number of retries on failure", default=0
     )
@@ -111,6 +118,11 @@ def get_arg_parsers(
         "run-all", help="Run all commands with a given tag"
     )
     run_all_parser.add_argument("-t", "--tag", required=True, help="Tag to match")
+    run_all_parser.add_argument(
+        "--summary",
+        action="store_true",
+        help="Print a summary after all tagged commands run",
+    )
     run_all_parser.add_argument(
         "--retries", type=int, help="Number of retries on failure", default=0
     )

falyx/prompt_utils.py

@@ -1,3 +1,4 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 from falyx.options_manager import OptionsManager
 
 

falyx/protocols.py

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

falyx/select_file_action.py

@@ -1,3 +1,4 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 from __future__ import annotations
 
 import csv
@@ -33,8 +34,30 @@ class FileReturnType(Enum):
     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 +65,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 +95,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 +106,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 +134,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()
@@ -137,7 +169,9 @@ class SelectFileAction(BaseAction):
 
             options = self.get_options(files)
 
-            table = render_selection_dict_table(self.title, options, self.columns)
+            table = render_selection_dict_table(
+                title=self.title, selections=options, columns=self.columns
+            )
 
             key = await prompt_for_selection(
                 options.keys(),
@@ -181,7 +215,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

@@ -31,6 +31,7 @@ class SelectionOption:
 
 def render_table_base(
     title: str,
+    *,
     caption: str = "",
     columns: int = 4,
     box_style: box.Box = box.SIMPLE,
@@ -71,6 +72,7 @@ def render_table_base(
 def render_selection_grid(
     title: str,
     selections: Sequence[str],
+    *,
     columns: int = 4,
     caption: str = "",
     box_style: box.Box = box.SIMPLE,
@@ -86,19 +88,19 @@ def render_selection_grid(
 ) -> Table:
     """Create a selection table with the given parameters."""
     table = render_table_base(
-        title,
-        caption,
-        columns,
-        box_style,
-        show_lines,
-        show_header,
-        show_footer,
-        style,
-        header_style,
-        footer_style,
-        title_style,
-        caption_style,
-        highlight,
+        title=title,
+        caption=caption,
+        columns=columns,
+        box_style=box_style,
+        show_lines=show_lines,
+        show_header=show_header,
+        show_footer=show_footer,
+        style=style,
+        header_style=header_style,
+        footer_style=footer_style,
+        title_style=title_style,
+        caption_style=caption_style,
+        highlight=highlight,
     )
 
     for chunk in chunks(selections, columns):
@@ -110,6 +112,7 @@ def render_selection_grid(
 def render_selection_indexed_table(
     title: str,
     selections: Sequence[str],
+    *,
     columns: int = 4,
     caption: str = "",
     box_style: box.Box = box.SIMPLE,
@@ -126,19 +129,19 @@ def render_selection_indexed_table(
 ) -> Table:
     """Create a selection table with the given parameters."""
     table = render_table_base(
-        title,
-        caption,
-        columns,
-        box_style,
-        show_lines,
-        show_header,
-        show_footer,
-        style,
-        header_style,
-        footer_style,
-        title_style,
-        caption_style,
-        highlight,
+        title=title,
+        caption=caption,
+        columns=columns,
+        box_style=box_style,
+        show_lines=show_lines,
+        show_header=show_header,
+        show_footer=show_footer,
+        style=style,
+        header_style=header_style,
+        footer_style=footer_style,
+        title_style=title_style,
+        caption_style=caption_style,
+        highlight=highlight,
     )
 
     for indexes, chunk in zip(
@@ -156,6 +159,7 @@ def render_selection_indexed_table(
 def render_selection_dict_table(
     title: str,
     selections: dict[str, SelectionOption],
+    *,
     columns: int = 2,
     caption: str = "",
     box_style: box.Box = box.SIMPLE,
@@ -171,19 +175,19 @@ def render_selection_dict_table(
 ) -> Table:
     """Create a selection table with the given parameters."""
     table = render_table_base(
-        title,
-        caption,
-        columns,
-        box_style,
-        show_lines,
-        show_header,
-        show_footer,
-        style,
-        header_style,
-        footer_style,
-        title_style,
-        caption_style,
-        highlight,
+        title=title,
+        caption=caption,
+        columns=columns,
+        box_style=box_style,
+        show_lines=show_lines,
+        show_header=show_header,
+        show_footer=show_footer,
+        style=style,
+        header_style=header_style,
+        footer_style=footer_style,
+        title_style=title_style,
+        caption_style=caption_style,
+        highlight=highlight,
     )
 
     for chunk in chunks(selections.items(), columns):
@@ -200,6 +204,7 @@ def render_selection_dict_table(
 async def prompt_for_index(
     max_index: int,
     table: Table,
+    *,
     min_index: int = 0,
     default_selection: str = "",
     console: Console | None = None,
@@ -211,7 +216,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,
@@ -224,6 +229,7 @@ async def prompt_for_index(
 async def prompt_for_selection(
     keys: Sequence[str] | KeysView[str],
     table: Table,
+    *,
     default_selection: str = "",
     console: Console | None = None,
     prompt_session: PromptSession | None = None,
@@ -249,6 +255,7 @@ async def prompt_for_selection(
 async def select_value_from_list(
     title: str,
     selections: Sequence[str],
+    *,
     console: Console | None = None,
     prompt_session: PromptSession | None = None,
     prompt_message: str = "Select an option > ",
@@ -268,20 +275,20 @@ async def select_value_from_list(
 ):
     """Prompt for a selection. Return the selected item."""
     table = render_selection_indexed_table(
-        title,
-        selections,
-        columns,
-        caption,
-        box_style,
-        show_lines,
-        show_header,
-        show_footer,
-        style,
-        header_style,
-        footer_style,
-        title_style,
-        caption_style,
-        highlight,
+        title=title,
+        selections=selections,
+        columns=columns,
+        caption=caption,
+        box_style=box_style,
+        show_lines=show_lines,
+        show_header=show_header,
+        show_footer=show_footer,
+        style=style,
+        header_style=header_style,
+        footer_style=footer_style,
+        title_style=title_style,
+        caption_style=caption_style,
+        highlight=highlight,
     )
     prompt_session = prompt_session or PromptSession()
     console = console or Console(color_system="auto")
@@ -301,6 +308,7 @@ async def select_value_from_list(
 async def select_key_from_dict(
     selections: dict[str, SelectionOption],
     table: Table,
+    *,
     console: Console | None = None,
     prompt_session: PromptSession | None = None,
     prompt_message: str = "Select an option > ",
@@ -310,7 +318,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(),
@@ -325,6 +333,7 @@ async def select_key_from_dict(
 async def select_value_from_dict(
     selections: dict[str, SelectionOption],
     table: Table,
+    *,
     console: Console | None = None,
     prompt_session: PromptSession | None = None,
     prompt_message: str = "Select an option > ",
@@ -334,7 +343,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(),
@@ -351,6 +360,7 @@ async def select_value_from_dict(
 async def get_selection_from_dict_menu(
     title: str,
     selections: dict[str, SelectionOption],
+    *,
     console: Console | None = None,
     prompt_session: PromptSession | None = None,
     prompt_message: str = "Select an option > ",
@@ -363,10 +373,10 @@ async def get_selection_from_dict_menu(
     )
 
     return await select_value_from_dict(
-        selections,
-        table,
-        console,
-        prompt_session,
-        prompt_message,
-        default_selection,
+        selections=selections,
+        table=table,
+        console=console,
+        prompt_session=prompt_session,
+        prompt_message=prompt_message,
+        default_selection=default_selection,
     )

falyx/selection_action.py

@@ -1,6 +1,5 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 """selection_action.py"""
-from pathlib import Path
 from typing import Any
 
 from prompt_toolkit import PromptSession
@@ -29,7 +28,7 @@ class SelectionAction(BaseAction):
         selections: list[str] | set[str] | tuple[str, ...] | dict[str, SelectionOption],
         *,
         title: str = "Select an option",
-        columns: int = 2,
+        columns: int = 5,
         prompt_message: str = "Select > ",
         default_selection: str = "",
         inject_last_result: bool = False,
@@ -117,7 +116,9 @@ class SelectionAction(BaseAction):
             await self.hooks.trigger(HookType.BEFORE, context)
             if isinstance(self.selections, list):
                 table = render_selection_indexed_table(
-                    self.title, self.selections, self.columns
+                    title=self.title,
+                    selections=self.selections,
+                    columns=self.columns,
                 )
                 if not self.never_prompt:
                     index = await prompt_for_index(
@@ -134,7 +135,7 @@ class SelectionAction(BaseAction):
                 result = self.selections[int(index)]
             elif isinstance(self.selections, dict):
                 table = render_selection_dict_table(
-                    self.title, self.selections, self.columns
+                    title=self.title, selections=self.selections, columns=self.columns
                 )
                 if not self.never_prompt:
                     key = await prompt_for_selection(
@@ -185,7 +186,7 @@ class SelectionAction(BaseAction):
             if len(self.selections) > 10:
                 sub.add(f"[dim]... ({len(self.selections) - 10} more)[/]")
         else:
-            tree.add("[bold red]Invalid selections type[/]")
+            tree.add(f"[{OneColors.DARK_RED_b}]Invalid selections type[/]")
             return
 
         tree.add(f"[dim]Default:[/] '{self.default_selection or self.last_result}'")

falyx/signal_action.py

@@ -1,3 +1,4 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 from falyx.action import Action
 from falyx.signals import FlowSignal
 

falyx/version.py

@@ -1 +1 @@
-__version__ = "0.1.21"
+__version__ = "0.1.23"

{falyx-0.1.21.dist-info → falyx-0.1.23.dist-info}/METADATA

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