Experiemental feature pipes

.gitignore

@@ -15,3 +15,4 @@ build/
 .vscode/
 coverage.xml
 .coverage
+

.pre-commit-config.yaml

@@ -1,23 +0,0 @@
-repos:
--   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
-    hooks:
-    -   id: trailing-whitespace
-    -   id: end-of-file-fixer
--   repo: https://github.com/pycqa/isort
-    rev: 5.13.2
-    hooks:
-    -   id: isort
-        args: [--profile, black]
--   repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 25.1.0
-    hooks:
-    -   id: black
-        args: [-l, "90"]
--   repo: local
-    hooks:
-    - id: sync-version
-      name: Sync version from pyproject.toml
-      entry: python scripts/sync_version.py
-      language: system
-      files: ^pyproject\.toml$

README.md

@@ -10,7 +10,7 @@
 - ⚙️ Full lifecycle hooks (before, after, success, error, teardown)
 - 📊 Execution tracing, logging, and introspection
 - 🧙‍♂️ Async-first design with Process support
-- 🧩 Extensible CLI menus, customizable bottom bars, and keyboard shortcuts
+- 🧩 Extensible CLI menus and customizable output
 
 > Built for developers who value *clarity*, *resilience*, and *visibility* in their terminal workflows.
 
@@ -21,13 +21,12 @@
 Modern CLI tools deserve the same resilience as production systems. Falyx makes it easy to:
 
 - Compose workflows using `Action`, `ChainedAction`, or `ActionGroup`
-- Inject the result of one step into the next (`last_result` / `auto_inject`)
+- Inject the result of one step into the next (`last_result`)
-- Handle flaky operations with retries, backoff, and jitter
+- Handle flaky operations with retries and exponential backoff
 - Roll back safely on failure with structured undo logic
-- Add observability with timing, tracebacks, and lifecycle hooks
+- Add observability with execution timing, result tracking, and hooks
 - Run in both interactive *and* headless (scriptable) modes
-- Support config-driven workflows with YAML or TOML
+- Customize output with Rich `Table`s (grouping, theming, etc.)
-- Visualize tagged command groups and menu state via Rich tables
 
 ---
 
@@ -53,20 +52,18 @@ poetry install
 import asyncio
 import random
 
-from falyx import Falyx
+from falyx import Falyx, Action, ChainedAction
-from falyx.action import Action, ChainedAction
 
 # A flaky async step that fails randomly
 async def flaky_step():
     await asyncio.sleep(0.2)
     if random.random() < 0.5:
         raise RuntimeError("Random failure!")
-    print("ok")
     return "ok"
 
 # Create the actions
-step1 = Action(name="step_1", action=flaky_step)
+step1 = Action(name="step_1", action=flaky_step, retry=True)
-step2 = Action(name="step_2", action=flaky_step)
+step2 = Action(name="step_2", action=flaky_step, retry=True)
 
 # Chain the actions
 chain = ChainedAction(name="my_pipeline", actions=[step1, step2])
@@ -77,11 +74,9 @@ falyx.add_command(
     key="R",
     description="Run My Pipeline",
     action=chain,
+    logging_hooks=True,
     preview_before_confirm=True,
     confirm=True,
-    retry_all=True,
-    spinner=True,
-    style="cyan",
 )
 
 # Entry point
@@ -90,131 +85,76 @@ if __name__ == "__main__":
 ```
 
 ```bash
-$ python simple.py
+❯ python simple.py
                                 🚀 Falyx Demo
 
   [R] Run My Pipeline
-           [H] Help              [Y] History   [X] Exit
+  [Y] History                                         [Q] Exit
 
 >
 ```
 
 ```bash
-$ python simple.py run r
+❯ python simple.py run R
 Command: 'R' — Run My Pipeline
 └── ⛓ ChainedAction 'my_pipeline'
     ├── ⚙ Action 'step_1'
     │   ↻ Retries: 3x, delay 1.0s, backoff 2.0x
     └── ⚙ Action 'step_2'
         ↻ Retries: 3x, delay 1.0s, backoff 2.0x
-❓ Confirm execution of R — Run My Pipeline (calls `my_pipeline`)  [Y/n] > y
+Confirm execution of R — Run My Pipeline (calls `my_pipeline`)  [Y/n] y
-[2025-07-20 09:29:35] WARNING   Retry attempt 1/3 failed due to 'Random failure!'.
+[2025-04-15 22:03:57] WARNING   ⚠️ Retry attempt 1/3 failed due to 'Random failure!'.
-ok
+✅ Result: ['ok', 'ok']
-[2025-07-20 09:29:38] WARNING   Retry attempt 1/3 failed due to 'Random failure!'.
-ok
 ```
 
 ---
 
 ## 📦 Core Features
 
-- ✅ Async-native `Action`, `ChainedAction`, `ActionGroup`, `ProcessAction`
+- ✅ Async-native `Action`, `ChainedAction`, `ActionGroup`
-- 🔁 Retry policies with delay, backoff, jitter — opt-in per action or globally
+- 🔁 Retry policies + exponential backoff
-- ⛓ Rollbacks and lifecycle hooks for chained execution
+- ⛓ Rollbacks on chained failures
-- 🎛️ Headless or interactive CLI powered by `argparse` + `prompt_toolkit`
+- 🎛️ Headless or interactive CLI with argparse and prompt_toolkit
-- 📊 In-memory `ExecutionRegistry` with result tracking, timing, and tracebacks
+- 📊 Built-in execution registry, result tracking, and timing
-- 🌐 CLI menu construction via config files or Python
+- 🧠 Supports `ProcessAction` for CPU-bound workloads
-- ⚡ Bottom bar toggle switches and counters with `Ctrl+<key>` shortcuts
+- 🧩 Custom `Table` rendering for CLI menu views
-- 🔍 Structured confirmation prompts and help rendering
+- 🔍 Hook lifecycle: `before`, `on_success`, `on_error`, `after`, `on_teardown`
-- 🪵 Flexible logging: Rich console for devs, JSON logs for ops
 
 ---
 
-### 🧰 Building Blocks
+## 🔍 Execution Trace
 
-- **`Action`**: A single unit of async (or sync) logic
+```bash
-- **`ChainedAction`**: Execute a sequence of actions, with rollback and injection
+[2025-04-14 10:33:22] DEBUG    [Step 1] ⚙ flaky_step()
-- **`ActionGroup`**: Run actions concurrently and collect results
+[2025-04-14 10:33:22] INFO     [Step 1] 🔁 Retrying (1/3) in 1.0s...
-- **`ProcessAction`**: Use `multiprocessing` for CPU-bound workflows
+[2025-04-14 10:33:23] DEBUG    [Step 1] ✅ Success | Result: ok
-- **`Falyx`**: Interactive or headless CLI controller with history, menus, and theming
+[2025-04-14 10:33:23] DEBUG    [My Pipeline] ✅ Result: ['ok', 'ok']
-- **`ExecutionContext`**: Metadata store per invocation (name, args, result, timing)
+```
-- **`HookManager`**: Attach `before`, `after`, `on_success`, `on_error`, `on_teardown`
 
 ---
 
-### 🔍 Logging
+### 🧱 Core Building Blocks
-```
-2025-07-20 09:29:32 [falyx] [INFO] Command 'R' selected.
-2025-07-20 09:29:32 [falyx] [INFO] [run_key] Executing: R — Run My Pipeline
-2025-07-20 09:29:33 [falyx] [INFO] [my_pipeline] Starting -> ChainedAction(name=my_pipeline, actions=['step_1', 'step_2'], args=(), kwargs={}, auto_inject=False, return_list=False)()
-2025-07-20 09:29:33 [falyx] [INFO] [step_1] Retrying (1/3) in 1.0s due to 'Random failure!'...
-2025-07-20 09:29:35 [falyx] [WARNING] [step_1] Retry attempt 1/3 failed due to 'Random failure!'.
-2025-07-20 09:29:35 [falyx] [INFO] [step_1] Retrying (2/3) in 2.0s due to 'Random failure!'...
-2025-07-20 09:29:37 [falyx] [INFO] [step_1] Retry succeeded on attempt 2.
-2025-07-20 09:29:37 [falyx] [INFO] [step_1] Recovered: step_1
-2025-07-20 09:29:37 [falyx] [DEBUG] [step_1] status=OK duration=3.627s result='ok' exception=None
-2025-07-20 09:29:37 [falyx] [INFO] [step_2] Retrying (1/3) in 1.0s due to 'Random failure!'...
-2025-07-20 09:29:38 [falyx] [WARNING] [step_2] Retry attempt 1/3 failed due to 'Random failure!'.
-2025-07-20 09:29:38 [falyx] [INFO] [step_2] Retrying (2/3) in 2.0s due to 'Random failure!'...
-2025-07-20 09:29:40 [falyx] [INFO] [step_2] Retry succeeded on attempt 2.
-2025-07-20 09:29:40 [falyx] [INFO] [step_2] Recovered: step_2
-2025-07-20 09:29:40 [falyx] [DEBUG] [step_2] status=OK duration=3.609s result='ok' exception=None
-2025-07-20 09:29:40 [falyx] [DEBUG] [my_pipeline] Success -> Result: 'ok'
-2025-07-20 09:29:40 [falyx] [DEBUG] [my_pipeline] Finished in 7.237s
-2025-07-20 09:29:40 [falyx] [DEBUG] [my_pipeline] status=OK duration=7.237s result='ok' exception=None
-2025-07-20 09:29:40 [falyx] [DEBUG] [Run My Pipeline] status=OK duration=7.238s result='ok' exception=None
-```
 
-### 📊 History Tracking
+#### `Action`
+A single async unit of work. Painless retry support.
 
-View full execution history:
+#### `ChainedAction`
+Run tasks in sequence. Supports rollback on failure and context propagation.
 
-```bash
+#### `ActionGroup`
-> history
+Run tasks in parallel. Useful for fan-out operations like batch API calls.
-                                                   📊 Execution History
 
-   Index   Name                           Start         End    Duration   Status        Result / Exception
+#### `ProcessAction`
- ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+Offload CPU-bound work to another process — no extra code needed.
-       0   step_1                      09:23:55    09:23:55      0.201s   ✅ Success    'ok'
-       1   step_2                      09:23:55    09:24:03      7.829s   ❌ Error      RuntimeError('Random failure!')
-       2   my_pipeline                 09:23:55    09:24:03      8.080s   ❌ Error      RuntimeError('Random failure!')
-       3   Run My Pipeline             09:23:55    09:24:03      8.082s   ❌ Error      RuntimeError('Random failure!')
-```
 
-Inspect result by index:
+#### `Falyx`
+Your CLI controller — powers menus, subcommands, history, bottom bars, and more.
 
-```bash
+#### `ExecutionContext`
-> history --result-index 0
+Tracks metadata, arguments, timing, and results for each action execution.
-Action(name='step_1', action=flaky_step, args=(), kwargs={}, retry=True, rollback=False) ():
-ok
-```
 
-Print last result includes tracebacks:
+#### `HookManager`
-
+Registers and triggers lifecycle hooks (`before`, `after`, `on_error`, etc.) for actions and commands.
-```bash
-> history --last-result
-Command(key='R', description='Run My Pipeline' action='ChainedAction(name=my_pipeline, actions=['step_1', 'step_2'],
-args=(), kwargs={}, auto_inject=False, return_list=False)') ():
-Traceback (most recent call last):
-  File ".../falyx/command.py", line 291, in __call__
-    result = await self.action(*combined_args, **combined_kwargs)
-             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  File ".../falyx/action/base_action.py", line 91, in __call__
-    return await self._run(*args, **kwargs)
-           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  File ".../falyx/action/chained_action.py", line 212, in _run
-    result = await prepared(*combined_args, **updated_kwargs)
-             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  File ".../falyx/action/base_action.py", line 91, in __call__
-    return await self._run(*args, **kwargs)
-           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  File ".../falyx/action/action.py", line 157, in _run
-    result = await self.action(*combined_args, **combined_kwargs)
-             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  File ".../falyx/examples/simple.py", line 15, in flaky_step
-    raise RuntimeError("Random failure!")
-RuntimeError: Random failure!
-```
 
 ---
 
@@ -222,6 +162,6 @@ RuntimeError: Random failure!
 
 > “Like a phalanx: organized, resilient, and reliable.”
 
-Falyx is designed for developers who don’t just want CLI tools to run — they want them to **fail meaningfully**, **recover intentionally**, and **log clearly**.
+Falyx is designed for developers who don’t just want CLI tools to run — they want them to **fail meaningfully**, **recover gracefully**, and **log clearly**.
 
 ---

examples/action_example.py

@@ -1,33 +1,29 @@
 import asyncio
 
-from falyx.action import Action, ActionGroup, ChainedAction
+from falyx import Action, ActionGroup, ChainedAction
-
 
 # Actions can be defined as synchronous functions
 # Falyx will automatically convert them to async functions
 def hello() -> None:
     print("Hello, world!")
 
-
+hello = Action(name="hello_action", action=hello)
-hello_action = Action(name="hello_action", action=hello)
 
 # Actions can be run by themselves or as part of a command or pipeline
-asyncio.run(hello_action())
+asyncio.run(hello())
-
 
 # Actions are designed to be asynchronous first
 async def goodbye() -> None:
     print("Goodbye!")
 
-
+goodbye = Action(name="goodbye_action", action=goodbye)
-goodbye_action = Action(name="goodbye_action", action=goodbye)
 
 asyncio.run(goodbye())
 
 # Actions can be run in parallel
-group = ActionGroup(name="greeting_group", actions=[hello_action, goodbye_action])
+group = ActionGroup(name="greeting_group", actions=[hello, goodbye])
 asyncio.run(group())
 
 # Actions can be run in a chain
-chain = ChainedAction(name="greeting_chain", actions=[hello_action, goodbye_action])
+chain = ChainedAction(name="greeting_chain", actions=[hello, goodbye])
 asyncio.run(chain())

examples/action_factory_demo.py

@@ -1,48 +0,0 @@
-import asyncio
-
-from falyx import Falyx
-from falyx.action import ActionFactory, ChainedAction, HTTPAction, SelectionAction
-
-# Selection of a post ID to fetch (just an example set)
-post_selector = SelectionAction(
-    name="Pick Post ID",
-    selections=["15", "25", "35", "45", "55"],
-    title="Choose a Post ID to submit",
-    prompt_message="Post ID > ",
-    show_table=True,
-)
-
-
-# Factory that builds and executes the actual HTTP POST request
-async def build_post_action(post_id) -> HTTPAction:
-    print(f"Building HTTPAction for Post ID: {post_id}")
-    return HTTPAction(
-        name=f"POST to /posts (id={post_id})",
-        method="POST",
-        url="https://jsonplaceholder.typicode.com/posts",
-        json={"title": "foo", "body": "bar", "userId": int(post_id)},
-    )
-
-
-post_factory = ActionFactory(
-    name="Build HTTPAction from Post ID",
-    factory=build_post_action,
-    inject_last_result=True,
-    inject_into="post_id",
-    preview_kwargs={"post_id": "100"},
-)
-
-# Wrap in a ChainedAction
-chain = ChainedAction(
-    name="Submit Post Flow",
-    actions=[post_selector, post_factory],
-    auto_inject=True,
-)
-
-flx = Falyx()
-flx.add_command(
-    key="S",
-    description="Submit a Post",
-    action=chain,
-)
-asyncio.run(flx.run())

examples/argument_examples.py

@@ -1,108 +0,0 @@
-import asyncio
-from enum import Enum
-from pathlib import Path
-
-from falyx import Falyx
-from falyx.action import Action
-from falyx.parser.command_argument_parser import CommandArgumentParser
-
-
-class Place(Enum):
-    """Enum for different places."""
-
-    NEW_YORK = "New York"
-    SAN_FRANCISCO = "San Francisco"
-    LONDON = "London"
-
-    def __str__(self):
-        return self.value
-
-
-async def test_args(
-    service: str,
-    place: Place = Place.NEW_YORK,
-    region: str = "us-east-1",
-    path: Path | None = None,
-    tag: str | None = None,
-    verbose: bool | None = None,
-    number: int | None = None,
-) -> str:
-    if verbose:
-        print(f"Deploying {service}:{tag}:{number} to {region} at {place} from {path}...")
-    return f"{service}:{tag}:{number} deployed to {region} at {place} from {path}."
-
-
-def default_config(parser: CommandArgumentParser) -> None:
-    """Default argument configuration for the command."""
-    parser.add_argument(
-        "service",
-        type=str,
-        choices=["web", "database", "cache"],
-        help="Service name to deploy.",
-    )
-    parser.add_argument(
-        "place",
-        type=Place,
-        choices=list(Place),
-        default=Place.NEW_YORK,
-        help="Place where the service will be deployed.",
-    )
-    parser.add_argument(
-        "--region",
-        type=str,
-        default="us-east-1",
-        help="Deployment region.",
-        choices=["us-east-1", "us-west-2", "eu-west-1"],
-    )
-    parser.add_argument(
-        "--path",
-        type=Path,
-        help="Path to the configuration file.",
-    )
-    parser.add_argument(
-        "--verbose",
-        action="store_bool_optional",
-        help="Enable verbose output.",
-    )
-    parser.add_argument(
-        "--tag",
-        type=str,
-        help="Optional tag for the deployment.",
-        suggestions=["latest", "stable", "beta"],
-    )
-    parser.add_argument(
-        "--number",
-        type=int,
-        help="Optional number argument.",
-    )
-    parser.add_tldr_examples(
-        [
-            ("web", "Deploy 'web' to the default location (New York)"),
-            ("cache London --tag beta", "Deploy 'cache' to London with tag"),
-            ("database --region us-west-2 --verbose", "Verbose deploy to west region"),
-        ]
-    )
-
-
-flx = Falyx(
-    "Argument Examples",
-    program="argument_examples.py",
-    hide_menu_table=True,
-    show_placeholder_menu=True,
-    enable_prompt_history=True,
-)
-
-flx.add_command(
-    key="T",
-    aliases=["test"],
-    description="Test Command",
-    help_text="A command to test argument parsing.",
-    action=Action(
-        name="test_args",
-        action=test_args,
-    ),
-    style="bold #B3EBF2",
-    argument_config=default_config,
-)
-
-asyncio.run(flx.run())

examples/auto_args_group.py

@@ -1,38 +0,0 @@
-import asyncio
-
-from falyx import Falyx
-from falyx.action import Action, ActionGroup
-
-
-# Define a shared async function
-async def say_hello(name: str, excited: bool = False):
-    if excited:
-        print(f"Hello, {name}!!!")
-    else:
-        print(f"Hello, {name}.")
-
-
-# Wrap the same callable in multiple Actions
-action1 = Action("say_hello_1", action=say_hello)
-action2 = Action("say_hello_2", action=say_hello)
-action3 = Action("say_hello_3", action=say_hello)
-
-# Combine into an ActionGroup
-group = ActionGroup(name="greet_group", actions=[action1, action2, action3])
-
-flx = Falyx("Test Group")
-flx.add_command(
-    key="G",
-    description="Greet someone with multiple variations.",
-    aliases=["greet", "hello"],
-    action=group,
-    arg_metadata={
-        "name": {
-            "help": "The name of the person to greet.",
-        },
-        "excited": {
-            "help": "Whether to greet excitedly.",
-        },
-    },
-)
-asyncio.run(flx.run())

examples/auto_parse_demo.py

@@ -1,62 +0,0 @@
-import asyncio
-
-from falyx import Falyx
-from falyx.action import Action, ChainedAction
-from falyx.utils import setup_logging
-
-setup_logging()
-
-
-async def deploy(service: str, region: str = "us-east-1", verbose: bool = False) -> str:
-    if verbose:
-        print(f"Deploying {service} to {region}...")
-    await asyncio.sleep(2)
-    if verbose:
-        print(f"{service} deployed successfully!")
-    return f"{service} deployed to {region}"
-
-
-flx = Falyx("Deployment CLI")
-
-flx.add_command(
-    key="D",
-    aliases=["deploy"],
-    description="Deploy",
-    help_text="Deploy a service to a specified region.",
-    action=Action(
-        name="deploy_service",
-        action=deploy,
-    ),
-    arg_metadata={
-        "service": "Service name",
-        "region": {
-            "help": "Deployment region",
-            "choices": ["us-east-1", "us-west-2", "eu-west-1"],
-        },
-        "verbose": {"help": "Enable verbose mode"},
-    },
-    tags=["deployment", "service"],
-)
-
-deploy_chain = ChainedAction(
-    name="DeployChain",
-    actions=[
-        Action(name="deploy_service", action=deploy),
-        Action(
-            name="notify",
-            action=lambda last_result: print(f"Notification: {last_result}"),
-        ),
-    ],
-    auto_inject=True,
-)
-
-flx.add_command(
-    key="N",
-    aliases=["notify"],
-    description="Deploy and Notify",
-    help_text="Deploy a service and notify.",
-    action=deploy_chain,
-    tags=["deployment", "service", "notification"],
-)
-
-asyncio.run(flx.run())

examples/config_loading.py

@@ -1,10 +0,0 @@
-"""config_loading.py"""
-
-from falyx.config import loader
-
-flx = loader("falyx.yaml")
-
-if __name__ == "__main__":
-    import asyncio
-
-    asyncio.run(flx.run())

examples/confirm_example.py

@@ -1,127 +0,0 @@
-import asyncio
-from typing import Any
-
-from pydantic import BaseModel
-
-from falyx import Falyx
-from falyx.action import (
-    Action,
-    ActionFactory,
-    ChainedAction,
-    ConfirmAction,
-    SaveFileAction,
-)
-from falyx.parser import CommandArgumentParser
-
-
-class Dog(BaseModel):
-    name: str
-    age: int
-    breed: str
-
-
-async def get_dogs(*dog_names: str) -> list[Dog]:
-    """Simulate fetching dog data."""
-    await asyncio.sleep(0.1)  # Simulate network delay
-    dogs = [
-        Dog(name="Buddy", age=3, breed="Golden Retriever"),
-        Dog(name="Max", age=5, breed="Beagle"),
-        Dog(name="Bella", age=2, breed="Bulldog"),
-        Dog(name="Charlie", age=4, breed="Poodle"),
-        Dog(name="Lucy", age=1, breed="Labrador"),
-        Dog(name="Spot", age=6, breed="German Shepherd"),
-    ]
-    dogs = [
-        dog for dog in dogs if dog.name.upper() in (name.upper() for name in dog_names)
-    ]
-    if not dogs:
-        raise ValueError(f"No dogs found with the names: {', '.join(dog_names)}")
-    return dogs
-
-
-async def build_json_updates(dogs: list[Dog]) -> list[dict[str, Any]]:
-    """Build JSON updates for the dogs."""
-    print(f"Building JSON updates for {','.join(dog.name for dog in dogs)}")
-    return [dog.model_dump(mode="json") for dog in dogs]
-
-
-async def save_dogs(dogs) -> None:
-    if not dogs:
-        print("No dogs processed.")
-        return
-    for result in dogs:
-        print(f"Saving {Dog(**result)} to file.")
-        await SaveFileAction(
-            name="Save Dog Data",
-            file_path=f"dogs/{result['name']}.json",
-            data=result,
-            file_type="json",
-        )()
-
-
-async def build_chain(dogs: list[Dog]) -> ChainedAction:
-    return ChainedAction(
-        name="test_chain",
-        actions=[
-            Action(
-                name="build_json_updates",
-                action=build_json_updates,
-                kwargs={"dogs": dogs},
-            ),
-            ConfirmAction(
-                name="test_confirm",
-                prompt_message="Do you want to process the dogs?",
-                confirm_type="yes_no_cancel",
-                return_last_result=True,
-                inject_into="dogs",
-            ),
-            Action(
-                name="save_dogs",
-                action=save_dogs,
-                inject_into="dogs",
-            ),
-        ],
-        auto_inject=True,
-    )
-
-
-factory = ActionFactory(
-    name="Dog Post Factory",
-    factory=build_chain,
-    preview_kwargs={"dogs": ["Buddy", "Max"]},
-)
-
-
-def dog_config(parser: CommandArgumentParser) -> None:
-    parser.add_argument(
-        "dogs",
-        nargs="+",
-        action="action",
-        resolver=Action("Get Dogs", get_dogs),
-        lazy_resolver=False,
-        help="List of dogs to process.",
-    )
-    parser.add_tldr_examples(
-        [
-            ("max", "Process the dog named Max"),
-            ("bella buddy max", "Process the dogs named Bella, Buddy, and Max"),
-        ]
-    )
-
-
-async def main():
-    flx = Falyx("Save Dogs Example", program="confirm_example.py")
-
-    flx.add_command(
-        key="D",
-        description="Save Dog Data",
-        action=factory,
-        aliases=["save_dogs"],
-        argument_config=dog_config,
-    )
-
-    await flx.run()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

examples/falyx.yaml

@@ -1,32 +0,0 @@
-commands:
-  - key: P
-    description: Pipeline Demo
-    action: pipeline_demo.pipeline
-    tags: [pipeline, demo]
-    help_text: Run Deployment Pipeline with retries.
-
-  - key: G
-    description: Run HTTP Action Group
-    action: http_demo.action_group
-    tags: [http, demo]
-    confirm: true
-
-  - key: S
-    description: Select a file
-    action: file_select.sf
-    tags: [file, select, demo]
-
-  - key: M
-    description: Menu Demo
-    action: menu_demo.menu
-    tags: [menu, demo]
-    help_text: Run a menu demo with multiple options.
-
-submenus:
-  - key: C
-    description: Process Menu (From Config)
-    config: process.yaml
-
-  - key: U
-    description: Submenu From Python
-    submenu: submenu.submenu

examples/falyx_demo.py

@@ -1,162 +0,0 @@
-"""
-Falyx CLI Framework
-
-Copyright (c) 2025 rtj.dev LLC.
-Licensed under the MIT License. See LICENSE file for details.
-"""
-
-import asyncio
-import random
-
-from falyx.action import Action, ActionGroup, ChainedAction
-from falyx.falyx import Falyx
-from falyx.version import __version__
-
-
-class Foo:
-    def __init__(self, flx: Falyx) -> None:
-        self.flx = flx
-
-    async def build(self):
-        await asyncio.sleep(1)
-        print("✅ Build complete!")
-        return "Build complete!"
-
-    async def test(self):
-        await asyncio.sleep(1)
-        print("✅ Tests passed!")
-        return "Tests passed!"
-
-    async def deploy(self):
-        await asyncio.sleep(1)
-        print("✅ Deployment complete!")
-        return "Deployment complete!"
-
-    async def clean(self):
-        print("🧹 Cleaning...")
-        await asyncio.sleep(1)
-        print("✅ Clean complete!")
-        return "Clean complete!"
-
-    async def build_package(self):
-        print("🔨 Building...")
-        await asyncio.sleep(1)
-        print("✅ Build finished!")
-        return "Build finished!"
-
-    async def package(self):
-        print("📦 Packaging...")
-        await asyncio.sleep(1)
-        print("✅ Package complete!")
-        return "Package complete!"
-
-    async def run_tests(self):
-        print("🧪 Running tests...")
-        await asyncio.sleep(random.randint(1, 3))
-        print("✅ Tests passed!")
-        return "Tests passed!"
-
-    async def run_integration_tests(self):
-        print("🔗 Running integration tests...")
-        await asyncio.sleep(random.randint(1, 3))
-        print("✅ Integration tests passed!")
-        return "Integration tests passed!"
-
-    async def run_linter(self):
-        print("🧹 Running linter...")
-        await asyncio.sleep(random.randint(1, 3))
-        print("✅ Linter passed!")
-        return "Linter passed!"
-
-    async def run(self):
-        await self.flx.run()
-
-
-async def main() -> None:
-    """Build and return a Falyx instance with all your commands."""
-    flx = Falyx(
-        title="🚀 Falyx CLI",
-        columns=5,
-        welcome_message="Welcome to Falyx CLI!",
-        exit_message="Goodbye!",
-    )
-    foo = Foo(flx)
-
-    # --- Bottom bar info ---
-    flx.bottom_bar.columns = 3
-    flx.bottom_bar.add_toggle_from_option("B", "Verbose", flx.options, "verbose")
-    flx.bottom_bar.add_toggle_from_option("U", "Debug Hooks", flx.options, "debug_hooks")
-    flx.bottom_bar.add_static("Version", f"Falyx v{__version__}")
-
-    # --- Command actions ---
-
-    # --- Single Actions ---
-    flx.add_command(
-        key="B",
-        description="Build project",
-        action=Action("Build", foo.build),
-        tags=["build"],
-        spinner=True,
-        spinner_message="📦 Building...",
-    )
-    flx.add_command(
-        key="T",
-        description="Run tests",
-        action=Action("Test", foo.test),
-        tags=["test"],
-        spinner=True,
-        spinner_message="🧪 Running tests...",
-    )
-    flx.add_command(
-        key="D",
-        description="Deploy project",
-        action=Action("Deploy", foo.deploy),
-        tags=["deploy"],
-        spinner=True,
-        spinner_message="🚀 Deploying...",
-    )
-
-    # --- Build pipeline (ChainedAction) ---
-    pipeline = ChainedAction(
-        name="Full Build Pipeline",
-        actions=[
-            Action("Clean", foo.clean),
-            Action("Build", foo.build_package),
-            Action("Package", foo.package),
-        ],
-    )
-    flx.add_command(
-        key="P",
-        description="Run Build Pipeline",
-        action=pipeline,
-        tags=["build", "pipeline"],
-        spinner=True,
-        spinner_message="🔨 Running build pipeline...",
-        spinner_type="line",
-    )
-
-    # --- Test suite (ActionGroup) ---
-    test_suite = ActionGroup(
-        name="Test Suite",
-        actions=[
-            Action("Unit Tests", foo.run_tests),
-            Action("Integration Tests", foo.run_integration_tests),
-            Action("Lint", foo.run_linter),
-        ],
-    )
-    flx.add_command(
-        key="G",
-        description="Run All Tests",
-        action=test_suite,
-        tags=["test", "parallel"],
-        spinner=True,
-        spinner_type="line",
-    )
-    await foo.run()
-
-
-if __name__ == "__main__":
-    try:
-        asyncio.run(main())
-    except (KeyboardInterrupt, EOFError):
-        pass

examples/file_select.py

@@ -1,34 +0,0 @@
-import asyncio
-
-from falyx import Falyx
-from falyx.action import SelectFileAction
-from falyx.action.action_types import FileType
-
-sf = SelectFileAction(
-    name="select_file",
-    suffix_filter=".yaml",
-    title="Select a YAML file",
-    prompt_message="Choose 2 > ",
-    return_type=FileType.TEXT,
-    columns=3,
-    number_selections=2,
-)
-
-flx = Falyx(
-    title="File Selection Example",
-    description="This example demonstrates how to select files using Falyx.",
-    version="1.0.0",
-    program="file_select.py",
-    hide_menu_table=True,
-    show_placeholder_menu=True,
-)
-
-flx.add_command(
-    key="S",
-    description="Select a file",
-    action=sf,
-    help_text="Select a file from the current directory",
-)
-
-if __name__ == "__main__":
-    asyncio.run(flx.run())

examples/http.yaml

@@ -1,6 +0,0 @@
-commands:
-  - key: T
-    description: HTTP Test
-    action: single_http.http_action
-    tags: [http, demo]
-    help_text: Run HTTP test.

examples/http_demo.py

@@ -1,66 +0,0 @@
-import asyncio
-
-from rich.console import Console
-
-from falyx import Falyx
-from falyx.action import ActionGroup, HTTPAction
-from falyx.hooks import ResultReporter
-
-console = Console()
-
-
-action_group = ActionGroup(
-    "HTTP Group",
-    actions=[
-        HTTPAction(
-            name="Get Example",
-            method="GET",
-            url="https://jsonplaceholder.typicode.com/posts/1",
-            headers={"Accept": "application/json"},
-            retry=True,
-        ),
-        HTTPAction(
-            name="Post Example",
-            method="POST",
-            url="https://jsonplaceholder.typicode.com/posts",
-            headers={"Content-Type": "application/json"},
-            json={"title": "foo", "body": "bar", "userId": 1},
-            retry=True,
-        ),
-        HTTPAction(
-            name="Put Example",
-            method="PUT",
-            url="https://jsonplaceholder.typicode.com/posts/1",
-            headers={"Content-Type": "application/json"},
-            json={"id": 1, "title": "foo", "body": "bar", "userId": 1},
-            retry=True,
-        ),
-        HTTPAction(
-            name="Delete Example",
-            method="DELETE",
-            url="https://jsonplaceholder.typicode.com/posts/1",
-            headers={"Content-Type": "application/json"},
-            retry=True,
-        ),
-    ],
-)
-
-reporter = ResultReporter()
-
-action_group.hooks.register(
-    "on_success",
-    reporter.report,
-)
-
-flx = Falyx("HTTP Demo")
-
-flx.add_command(
-    key="G",
-    description="Run HTTP Action Group",
-    action=action_group,
-    spinner=True,
-)
-
-
-if __name__ == "__main__":
-    asyncio.run(flx.run())

examples/menu_demo.py

@@ -1,136 +0,0 @@
-import asyncio
-import time
-
-from falyx import Falyx
-from falyx.action import (
-    Action,
-    ActionGroup,
-    ChainedAction,
-    MenuAction,
-    ProcessAction,
-    PromptMenuAction,
-)
-from falyx.menu import MenuOption, MenuOptionMap
-from falyx.themes import OneColors
-
-
-# Basic coroutine for Action
-async def greet_user():
-    print("👋 Hello from a regular Action!")
-    await asyncio.sleep(0.5)
-    return "Greeted user."
-
-
-# Chain of tasks
-async def fetch_data():
-    print("📡 Fetching data...")
-    await asyncio.sleep(1)
-    return "data123"
-
-
-async def process_data(last_result):
-    print(f"⚙️ Processing: {last_result}")
-    await asyncio.sleep(1)
-    return f"processed({last_result})"
-
-
-async def save_data(last_result):
-    print(f"💾 Saving: {last_result}")
-    await asyncio.sleep(1)
-    return f"saved({last_result})"
-
-
-# Parallel tasks
-async def fetch_users():
-    print("👥 Fetching users...")
-    await asyncio.sleep(1)
-    return ["alice", "bob", "carol"]
-
-
-async def fetch_logs():
-    print("📝 Fetching logs...")
-    await asyncio.sleep(2)
-    return ["log1", "log2"]
-
-
-# CPU-bound task (simulate via blocking sleep)
-def heavy_computation():
-    print("🧠 Starting heavy computation...")
-    time.sleep(3)
-    print("✅ Finished computation.")
-    return 42
-
-
-# Define actions
-
-basic_action = Action("greet", greet_user)
-
-chained = ChainedAction(
-    name="data-pipeline",
-    actions=[
-        Action("fetch", fetch_data),
-        Action("process", process_data, inject_last_result=True),
-        Action("save", save_data, inject_last_result=True),
-    ],
-    auto_inject=True,
-)
-
-parallel = ActionGroup(
-    name="parallel-fetch",
-    actions=[
-        Action("fetch-users", fetch_users),
-        Action("fetch-logs", fetch_logs),
-    ],
-)
-
-process = ProcessAction(name="compute", action=heavy_computation)
-
-menu_options = MenuOptionMap(
-    {
-        "A": MenuOption("Run basic Action", basic_action, style=OneColors.LIGHT_YELLOW),
-        "C": MenuOption("Run ChainedAction", chained, style=OneColors.MAGENTA),
-        "P": MenuOption("Run ActionGroup (parallel)", parallel, style=OneColors.CYAN),
-        "H": MenuOption("Run ProcessAction (heavy task)", process, style=OneColors.GREEN),
-    }
-)
-
-
-# Menu setup
-
-menu = MenuAction(
-    name="main-menu",
-    title="Choose a task to run",
-    menu_options=menu_options,
-)
-
-
-prompt_menu = PromptMenuAction(
-    name="select-user",
-    menu_options=menu_options,
-)
-
-flx = Falyx(
-    title="🚀 Falyx Menu Demo",
-    welcome_message="Welcome to the Menu Demo!",
-    exit_message="Goodbye!",
-    columns=2,
-    never_prompt=False,
-)
-
-flx.add_command(
-    key="M",
-    description="Show Menu",
-    action=menu,
-    logging_hooks=True,
-)
-
-flx.add_command(
-    key="P",
-    description="Show Prompt Menu",
-    action=prompt_menu,
-    logging_hooks=True,
-)
-
-
-if __name__ == "__main__":
-    asyncio.run(flx.run())

examples/pipeline_demo.py

@@ -1,121 +0,0 @@
-import asyncio
-import random
-import time
-
-from falyx import Falyx
-from falyx.action import Action, ActionGroup, ChainedAction, ProcessAction
-from falyx.console import console
-
-
-# Step 1: Fast I/O-bound setup (standard Action)
-async def checkout_code():
-    console.print("🔄 Checking out code...")
-    await asyncio.sleep(0.5)
-    console.print("📦 Code checked out successfully.")
-
-
-# Step 2: CPU-bound task (ProcessAction)
-def run_static_analysis():
-    total = 0
-    for i in range(10_000_000):
-        total += i % 3
-    time.sleep(2)
-    return total
-
-
-# Step 3: Simulated flaky test with retry
-async def flaky_tests():
-    console.print("🧪 Running tests...")
-    await asyncio.sleep(0.3)
-    if random.random() < 0.3:
-        raise RuntimeError("❌ Random test failure!")
-    console.print("🧪 Tests passed.")
-    return "ok"
-
-
-# Step 4: Multiple deploy targets (parallel ActionGroup)
-async def deploy_to(target: str):
-    console.print(f"🚀 Deploying to {target}...")
-    await asyncio.sleep(random.randint(2, 6))
-    console.print(f"✅ Deployment to {target} complete.")
-    return f"{target} complete"
-
-
-def build_pipeline():
-    # Base actions
-    checkout = Action("Checkout", checkout_code)
-    analysis = ProcessAction(
-        "Static Analysis",
-        run_static_analysis,
-        spinner=True,
-        spinner_message="Analyzing code...",
-    )
-    analysis.hooks.register(
-        "before", lambda ctx: console.print("🧠 Running static analysis (CPU-bound)...")
-    )
-    analysis.hooks.register("after", lambda ctx: console.print("🧠 Analysis complete!"))
-    tests = Action(
-        "Run Tests",
-        flaky_tests,
-        retry=True,
-        spinner=True,
-        spinner_message="Running tests...",
-    )
-
-    # Parallel deploys
-    deploy_group = ActionGroup(
-        "Deploy to All",
-        [
-            Action(
-                "Deploy US",
-                deploy_to,
-                args=("us-west",),
-                spinner=True,
-                spinner_message="Deploying US...",
-            ),
-            Action(
-                "Deploy EU",
-                deploy_to,
-                args=("eu-central",),
-                spinner=True,
-                spinner_message="Deploying EU...",
-            ),
-            Action(
-                "Deploy Asia",
-                deploy_to,
-                args=("asia-east",),
-                spinner=True,
-                spinner_message="Deploying Asia...",
-            ),
-        ],
-    )
-
-    # Full pipeline
-    return ChainedAction("CI/CD Pipeline", [checkout, analysis, tests, deploy_group])
-
-
-pipeline = build_pipeline()
-
-
-# Run the pipeline
-async def main():
-
-    flx = Falyx(
-        hide_menu_table=True, program="pipeline_demo.py", show_placeholder_menu=True
-    )
-    flx.add_command(
-        "P",
-        "Run Pipeline",
-        pipeline,
-        spinner=True,
-        spinner_type="line",
-        spinner_message="Running pipeline...",
-        tags=["pipeline", "demo"],
-        help_text="Run the full CI/CD pipeline demo.",
-    )
-
-    await flx.run()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

examples/process.yaml

@@ -1,11 +0,0 @@
-commands:
-  - key: P
-    description: Pipeline Demo
-    action: pipeline_demo.pipeline
-    tags: [pipeline, demo]
-    help_text: Run Demployment Pipeline with retries.
-
-submenus:
-  - key: C
-    description: HTTP Test (Nested From Config)
-    config: http.yaml

examples/process_pool.py

@@ -1,36 +1,22 @@
+from falyx import Falyx, ProcessAction
+from falyx.themes.colors import NordColors as nc
 from rich.console import Console
 
-from falyx import Falyx
-from falyx.action import ProcessPoolAction
-from falyx.action.process_pool_action import ProcessTask
-from falyx.execution_registry import ExecutionRegistry as er
-from falyx.themes import NordColors as nc
-
 console = Console()
 falyx = Falyx(title="🚀 Process Pool Demo")
 
-
+def generate_primes(n):
-def generate_primes(start: int = 2, end: int = 100_000) -> list[int]:
+    primes = []
-    primes: list[int] = []
+    for num in range(2, n):
-    console.print(f"Generating primes from {start} to {end}...", style=nc.YELLOW)
-    for num in range(start, end):
         if all(num % p != 0 for p in primes):
             primes.append(num)
-    console.print(
+    console.print(f"Generated {len(primes)} primes up to {n}.", style=nc.GREEN)
-        f"Generated {len(primes)} primes from {start} to {end}.", style=nc.GREEN
-    )
     return primes
 
-
-actions = [ProcessTask(task=generate_primes)]
-
 # Will not block the event loop
-heavy_action = ProcessPoolAction(
+heavy_action = ProcessAction("Prime Generator", generate_primes, args=(100_000,))
-    name="Prime Generator",
-    actions=actions,
-)
 
-falyx.add_command("R", "Generate Primes", heavy_action)
+falyx.add_command("R", "Generate Primes", heavy_action, spinner=True)
 
 
 if __name__ == "__main__":

examples/run_key.py

@@ -1,32 +0,0 @@
-import asyncio
-
-from falyx import Falyx
-from falyx.action import Action
-
-
-async def main():
-    state = {"count": 0}
-
-    async def flaky():
-        if not state["count"]:
-            state["count"] += 1
-            print("Flaky step failed, retrying...")
-            raise RuntimeError("Random failure!")
-        return "ok"
-
-    # Add a command that raises an exception
-    falyx.add_command(
-        key="E",
-        description="Error Command",
-        action=Action("flaky", flaky),
-        retry=True,
-    )
-
-    result = await falyx.run_key("E")
-    print(result)
-    assert result == "ok"
-
-
-if __name__ == "__main__":
-    falyx = Falyx("Headless Recovery Test")
-    asyncio.run(main())

examples/selection_demo.py

@@ -1,70 +0,0 @@
-import asyncio
-from uuid import uuid4
-
-from falyx import Falyx
-from falyx.action import SelectionAction
-from falyx.selection import SelectionOption
-from falyx.signals import CancelSignal
-
-selections = {
-    "1": SelectionOption(
-        description="Production", value="3bc2616e-3696-11f0-a139-089204eb86ac"
-    ),
-    "2": SelectionOption(
-        description="Staging", value="42f2cd84-3696-11f0-a139-089204eb86ac"
-    ),
-}
-
-
-select = SelectionAction(
-    name="Select Deployment",
-    selections=selections,
-    title="Select a Deployment",
-    columns=2,
-    prompt_message="> ",
-    return_type="value",
-    show_table=True,
-)
-
-list_selections = [uuid4() for _ in range(10)]
-
-list_select = SelectionAction(
-    name="Select Deployments",
-    selections=list_selections,
-    title="Select Deployments",
-    columns=3,
-    prompt_message="Select 3 Deployments > ",
-    return_type="value",
-    show_table=True,
-    number_selections=3,
-)
-
-
-flx = Falyx()
-
-flx.add_command(
-    key="S",
-    description="Select a deployment",
-    action=select,
-    help_text="Select a deployment from the list",
-)
-flx.add_command(
-    key="L",
-    description="Select deployments",
-    action=list_select,
-    help_text="Select multiple deployments from the list",
-)
-
-if __name__ == "__main__":
-
-    try:
-        print(asyncio.run(select()))
-    except CancelSignal:
-        print("Selection was cancelled.")
-
-    try:
-        print(asyncio.run(list_select()))
-    except CancelSignal:
-        print("Selection was cancelled.")
-
-    asyncio.run(flx.run())

examples/shell_example.py

@@ -1,89 +0,0 @@
-#!/usr/bin/env python
-import asyncio
-
-from falyx import Falyx
-from falyx.action import Action, ChainedAction, ShellAction
-from falyx.hooks import ResultReporter
-from falyx.utils import setup_logging
-
-# Setup logging
-setup_logging()
-
-
-fx = Falyx("🚀 Falyx Demo")
-
-e = ShellAction("Shell", "echo Hello, {}!")
-
-fx.add_command(
-    key="R",
-    description="Echo a message",
-    action=e,
-)
-
-s = ShellAction("Ping", "ping -c 1 {}")
-
-fx.add_command(
-    key="P",
-    description="Ping a host",
-    action=s,
-)
-
-
-async def a1(last_result):
-    return f"Hello, {last_result}"
-
-
-async def a2(last_result):
-    return f"World! {last_result}"
-
-
-reporter = ResultReporter()
-
-a1 = Action("a1", a1, inject_last_result=True)
-a1.hooks.register(
-    "on_success",
-    reporter.report,
-)
-a2 = Action("a2", a2, inject_last_result=True)
-a2.hooks.register(
-    "on_success",
-    reporter.report,
-)
-
-
-async def normal():
-    print("Normal")
-    return "Normal"
-
-
-async def annotate(last_result):
-    return f"Annotated: {last_result}"
-
-
-async def whisper(last_result):
-    return last_result.lower()
-
-
-c1 = ChainedAction(
-    name="ShellDemo",
-    actions=[
-        # host,
-        ShellAction("Ping", "ping -c 1 {}"),
-        Action("Annotate", annotate),
-        Action("Whisper", whisper),
-    ],
-    auto_inject=True,
-)
-
-fx.add_command(
-    key="C",
-    description="Run a chain of actions",
-    action=c1,
-)
-
-
-async def main():
-    await fx.run()
-
-
-asyncio.run(main())

examples/simple.py

@@ -1,25 +1,21 @@
 import asyncio
 import random
 
-from falyx import Falyx
+from falyx import Falyx, Action, ChainedAction
-from falyx.action import Action, ChainedAction
 from falyx.utils import setup_logging
 
 setup_logging()
 
-
 # A flaky async step that fails randomly
-async def flaky_step() -> str:
+async def flaky_step():
     await asyncio.sleep(0.2)
     if random.random() < 0.5:
         raise RuntimeError("Random failure!")
-    print("ok")
     return "ok"
 
-
 # Create a retry handler
-step1 = Action(name="step_1", action=flaky_step)
+step1 = Action(name="step_1", action=flaky_step, retry=True)
-step2 = Action(name="step_2", action=flaky_step)
+step2 = Action(name="step_2", action=flaky_step, retry=True)
 
 # Chain the actions
 chain = ChainedAction(name="my_pipeline", actions=[step1, step2])
@@ -33,8 +29,6 @@ falyx.add_command(
     logging_hooks=True,
     preview_before_confirm=True,
     confirm=True,
-    retry_all=True,
-    spinner=True,
 )
 
 # Entry point

examples/single_http.py

@@ -1,14 +0,0 @@
-import asyncio
-
-from falyx.action import HTTPAction
-
-http_action = HTTPAction(
-    name="Get Example",
-    method="GET",
-    url="https://jsonplaceholder.typicode.com/posts/1",
-    headers={"Accept": "application/json"},
-    retry=True,
-)
-
-if __name__ == "__main__":
-    asyncio.run(http_action())

examples/submenu.py

@@ -1,53 +0,0 @@
-import asyncio
-import random
-
-from falyx import Falyx
-from falyx.action import Action, ChainedAction
-from falyx.utils import setup_logging
-
-setup_logging()
-
-
-# A flaky async step that fails randomly
-async def flaky_step():
-    await asyncio.sleep(0.2)
-    if random.random() < 0.5:
-        raise RuntimeError("Random failure!")
-    return "ok"
-
-
-step1 = Action(name="step_1", action=flaky_step, retry=True)
-step2 = Action(name="step_2", action=flaky_step, retry=True)
-
-# Chain the actions
-chain = ChainedAction(name="my_pipeline", actions=[step1, step2])
-
-# Create the CLI menu
-falyx = Falyx("🚀 Falyx Demo")
-falyx.add_command(
-    key="R",
-    description="Run My Pipeline",
-    action=chain,
-    logging_hooks=True,
-    preview_before_confirm=True,
-    confirm=True,
-)
-
-# Create a submenu
-submenu = Falyx("Submenu")
-submenu.add_command(
-    key="T",
-    description="Test",
-    action=lambda: "test",
-    logging_hooks=True,
-    preview_before_confirm=True,
-    confirm=True,
-)
-falyx.add_submenu(
-    key="S",
-    description="Submenu",
-    submenu=submenu,
-)
-
-if __name__ == "__main__":
-    asyncio.run(falyx.run())

examples/type_validation.py

@@ -1,100 +0,0 @@
-import asyncio
-from uuid import UUID, uuid4
-
-from falyx import Falyx
-from falyx.parser import CommandArgumentParser
-
-flx = Falyx("Test Type Validation")
-
-
-def uuid_val(value: str) -> str:
-    """Custom validator to ensure a string is a valid UUID."""
-    UUID(value)
-    return value
-
-
-async def print_uuid(uuid: str) -> str:
-    """Prints the UUID if valid."""
-    print(f"Valid UUID: {uuid}")
-    return uuid
-
-
-flx.add_command(
-    "U",
-    "Print a valid UUID (arguemnts)",
-    print_uuid,
-    arguments=[
-        {
-            "flags": ["uuid"],
-            "type": uuid_val,
-            "help": "A valid UUID string",
-        }
-    ],
-)
-
-
-def uuid_parser(parser: CommandArgumentParser) -> None:
-    """Custom parser to ensure the UUID argument is valid."""
-    parser.add_argument(
-        "uuid",
-        type=uuid_val,
-        help="A valid UUID string",
-    )
-
-
-flx.add_command(
-    "I",
-    "Print a valid UUID (argument_config)",
-    print_uuid,
-    argument_config=uuid_parser,
-)
-
-flx.add_command(
-    "D",
-    "Print a valid UUID (arg_metadata)",
-    print_uuid,
-    arg_metadata={
-        "uuid": {
-            "type": uuid_val,
-            "help": "A valid UUID string",
-        }
-    },
-)
-
-
-def custom_parser(arguments: list[str]) -> tuple[tuple, dict]:
-    """Custom parser to ensure the UUID argument is valid."""
-    if len(arguments) != 1:
-        raise ValueError("Exactly one argument is required")
-    uuid_val(arguments[0])
-    return (arguments[0],), {}
-
-
-flx.add_command(
-    "C",
-    "Print a valid UUID (custom_parser)",
-    print_uuid,
-    custom_parser=custom_parser,
-)
-
-
-async def generate_uuid() -> str:
-    """Generates a new UUID."""
-    new_uuid = uuid4()
-    print(f"Generated UUID: {new_uuid}")
-    return new_uuid
-
-
-flx.add_command(
-    "G",
-    "Generate a new UUID",
-    lambda: print(uuid4()),
-)
-
-
-async def main() -> None:
-    await flx.run()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

examples/user_input_demo.py

@@ -1,38 +0,0 @@
-import asyncio
-
-from prompt_toolkit.validation import Validator
-
-from falyx.action import Action, ChainedAction, UserInputAction
-
-
-def validate_alpha() -> Validator:
-    def validate(text: str) -> bool:
-        return text.isalpha()
-
-    return Validator.from_callable(
-        validate,
-        error_message="Please enter only alphabetic characters.",
-        move_cursor_to_end=True,
-    )
-
-
-chain = ChainedAction(
-    name="Demo Chain",
-    actions=[
-        "Name",
-        UserInputAction(
-            name="User Input",
-            prompt_message="Enter your {last_result}: ",
-            validator=validate_alpha(),
-        ),
-        Action(
-            name="Display Name",
-            action=lambda last_result: print(f"Hello, {last_result}!"),
-        ),
-    ],
-    auto_inject=True,
-)
-
-if __name__ == "__main__":
-    asyncio.run(chain.preview())
-    asyncio.run(chain())

falyx/__init__.py

@@ -1,19 +1,23 @@
-"""
-Falyx CLI Framework
-
-Copyright (c) 2025 rtj.dev LLC.
-Licensed under the MIT License. See LICENSE file for details.
-"""
-
 import logging
 
+from .action import Action, ActionGroup, ChainedAction, ProcessAction
+from .command import Command
+from .context import ExecutionContext, ResultsContext
 from .execution_registry import ExecutionRegistry
 from .falyx import Falyx
 
 logger = logging.getLogger("falyx")
 
+__version__ = "0.1.0"
 
 __all__ = [
+    "Action",
+    "ChainedAction",
+    "ActionGroup",
+    "ProcessAction",
     "Falyx",
+    "Command",
+    "ExecutionContext",
+    "ResultsContext",
     "ExecutionRegistry",
 ]

falyx/__main__.py

@@ -1,120 +1,42 @@
-"""
+# falyx/__main__.py
-Falyx CLI Framework
-
-Copyright (c) 2025 rtj.dev LLC.
-Licensed under the MIT License. See LICENSE file for details.
-"""
 
 import asyncio
-import os
+import logging
-import sys
-from argparse import ArgumentParser, Namespace, _SubParsersAction
-from pathlib import Path
-from typing import Any
 
-from falyx.config import loader
+from falyx.action import Action
 from falyx.falyx import Falyx
-from falyx.parser import CommandArgumentParser, get_root_parser, get_subparsers
 
 
-def find_falyx_config() -> Path | None:
+def build_falyx() -> Falyx:
-    candidates = [
+    """Build and return a Falyx instance with all your commands."""
-        Path.cwd() / "falyx.yaml",
+    app = Falyx(title="🚀 Falyx CLI")
-        Path.cwd() / "falyx.toml",
-        Path.cwd() / ".falyx.yaml",
-        Path.cwd() / ".falyx.toml",
-        Path(os.environ.get("FALYX_CONFIG", "falyx.yaml")),
-        Path.home() / ".config" / "falyx" / "falyx.yaml",
-        Path.home() / ".config" / "falyx" / "falyx.toml",
-        Path.home() / ".falyx.yaml",
-        Path.home() / ".falyx.toml",
-    ]
-    return next((p for p in candidates if p.exists()), None)
 
-
+    # Example commands
-def bootstrap() -> Path | None:
+    app.add_command(
-    config_path = find_falyx_config()
+        key="B",
-    if config_path and str(config_path.parent) not in sys.path:
+        description="Build project",
-        sys.path.insert(0, str(config_path.parent))
+        action=Action("Build", lambda: print("📦 Building...")),
-    return config_path
+        tags=["build"]
-
-
-def init_config(parser: CommandArgumentParser) -> None:
-    parser.add_argument(
-        "name",
-        type=str,
-        help="Name of the new Falyx project",
-        default=".",
-        nargs="?",
     )
 
-
+    app.add_command(
-def init_callback(args: Namespace) -> None:
+        key="T",
-    """Callback for the init command."""
+        description="Run tests",
-    if args.command == "init":
+        action=Action("Test", lambda: print("🧪 Running tests...")),
-        from falyx.init import init_project
+        tags=["test"]
-
-        init_project(args.name)
-    elif args.command == "init_global":
-        from falyx.init import init_global
-
-        init_global()
-
-
-def get_parsers() -> tuple[ArgumentParser, _SubParsersAction]:
-    root_parser: ArgumentParser = get_root_parser()
-    subparsers = get_subparsers(root_parser)
-    init_parser = subparsers.add_parser(
-        "init",
-        help="Initialize a new Falyx project",
-        description="Create a new Falyx project with mock configuration files.",
-        epilog="If no name is provided, the current directory will be used.",
-    )
-    init_parser.add_argument(
-        "name",
-        type=str,
-        help="Name of the new Falyx project",
-        default=".",
-        nargs="?",
-    )
-    subparsers.add_parser(
-        "init-global",
-        help="Initialize Falyx global configuration",
-        description="Create a global Falyx configuration at ~/.config/falyx/.",
-    )
-    return root_parser, subparsers
-
-
-def main() -> Any:
-    bootstrap_path = bootstrap()
-    if not bootstrap_path:
-        from falyx.init import init_global, init_project
-
-        flx: Falyx = Falyx()
-        flx.add_command(
-            "I",
-            "Initialize a new Falyx project",
-            init_project,
-            aliases=["init"],
-            argument_config=init_config,
-            help_epilog="If no name is provided, the current directory will be used.",
-        )
-        flx.add_command(
-            "G",
-            "Initialize Falyx global configuration",
-            init_global,
-            aliases=["init-global"],
-            help_text="Create a global Falyx configuration at ~/.config/falyx/.",
-        )
-    else:
-        flx = loader(bootstrap_path)
-
-    root_parser, subparsers = get_parsers()
-
-    return asyncio.run(
-        flx.run(root_parser=root_parser, subparsers=subparsers, callback=init_callback)
     )
 
+    app.add_command(
+        key="D",
+        description="Deploy project",
+        action=Action("Deploy", lambda: print("🚀 Deploying...")),
+        tags=["deploy"]
+    )
+
+    return app
 
 if __name__ == "__main__":
-    main()
+    logging.basicConfig(level=logging.WARNING)
+    falyx = build_falyx()
+    asyncio.run(falyx.run())
+

falyx/action.py

@@ -0,0 +1,537 @@
+"""action.py
+
+Any Action or Command is callable and supports the signature:
+    result = thing(*args, **kwargs)
+
+This guarantees:
+- Hook lifecycle (before/after/error/teardown)
+- Timing
+- Consistent return values
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import random
+from abc import ABC, abstractmethod
+from concurrent.futures import ProcessPoolExecutor
+from functools import partial
+from typing import Any, Callable
+
+from rich.console import Console
+from rich.tree import Tree
+
+from falyx.context import ExecutionContext, ResultsContext
+from falyx.debug import register_debug_hooks
+from falyx.exceptions import FalyxError
+from falyx.execution_registry import ExecutionRegistry as er
+from falyx.hook_manager import Hook, HookManager, HookType
+from falyx.retry import RetryHandler, RetryPolicy
+from falyx.themes.colors import OneColors
+from falyx.utils import ensure_async, logger
+
+console = Console()
+
+
+class BaseAction(ABC):
+    """
+    Base class for actions. Actions can be simple functions or more
+    complex actions like `ChainedAction` or `ActionGroup`. They can also
+    be run independently or as part of Menu.
+
+    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
+                                 (default: 'last_result').
+    """
+    def __init__(
+            self,
+            name: str,
+            hooks: HookManager | None = None,
+            inject_last_result: bool = False,
+            inject_last_result_as: str = "last_result",
+            logging_hooks: bool = False,
+    ) -> None:
+        self.name = name
+        self.hooks = hooks or HookManager()
+        self.is_retryable: bool = False
+        self.results_context: ResultsContext | None = None
+        self.inject_last_result: bool = inject_last_result
+        self.inject_last_result_as: str = inject_last_result_as
+
+        if logging_hooks:
+            register_debug_hooks(self.hooks)
+
+    async def __call__(self, *args, **kwargs) -> Any:
+        return await self._run(*args, **kwargs)
+
+    @abstractmethod
+    async def _run(self, *args, **kwargs) -> Any:
+        raise NotImplementedError("_run must be implemented by subclasses")
+
+    @abstractmethod
+    async def preview(self, parent: Tree | None = None):
+        raise NotImplementedError("preview must be implemented by subclasses")
+
+    def set_results_context(self, results_context: ResultsContext):
+        self.results_context = results_context
+
+    def prepare_for_chain(self, results_context: ResultsContext) -> BaseAction:
+        """
+        Prepare the action specifically for sequential (ChainedAction) execution.
+        Can be overridden for chain-specific logic.
+        """
+        self.set_results_context(results_context)
+        return self
+
+    def prepare_for_group(self, results_context: ResultsContext) -> BaseAction:
+        """
+        Prepare the action specifically for parallel (ActionGroup) execution.
+        Can be overridden for group-specific logic.
+        """
+        self.set_results_context(results_context)
+        return self
+
+    def _maybe_inject_last_result(self, kwargs: dict[str, Any]) -> dict[str, Any]:
+        if self.inject_last_result and self.results_context:
+            key = self.inject_last_result_as
+            if key in kwargs:
+                logger.warning("[%s] ⚠️ Overriding '%s' with last_result", self.name, key)
+            kwargs = dict(kwargs)
+            kwargs[key] = self.results_context.last_result()
+        return kwargs
+
+    def register_hooks_recursively(self, hook_type: HookType, hook: Hook):
+        """Register a hook for all actions and sub-actions."""
+        self.hooks.register(hook_type, hook)
+
+    @classmethod
+    def enable_retries_recursively(cls, action: BaseAction, policy: RetryPolicy | None):
+        if not policy:
+            policy = RetryPolicy(enabled=True)
+        if isinstance(action, Action):
+            action.retry_policy = policy
+            action.retry_policy.enabled = True
+            action.hooks.register(HookType.ON_ERROR, RetryHandler(policy).retry_on_error)
+
+        if hasattr(action, "actions"):
+            for sub in action.actions:
+                cls.enable_retries_recursively(sub, policy)
+
+    async def _write_stdout(self, data: str) -> None:
+        """Override in subclasses that produce terminal output."""
+        pass
+
+    def __str__(self):
+        return f"<{self.__class__.__name__} '{self.name}'>"
+
+    def __repr__(self):
+        return str(self)
+
+    def __or__(self, other: BaseAction) -> ChainedAction:
+        """Chain this action with another action."""
+        if not isinstance(other, BaseAction):
+            raise FalyxError(f"Cannot chain {type(other)} with {type(self)}")
+        return ChainedAction(name=f"{self.name} | {other.name}", actions=[self, other])
+
+    async def __ror__(self, other: Any):
+        if inspect.isawaitable(other):
+            print(1)
+            other = await other
+
+        if self.inject_last_result:
+            print(2)
+            return await self(**{self.inject_last_result_as: other})
+
+        literal_action = Action(
+            name=f"Input | {self.name}",
+            action=lambda: other,
+        )
+
+        chain = ChainedAction(name=f"{other} | {self.name}", actions=[literal_action, self])
+        print(3)
+        print(self.name, other)
+        return await chain()
+
+class Action(BaseAction):
+    """A simple action that runs a callable. It can be a function or a coroutine."""
+    def __init__(
+            self,
+            name: str,
+            action,
+            rollback=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",
+            retry: bool = False,
+            retry_policy: RetryPolicy | None = None,
+    ) -> None:
+        super().__init__(name, hooks, inject_last_result, inject_last_result_as)
+        self.action = ensure_async(action)
+        self.rollback = rollback
+        self.args = args
+        self.kwargs = kwargs or {}
+        self.is_retryable = True
+        self.retry_policy = retry_policy or RetryPolicy()
+        if retry or (retry_policy and retry_policy.enabled):
+            self.enable_retry()
+
+    def enable_retry(self):
+        """Enable retry with the existing retry policy."""
+        self.retry_policy.enabled = True
+        logger.debug(f"[Action:{self.name}] Registering retry handler")
+        handler = RetryHandler(self.retry_policy)
+        self.hooks.register(HookType.ON_ERROR, handler.retry_on_error)
+
+    def set_retry_policy(self, policy: RetryPolicy):
+        """Set a new retry policy and re-register the handler."""
+        self.retry_policy = policy
+        self.enable_retry()
+
+    async def _run(self, *args, **kwargs) -> Any:
+        combined_args = args + self.args
+        combined_kwargs = self._maybe_inject_last_result({**self.kwargs, **kwargs})
+
+        context = ExecutionContext(
+            name=self.name,
+            args=combined_args,
+            kwargs=combined_kwargs,
+            action=self,
+        )
+        context.start_timer()
+        try:
+            await self.hooks.trigger(HookType.BEFORE, context)
+            result = await self.action(*combined_args, **combined_kwargs)
+            context.result = result
+            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)
+            if context.result is not None:
+                logger.info("[%s] ✅ Recovered: %s", self.name, self.name)
+                return context.result
+            raise error
+        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_b}]⚙ Action[/] '{self.name}'"]
+        if self.inject_last_result:
+            label.append(f" [dim](injects '{self.inject_last_result_as}')[/dim]")
+        if self.retry_policy.enabled:
+            label.append(
+                f"\n[dim]↻ Retries:[/] {self.retry_policy.max_retries}x, "
+                f"delay {self.retry_policy.delay}s, backoff {self.retry_policy.backoff}x"
+            )
+
+        if parent:
+            parent.add("".join(label))
+        else:
+            console.print(Tree("".join(label)))
+
+
+class LiteralInputAction(Action):
+    def __init__(self, value: Any):
+        async def literal(*args, **kwargs): return value
+        super().__init__("Input", literal, inject_last_result=True)
+
+
+class ActionListMixin:
+    """Mixin for managing a list of actions."""
+    def __init__(self) -> None:
+        self.actions: list[BaseAction] = []
+
+    def set_actions(self, actions: list[BaseAction]) -> None:
+        """Replaces the current action list with a new one."""
+        self.actions.clear()
+        for action in actions:
+            self.add_action(action)
+
+    def add_action(self, action: BaseAction) -> None:
+        """Adds an action to the list."""
+        self.actions.append(action)
+
+    def remove_action(self, name: str) -> None:
+        """Removes an action by name."""
+        self.actions = [action for action in self.actions if action.name != name]
+
+    def has_action(self, name: str) -> bool:
+        """Checks if an action with the given name exists."""
+        return any(action.name == name for action in self.actions)
+
+    def get_action(self, name: str) -> BaseAction | None:
+        """Retrieves an action by name."""
+        for action in self.actions:
+            if action.name == name:
+                return action
+        return None
+
+
+class ChainedAction(BaseAction, ActionListMixin):
+    """A ChainedAction is a sequence of actions that are executed in order."""
+    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",
+    ) -> None:
+        super().__init__(name, hooks, inject_last_result, inject_last_result_as)
+        ActionListMixin.__init__(self)
+        if actions:
+            self.set_actions(actions)
+
+    async def _run(self, *args, **kwargs) -> list[Any]:
+        results_context = ResultsContext(name=self.name)
+        if self.results_context:
+            results_context.add_result(self.results_context.last_result())
+        updated_kwargs = self._maybe_inject_last_result(kwargs)
+        context = ExecutionContext(
+            name=self.name,
+            args=args,
+            kwargs=updated_kwargs,
+            action=self,
+            extra={"results": [], "rollback_stack": []},
+        )
+        context.start_timer()
+        try:
+            await self.hooks.trigger(HookType.BEFORE, context)
+            last_result = self.results_context.last_result() if self.results_context else None
+
+
+
+            for index, action in enumerate(self.actions):
+                results_context.current_index = index
+                prepared = action.prepare_for_chain(results_context)
+                run_kwargs = dict(updated_kwargs)
+
+                underlying = getattr(prepared, "action", None)
+                if underlying:
+                    signature = inspect.signature(underlying)
+                else:
+                    signature = inspect.signature(prepared._run)
+                parameters = signature.parameters
+
+                if last_result is not None:
+                    if action.inject_last_result_as in parameters:
+                        run_kwargs[action.inject_last_result_as] = last_result
+                        result = await prepared(*args, **run_kwargs)
+                    elif (
+                        len(parameters) == 1 and
+                        not parameters.get("self")
+                    ):
+                        result = await prepared(last_result)
+                    else:
+                        result = await prepared(*args, **updated_kwargs)
+                else:
+                    result = await prepared(*args, **updated_kwargs)
+                last_result = result
+                results_context.add_result(result)
+                context.extra["results"].append(result)
+                context.extra["rollback_stack"].append(prepared)
+
+            context.result = last_result
+            await self.hooks.trigger(HookType.ON_SUCCESS, context)
+            return last_result
+
+        except Exception as error:
+            context.exception = error
+            results_context.errors.append((results_context.current_index, error))
+            await self._rollback(context.extra["rollback_stack"], *args, **kwargs)
+            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 _rollback(self, rollback_stack, *args, **kwargs):
+        for action in reversed(rollback_stack):
+            rollback = getattr(action, "rollback", None)
+            if rollback:
+                try:
+                    logger.warning("[%s] ↩️ Rolling back...", action.name)
+                    await action.rollback(*args, **kwargs)
+                except Exception as error:
+                    logger.error("[%s]⚠️ Rollback failed: %s", action.name, error)
+
+    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]")
+        tree = parent.add("".join(label)) if parent else Tree("".join(label))
+        for action in self.actions:
+            await action.preview(parent=tree)
+        if not parent:
+            console.print(tree)
+
+    def register_hooks_recursively(self, hook_type: HookType, hook: Hook):
+        """Register a hook for all actions and sub-actions."""
+        self.hooks.register(hook_type, hook)
+        for action in self.actions:
+            action.register_hooks_recursively(hook_type, hook)
+
+
+class ActionGroup(BaseAction, ActionListMixin):
+    """An ActionGroup is a collection of actions that can be run in parallel."""
+    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",
+    ):
+        super().__init__(name, hooks, inject_last_result, inject_last_result_as)
+        ActionListMixin.__init__(self)
+        if actions:
+            self.set_actions(actions)
+
+    async def _run(self, *args, **kwargs) -> list[tuple[str, Any]]:
+        results_context = ResultsContext(name=self.name, is_parallel=True)
+        if self.results_context:
+            results_context.set_shared_result(self.results_context.last_result())
+        updated_kwargs = self._maybe_inject_last_result(kwargs)
+        context = ExecutionContext(
+            name=self.name,
+            args=args,
+            kwargs=updated_kwargs,
+            action=self,
+            extra={"results": [], "errors": []},
+        )
+        async def run_one(action: BaseAction):
+            try:
+                prepared = action.prepare_for_group(results_context)
+                result = await prepared(*args, **updated_kwargs)
+                results_context.add_result((action.name, result))
+                context.extra["results"].append((action.name, result))
+            except Exception as error:
+                results_context.errors.append((results_context.current_index, error))
+                context.extra["errors"].append((action.name, error))
+
+        context.start_timer()
+        try:
+            await self.hooks.trigger(HookType.BEFORE, context)
+            await asyncio.gather(*[run_one(a) for a in self.actions])
+
+            if context.extra["errors"]:
+                context.exception = Exception(
+                    f"{len(context.extra['errors'])} action(s) failed: "
+                    f"{' ,'.join(name for name, _ in context.extra["errors"])}"
+                )
+                await self.hooks.trigger(HookType.ON_ERROR, context)
+                raise context.exception
+
+            context.result = context.extra["results"]
+            await self.hooks.trigger(HookType.ON_SUCCESS, context)
+            return context.result
+
+        except Exception as error:
+            context.exception = error
+            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.MAGENTA_b}]⏩ ActionGroup (parallel)[/] '{self.name}'"]
+        if self.inject_last_result:
+            label.append(f" [dim](receives '{self.inject_last_result_as}')[/dim]")
+        tree = parent.add("".join(label)) if parent else Tree("".join(label))
+        actions = self.actions.copy()
+        random.shuffle(actions)
+        await asyncio.gather(*(action.preview(parent=tree) for action in actions))
+        if not parent:
+            console.print(tree)
+
+    def register_hooks_recursively(self, hook_type: HookType, hook: Hook):
+        """Register a hook for all actions and sub-actions."""
+        super().register_hooks_recursively(hook_type, hook)
+        for action in self.actions:
+            action.register_hooks_recursively(hook_type, hook)
+
+
+class ProcessAction(BaseAction):
+    """A ProcessAction runs a function in a separate process using ProcessPoolExecutor."""
+    def __init__(
+        self,
+        name: str,
+        func: 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",
+    ):
+        super().__init__(name, hooks, inject_last_result, inject_last_result_as)
+        self.func = func
+        self.args = args
+        self.kwargs = kwargs or {}
+        self.executor = executor or ProcessPoolExecutor()
+        self.is_retryable = True
+
+    async def _run(self, *args, **kwargs):
+        if self.inject_last_result:
+            last_result = self.results_context.last_result()
+            if not self._validate_pickleable(last_result):
+                raise ValueError(
+                    f"Cannot inject last result into {self.name}: "
+                    f"last result is not pickleable."
+                )
+        combined_args = args + self.args
+        combined_kwargs = self._maybe_inject_last_result({**self.kwargs, **kwargs})
+        context = ExecutionContext(
+            name=self.name,
+            args=combined_args,
+            kwargs=combined_kwargs,
+            action=self,
+        )
+        loop = asyncio.get_running_loop()
+
+        context.start_timer()
+        try:
+            await self.hooks.trigger(HookType.BEFORE, context)
+            result = await loop.run_in_executor(
+                self.executor, partial(self.func, *combined_args, **combined_kwargs)
+            )
+            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)
+            if context.result is not None:
+                return context.result
+            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.DARK_YELLOW_b}]🧠 ProcessAction (new process)[/] '{self.name}'"]
+        if self.inject_last_result:
+            label.append(f" [dim](injects '{self.inject_last_result_as}')[/dim]")
+        if parent:
+            parent.add("".join(label))
+        else:
+            console.print(Tree("".join(label)))
+
+    def _validate_pickleable(self, obj: Any) -> bool:
+        try:
+            import pickle
+            pickle.dumps(obj)
+            return True
+        except (pickle.PicklingError, TypeError):
+            return False

falyx/action/__init__.py

@@ -1,52 +0,0 @@
-"""
-Falyx CLI Framework
-
-Copyright (c) 2025 rtj.dev LLC.
-Licensed under the MIT License. See LICENSE file for details.
-"""
-
-from .action import Action
-from .action_factory import ActionFactory
-from .action_group import ActionGroup
-from .base_action import BaseAction
-from .chained_action import ChainedAction
-from .confirm_action import ConfirmAction
-from .fallback_action import FallbackAction
-from .http_action import HTTPAction
-from .io_action import BaseIOAction
-from .literal_input_action import LiteralInputAction
-from .load_file_action import LoadFileAction
-from .menu_action import MenuAction
-from .process_action import ProcessAction
-from .process_pool_action import ProcessPoolAction
-from .prompt_menu_action import PromptMenuAction
-from .save_file_action import SaveFileAction
-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
-
-__all__ = [
-    "Action",
-    "ActionGroup",
-    "BaseAction",
-    "ChainedAction",
-    "ProcessAction",
-    "ActionFactory",
-    "HTTPAction",
-    "BaseIOAction",
-    "ShellAction",
-    "SelectionAction",
-    "SelectFileAction",
-    "MenuAction",
-    "SignalAction",
-    "FallbackAction",
-    "LiteralInputAction",
-    "UserInputAction",
-    "PromptMenuAction",
-    "ProcessPoolAction",
-    "LoadFileAction",
-    "SaveFileAction",
-    "ConfirmAction",
-]

falyx/action/action.py

@@ -1,210 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `Action`, the core atomic unit in the Falyx CLI framework, used to wrap and
-execute a single callable or coroutine with structured lifecycle support.
-
-An `Action` is the simplest building block in Falyx's execution model, enabling
-developers to turn ordinary Python functions into hookable, retryable, introspectable
-workflow steps. It supports synchronous or asynchronous callables, argument injection,
-rollback handlers, and retry policies.
-
-Key Features:
-- Lifecycle hooks: `before`, `on_success`, `on_error`, `after`, `on_teardown`
-- Optional `last_result` injection for chained workflows
-- Retry logic via configurable `RetryPolicy` and `RetryHandler`
-- Rollback function support for recovery and undo behavior
-- Rich preview output for introspection and dry-run diagnostics
-
-Usage Scenarios:
-- Wrapping business logic, utility functions, or external API calls
-- Converting lightweight callables into structured CLI actions
-- Composing workflows using `Action`, `ChainedAction`, or `ActionGroup`
-
-Example:
-    def compute(x, y):
-        return x + y
-
-    Action(
-        name="AddNumbers",
-        action=compute,
-        args=(2, 3),
-    )
-
-This module serves as the foundation for building robust, observable,
-and composable CLI automation flows in Falyx.
-"""
-from __future__ import annotations
-
-from typing import Any, Awaitable, Callable
-
-from rich.tree import Tree
-
-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
-from falyx.logger import logger
-from falyx.retry import RetryHandler, RetryPolicy
-from falyx.themes import OneColors
-from falyx.utils import ensure_async
-
-
-class Action(BaseAction):
-    """
-    Action wraps a simple function or coroutine into a standard executable unit.
-
-    It supports:
-    - Optional retry logic.
-    - Hook lifecycle (before, success, error, after, teardown).
-    - Last result injection for chaining.
-    - Optional rollback handlers for undo logic.
-
-    Args:
-        name (str): Name of the action. Used for logging and debugging.
-        action (Callable): The function or coroutine to execute.
-        rollback (Callable, optional): Rollback function to undo the action.
-        args (tuple, optional): Positional arguments.
-        kwargs (dict, optional): Keyword arguments.
-        hooks (HookManager, optional): Hook manager for lifecycle events.
-        inject_last_result (bool, optional): Enable last_result injection.
-        inject_into (str, optional): Name of injected key.
-        retry (bool, optional): Enable retry logic.
-        retry_policy (RetryPolicy, optional): Retry settings.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        action: Callable[..., Any] | Callable[..., Awaitable[Any]],
-        *,
-        rollback: Callable[..., Any] | Callable[..., Awaitable[Any]] | None = None,
-        args: tuple[Any, ...] = (),
-        kwargs: dict[str, Any] | None = None,
-        hooks: HookManager | None = None,
-        inject_last_result: bool = False,
-        inject_into: str = "last_result",
-        never_prompt: bool | None = None,
-        logging_hooks: bool = False,
-        retry: bool = False,
-        retry_policy: RetryPolicy | None = None,
-        spinner: bool = False,
-        spinner_message: str = "Processing...",
-        spinner_type: str = "dots",
-        spinner_style: str = OneColors.CYAN,
-        spinner_speed: float = 1.0,
-    ) -> None:
-        super().__init__(
-            name,
-            hooks=hooks,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-            never_prompt=never_prompt,
-            logging_hooks=logging_hooks,
-            spinner=spinner,
-            spinner_message=spinner_message,
-            spinner_type=spinner_type,
-            spinner_style=spinner_style,
-            spinner_speed=spinner_speed,
-        )
-        self.action = action
-        self.rollback = rollback
-        self.args = args
-        self.kwargs = kwargs or {}
-        self.is_retryable = True
-        self.retry_policy = retry_policy or RetryPolicy()
-        if retry or (retry_policy and retry_policy.enabled):
-            self.enable_retry()
-
-    @property
-    def action(self) -> Callable[..., Awaitable[Any]]:
-        return self._action
-
-    @action.setter
-    def action(self, value: Callable[..., Awaitable[Any]]):
-        self._action = ensure_async(value)
-
-    @property
-    def rollback(self) -> Callable[..., Awaitable[Any]] | None:
-        return self._rollback
-
-    @rollback.setter
-    def rollback(self, value: Callable[..., Awaitable[Any]] | None):
-        if value is None:
-            self._rollback = None
-        else:
-            self._rollback = ensure_async(value)
-
-    def enable_retry(self):
-        """Enable retry with the existing retry policy."""
-        self.retry_policy.enable_policy()
-        logger.debug("[%s] Registering retry handler", self.name)
-        handler = RetryHandler(self.retry_policy)
-        self.hooks.register(HookType.ON_ERROR, handler.retry_on_error)
-
-    def set_retry_policy(self, policy: RetryPolicy):
-        """Set a new retry policy and re-register the handler."""
-        self.retry_policy = policy
-        if policy.enabled:
-            self.enable_retry()
-
-    def get_infer_target(self) -> tuple[Callable[..., Any], None]:
-        """
-        Returns the callable to be used for argument inference.
-        By default, it returns the action itself.
-        """
-        return self.action, None
-
-    async def _run(self, *args, **kwargs) -> Any:
-        combined_args = args + self.args
-        combined_kwargs = self._maybe_inject_last_result({**self.kwargs, **kwargs})
-
-        context = ExecutionContext(
-            name=self.name,
-            args=combined_args,
-            kwargs=combined_kwargs,
-            action=self,
-        )
-
-        context.start_timer()
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-            result = await self.action(*combined_args, **combined_kwargs)
-            context.result = result
-            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)
-            if context.result is not None:
-                logger.info("[%s] Recovered: %s", self.name, self.name)
-                return context.result
-            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_b}]⚙ Action[/] '{self.name}'"]
-        if self.inject_last_result:
-            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, "
-                f"delay {self.retry_policy.delay}s, backoff {self.retry_policy.backoff}x"
-            )
-
-        if parent:
-            parent.add("".join(label))
-        else:
-            self.console.print(Tree("".join(label)))
-
-    def __str__(self):
-        return (
-            f"Action(name={self.name!r}, action="
-            f"{getattr(self._action, '__name__', repr(self._action))}, "
-            f"args={self.args!r}, kwargs={self.kwargs!r}, "
-            f"retry={self.retry_policy.enabled}, "
-            f"rollback={self.rollback is not None})"
-        )

falyx/action/action_factory.py

@@ -1,178 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `ActionFactory`, a dynamic Falyx Action that defers the construction of its
-underlying logic to runtime using a user-defined factory function.
-
-This pattern is useful when the specific Action to execute cannot be determined until
-execution time—such as when branching on data, generating parameterized HTTP requests,
-or selecting configuration-aware flows. `ActionFactory` integrates seamlessly with the
-Falyx lifecycle system and supports hook propagation, teardown registration, and
-contextual previewing.
-
-Key Features:
-- Accepts a factory function that returns a `BaseAction` instance
-- Supports injection of `last_result` and arbitrary args/kwargs
-- Integrates into chained or standalone workflows
-- Automatically previews generated action tree
-- Propagates shared context and teardown hooks to the returned action
-
-Common Use Cases:
-- Conditional or data-driven action generation
-- Configurable workflows with dynamic behavior
-- Adapter for factory-style dependency injection in CLI flows
-
-Example:
-    def generate_request_action(env):
-        return HTTPAction(f"GET /status/{env}", url=f"https://api/{env}/status")
-
-    ActionFactory(
-        name="GetEnvStatus",
-        factory=generate_request_action,
-        inject_last_result=True,
-    )
-"""
-from typing import Any, Callable
-
-from rich.tree import Tree
-
-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
-from falyx.logger import logger
-from falyx.protocols import ActionFactoryProtocol
-from falyx.themes import OneColors
-from falyx.utils import ensure_async
-
-
-class ActionFactory(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. Used for logging and debugging.
-        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.
-        args (tuple, optional): Positional arguments for the factory.
-        kwargs (dict, optional): Keyword arguments for the factory.
-        preview_args (tuple, optional): Positional arguments for the preview.
-        preview_kwargs (dict, optional): Keyword arguments for the preview.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        factory: ActionFactoryProtocol,
-        *,
-        inject_last_result: bool = False,
-        inject_into: str = "last_result",
-        args: tuple[Any, ...] = (),
-        kwargs: dict[str, Any] | None = None,
-        preview_args: tuple[Any, ...] = (),
-        preview_kwargs: dict[str, Any] | None = None,
-    ):
-        super().__init__(
-            name=name,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-        )
-        self.factory = factory
-        self.args = args
-        self.kwargs = kwargs or {}
-        self.preview_args = preview_args
-        self.preview_kwargs = preview_kwargs or {}
-
-    @property
-    def factory(self) -> ActionFactoryProtocol:
-        return self._factory  # type: ignore[return-value]
-
-    @factory.setter
-    def factory(self, value: ActionFactoryProtocol):
-        self._factory = ensure_async(value)
-
-    def get_infer_target(self) -> tuple[Callable[..., Any], None]:
-        return self.factory, None
-
-    async def _run(self, *args, **kwargs) -> Any:
-        args = (*self.args, *args)
-        kwargs = {**self.kwargs, **kwargs}
-        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 = await self.factory(*args, **updated_kwargs)
-            if not isinstance(generated_action, BaseAction):
-                raise TypeError(
-                    f"[{self.name}] Factory must return a BaseAction, got "
-                    f"{type(generated_action).__name__}"
-                )
-            if self.shared_context:
-                generated_action.set_shared_context(self.shared_context)
-                if hasattr(generated_action, "register_teardown") and callable(
-                    generated_action.register_teardown
-                ):
-                    generated_action.register_teardown(self.shared_context.action.hooks)
-                    logger.debug(
-                        "[%s] Registered teardown for %s",
-                        self.name,
-                        generated_action.name,
-                    )
-            if self.options_manager:
-                generated_action.set_options_manager(self.options_manager)
-            context.result = await generated_action()
-            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 = None
-            if self.args or self.kwargs:
-                try:
-                    generated = await self.factory(*self.args, **self.kwargs)
-                except TypeError:
-                    ...
-
-            if not generated:
-                generated = await 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)
-
-    def __str__(self) -> str:
-        return (
-            f"ActionFactory(name={self.name!r}, "
-            f"inject_last_result={self.inject_last_result}, "
-            f"factory={self._factory.__name__ if hasattr(self._factory, '__name__') else type(self._factory).__name__}, "
-            f"args={self.args!r}, kwargs={self.kwargs!r})"
-        )

falyx/action/action_group.py

@@ -1,248 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `ActionGroup`, a Falyx Action that executes multiple sub-actions concurrently
-using asynchronous parallelism.
-
-`ActionGroup` is designed for workflows where several independent actions can run
-simultaneously to improve responsiveness and reduce latency. It ensures robust error
-isolation, shared result tracking, and full lifecycle hook integration while preserving
-Falyx's introspectability and chaining capabilities.
-
-Key Features:
-- Executes all actions in parallel via `asyncio.gather`
-- Aggregates results as a list of `(name, result)` tuples
-- Collects and reports multiple errors without interrupting execution
-- Compatible with `SharedContext`, `OptionsManager`, and `last_result` injection
-- Teardown-aware: propagates teardown registration across all child actions
-- Fully previewable via Rich tree rendering
-
-Use Cases:
-- Batch execution of independent tasks (e.g., multiple file operations, API calls)
-- Concurrent report generation or validations
-- High-throughput CLI pipelines where latency is critical
-
-Raises:
-- `EmptyGroupError`: If no actions are added to the group
-- `Exception`: Summarizes all failed actions after execution
-
-Example:
-    ActionGroup(
-        name="ParallelChecks",
-        actions=[Action(...), Action(...), ChainedAction(...)],
-    )
-
-This module complements `ChainedAction` by offering breadth-wise (parallel) execution
-as opposed to depth-wise (sequential) execution.
-"""
-import asyncio
-import random
-from typing import Any, Awaitable, Callable, Sequence
-
-from rich.tree import Tree
-
-from falyx.action.action import Action
-from falyx.action.action_mixins import ActionListMixin
-from falyx.action.base_action import BaseAction
-from falyx.context import ExecutionContext, SharedContext
-from falyx.exceptions import EmptyGroupError
-from falyx.execution_registry import ExecutionRegistry as er
-from falyx.hook_manager import Hook, HookManager, HookType
-from falyx.logger import logger
-from falyx.options_manager import OptionsManager
-from falyx.parser.utils import same_argument_definitions
-from falyx.themes.colors import OneColors
-
-
-class ActionGroup(BaseAction, ActionListMixin):
-    """
-    ActionGroup executes multiple actions concurrently in parallel.
-
-    It is ideal for independent tasks that can be safely run simultaneously,
-    improving overall throughput and responsiveness of workflows.
-
-    Core features:
-    - Parallel execution of all contained actions.
-    - Shared last_result injection across all actions if configured.
-    - Aggregated collection of individual results as (name, result) pairs.
-    - Hook lifecycle support (before, on_success, on_error, after, on_teardown).
-    - Error aggregation: captures all action errors and reports them together.
-
-    Behavior:
-    - If any action fails, the group collects the errors but continues executing
-      other actions without interruption.
-    - After all actions complete, ActionGroup raises a single exception summarizing
-      all failures, or returns all results if successful.
-
-    Best used for:
-    - Batch processing multiple independent tasks.
-    - Reducing latency for workflows with parallelizable steps.
-    - Isolating errors while maximizing successful execution.
-
-    Args:
-        name (str): Name of the chain.
-        actions (list): List of actions or literals to execute.
-        args (tuple, optional): Positional arguments.
-        kwargs (dict, optional): Keyword arguments.
-        hooks (HookManager, optional): Hooks for lifecycle events.
-        inject_last_result (bool, optional): Whether to inject last results into kwargs
-                                             by default.
-        inject_into (str, optional): Key name for injection.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        actions: (
-            Sequence[BaseAction | Callable[..., Any] | Callable[..., Awaitable]] | None
-        ) = None,
-        *,
-        args: tuple[Any, ...] = (),
-        kwargs: dict[str, Any] | None = None,
-        hooks: HookManager | None = None,
-        inject_last_result: bool = False,
-        inject_into: str = "last_result",
-        never_prompt: bool | None = None,
-        logging_hooks: bool = False,
-        spinner: bool = False,
-        spinner_message: str = "Processing...",
-        spinner_type: str = "dots",
-        spinner_style: str = OneColors.CYAN,
-        spinner_speed: float = 1.0,
-    ):
-        super().__init__(
-            name,
-            hooks=hooks,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-            never_prompt=never_prompt,
-            logging_hooks=logging_hooks,
-            spinner=spinner,
-            spinner_message=spinner_message,
-            spinner_type=spinner_type,
-            spinner_style=spinner_style,
-            spinner_speed=spinner_speed,
-        )
-        ActionListMixin.__init__(self)
-        self.args = args
-        self.kwargs = kwargs or {}
-        if actions:
-            self.set_actions(actions)
-
-    def _wrap_if_needed(self, action: BaseAction | Callable[..., Any]) -> BaseAction:
-        if isinstance(action, BaseAction):
-            return action
-        elif callable(action):
-            return Action(name=action.__name__, action=action)
-        else:
-            raise TypeError(
-                "ActionGroup only accepts BaseAction or callable, got "
-                f"{type(action).__name__}"
-            )
-
-    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 set_options_manager(self, options_manager: OptionsManager) -> None:
-        super().set_options_manager(options_manager)
-        for action in self.actions:
-            action.set_options_manager(options_manager)
-
-    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
-        arg_defs = same_argument_definitions(self.actions)
-        if arg_defs:
-            return self.actions[0].get_infer_target()
-        logger.debug(
-            "[%s] auto_args disabled: mismatched ActionGroup arguments",
-            self.name,
-        )
-        return None, None
-
-    async def _run(self, *args, **kwargs) -> list[tuple[str, Any]]:
-        if not self.actions:
-            raise EmptyGroupError(f"[{self.name}] No actions to execute.")
-
-        combined_args = args + self.args
-        combined_kwargs = {**self.kwargs, **kwargs}
-
-        shared_context = SharedContext(name=self.name, action=self, is_parallel=True)
-        if self.shared_context:
-            shared_context.set_shared_result(self.shared_context.last_result())
-        updated_kwargs = self._maybe_inject_last_result(combined_kwargs)
-        context = ExecutionContext(
-            name=self.name,
-            args=combined_args,
-            kwargs=updated_kwargs,
-            action=self,
-            extra={"results": [], "errors": []},
-            shared_context=shared_context,
-        )
-
-        async def run_one(action: BaseAction):
-            try:
-                prepared = action.prepare(shared_context, self.options_manager)
-                result = await prepared(*combined_args, **updated_kwargs)
-                shared_context.add_result((action.name, result))
-                context.extra["results"].append((action.name, result))
-            except Exception as error:
-                shared_context.add_error(shared_context.current_index, error)
-                context.extra["errors"].append((action.name, error))
-
-        context.start_timer()
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-            await asyncio.gather(*[run_one(a) for a in self.actions])
-
-            if context.extra["errors"]:
-                context.exception = Exception(
-                    f"{len(context.extra['errors'])} action(s) failed: "
-                    f"{' ,'.join(name for name, _ in context.extra['errors'])}"
-                )
-                await self.hooks.trigger(HookType.ON_ERROR, context)
-                raise context.exception
-
-            context.result = context.extra["results"]
-            await self.hooks.trigger(HookType.ON_SUCCESS, context)
-            return context.result
-
-        except Exception as error:
-            context.exception = error
-            raise
-        finally:
-            context.stop_timer()
-            await self.hooks.trigger(HookType.AFTER, context)
-            await self.hooks.trigger(HookType.ON_TEARDOWN, context)
-            er.record(context)
-
-    def register_hooks_recursively(self, hook_type: HookType, hook: Hook):
-        """Register a hook for all actions and sub-actions."""
-        super().register_hooks_recursively(hook_type, hook)
-        for action in self.actions:
-            action.register_hooks_recursively(hook_type, hook)
-
-    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_into}')[/dim]")
-        tree = parent.add("".join(label)) if parent else Tree("".join(label))
-        actions = self.actions.copy()
-        random.shuffle(actions)
-        await asyncio.gather(*(action.preview(parent=tree) for action in actions))
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self):
-        return (
-            f"ActionGroup(name={self.name}, actions={[a.name for a in self.actions]}, "
-            f"args={self.args!r}, kwargs={self.kwargs!r}, "
-            f"inject_last_result={self.inject_last_result}, "
-            f"inject_into={self.inject_into})"
-        )

falyx/action/action_mixins.py

@@ -1,60 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Provides reusable mixins for managing collections of `BaseAction` instances
-within composite Falyx actions such as `ActionGroup` or `ChainedAction`.
-
-The primary export, `ActionListMixin`, encapsulates common functionality for
-maintaining a mutable list of named actions—such as adding, removing, or retrieving
-actions by name—without duplicating logic across composite action types.
-"""
-
-from typing import Sequence
-
-from falyx.action.base_action import BaseAction
-
-
-class ActionListMixin:
-    """
-    Mixin for managing a list of named `BaseAction` objects.
-
-    Provides helper methods for setting, adding, removing, checking, and
-    retrieving actions in composite Falyx constructs like `ActionGroup`.
-
-    Attributes:
-        actions (list[BaseAction]): The internal list of managed actions.
-
-    Methods:
-        set_actions(actions): Replaces all current actions with the given list.
-        add_action(action): Adds a new action to the list.
-        remove_action(name): Removes an action by its name.
-        has_action(name): Returns True if an action with the given name exists.
-        get_action(name): Returns the action matching the name, or None.
-    """
-
-    def __init__(self) -> None:
-        self.actions: list[BaseAction] = []
-
-    def set_actions(self, actions: Sequence[BaseAction]) -> None:
-        """Replaces the current action list with a new one."""
-        self.actions.clear()
-        for action in actions:
-            self.add_action(action)
-
-    def add_action(self, action: BaseAction) -> None:
-        """Adds an action to the list."""
-        self.actions.append(action)
-
-    def remove_action(self, name: str) -> None:
-        """Removes all actions with the given name."""
-        self.actions = [action for action in self.actions if action.name != name]
-
-    def has_action(self, name: str) -> bool:
-        """Checks if an action with the given name exists."""
-        return any(action.name == name for action in self.actions)
-
-    def get_action(self, name: str) -> BaseAction | None:
-        """Retrieves a single action with the given name."""
-        for action in self.actions:
-            if action.name == name:
-                return action
-        return None

falyx/action/action_types.py

@@ -1,205 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines strongly-typed enums used throughout the Falyx CLI framework for
-representing common structured values like file formats, selection return types,
-and confirmation modes.
-
-These enums support alias resolution, graceful coercion from string inputs,
-and are used for input validation, serialization, and CLI configuration parsing.
-
-Exports:
-- FileType: Defines supported file formats for `LoadFileAction` and `SaveFileAction`
-- SelectionReturnType: Defines structured return modes for `SelectionAction`
-- ConfirmType: Defines selectable confirmation types for prompts and guards
-
-Key Features:
-- Custom `_missing_()` methods for forgiving string coercion and error reporting
-- Aliases and normalization support for user-friendly config-driven workflows
-- Useful in CLI flag parsing, YAML configs, and dynamic schema validation
-
-Example:
-    FileType("yml") → FileType.YAML
-    SelectionReturnType("value") → SelectionReturnType.VALUE
-    ConfirmType("YES_NO") → ConfirmType.YES_NO
-"""
-from __future__ import annotations
-
-from enum import Enum
-
-
-class FileType(Enum):
-    """
-    Represents supported file types for reading and writing in Falyx Actions.
-
-    Used by `LoadFileAction` and `SaveFileAction` to determine how to parse or
-    serialize file content. Includes alias resolution for common extensions like
-    `.yml`, `.txt`, and `filepath`.
-
-    Members:
-        TEXT: Raw encoded text as a string.
-        PATH: Returns the file path (as a Path object).
-        JSON: JSON-formatted object.
-        TOML: TOML-formatted object.
-        YAML: YAML-formatted object.
-        CSV: List of rows (as lists) from a CSV file.
-        TSV: Same as CSV, but tab-delimited.
-        XML: Raw XML as a ElementTree.
-
-    Example:
-        FileType("yml")  → FileType.YAML
-    """
-
-    TEXT = "text"
-    PATH = "path"
-    JSON = "json"
-    TOML = "toml"
-    YAML = "yaml"
-    CSV = "csv"
-    TSV = "tsv"
-    XML = "xml"
-
-    @classmethod
-    def choices(cls) -> list[FileType]:
-        """Return a list of all hook type choices."""
-        return list(cls)
-
-    @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) -> FileType:
-        if not isinstance(value, str):
-            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
-        normalized = value.strip().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 {cls.__name__}: '{value}'. Must be one of: {valid}")
-
-    def __str__(self) -> str:
-        """Return the string representation of the confirm type."""
-        return self.value
-
-
-class SelectionReturnType(Enum):
-    """
-    Controls what is returned from a `SelectionAction` when using a selection map.
-
-    Determines how the user's choice(s) from a `dict[str, SelectionOption]` are
-    transformed and returned by the action.
-
-    Members:
-        KEY: Return the selected key(s) only.
-        VALUE: Return the value(s) associated with the selected key(s).
-        DESCRIPTION: Return the description(s) of the selected item(s).
-        DESCRIPTION_VALUE: Return a dict of {description: value} pairs.
-        ITEMS: Return full `SelectionOption` objects as a dict {key: SelectionOption}.
-
-    Example:
-        return_type=SelectionReturnType.VALUE  → returns raw values like 'prod'
-    """
-
-    KEY = "key"
-    VALUE = "value"
-    DESCRIPTION = "description"
-    DESCRIPTION_VALUE = "description_value"
-    ITEMS = "items"
-
-    @classmethod
-    def choices(cls) -> list[SelectionReturnType]:
-        """Return a list of all hook type choices."""
-        return list(cls)
-
-    @classmethod
-    def _get_alias(cls, value: str) -> str:
-        aliases = {
-            "desc": "description",
-            "desc_value": "description_value",
-        }
-        return aliases.get(value, value)
-
-    @classmethod
-    def _missing_(cls, value: object) -> SelectionReturnType:
-        if not isinstance(value, str):
-            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
-        normalized = value.strip().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 {cls.__name__}: '{value}'. Must be one of: {valid}")
-
-    def __str__(self) -> str:
-        """Return the string representation of the confirm type."""
-        return self.value
-
-
-class ConfirmType(Enum):
-    """
-    Enum for defining prompt styles in confirmation dialogs.
-
-    Used by confirmation actions to control user input behavior and available choices.
-
-    Members:
-        YES_NO: Prompt with Yes / No options.
-        YES_CANCEL: Prompt with Yes / Cancel options.
-        YES_NO_CANCEL: Prompt with Yes / No / Cancel options.
-        TYPE_WORD: Require user to type a specific confirmation word (e.g., "delete").
-        TYPE_WORD_CANCEL: Same as TYPE_WORD, but allows cancellation.
-        OK_CANCEL: Prompt with OK / Cancel options.
-        ACKNOWLEDGE: Single confirmation button (e.g., "Acknowledge").
-
-    Example:
-        ConfirmType("yes_no_cancel") → ConfirmType.YES_NO_CANCEL
-    """
-
-    YES_NO = "yes_no"
-    YES_CANCEL = "yes_cancel"
-    YES_NO_CANCEL = "yes_no_cancel"
-    TYPE_WORD = "type_word"
-    TYPE_WORD_CANCEL = "type_word_cancel"
-    OK_CANCEL = "ok_cancel"
-    ACKNOWLEDGE = "acknowledge"
-
-    @classmethod
-    def choices(cls) -> list[ConfirmType]:
-        """Return a list of all hook type choices."""
-        return list(cls)
-
-    @classmethod
-    def _get_alias(cls, value: str) -> str:
-        aliases = {
-            "yes": "yes_no",
-            "ok": "ok_cancel",
-            "type": "type_word",
-            "word": "type_word",
-            "word_cancel": "type_word_cancel",
-            "ack": "acknowledge",
-        }
-        return aliases.get(value, value)
-
-    @classmethod
-    def _missing_(cls, value: object) -> ConfirmType:
-        if not isinstance(value, str):
-            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
-        normalized = value.strip().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 {cls.__name__}: '{value}'. Must be one of: {valid}")
-
-    def __str__(self) -> str:
-        """Return the string representation of the confirm type."""
-        return self.value

falyx/action/base_action.py

@@ -1,187 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Core action system for Falyx.
-
-This module defines the building blocks for executable actions and workflows,
-providing a structured way to compose, execute, recover, and manage sequences of
-operations.
-
-All actions are callable and follow a unified signature:
-    result = action(*args, **kwargs)
-
-Core guarantees:
-- Full hook lifecycle support (before, on_success, on_error, after, on_teardown).
-- Consistent timing and execution context tracking for each run.
-- Unified, predictable result handling and error propagation.
-- Optional last_result injection to enable flexible, data-driven workflows.
-- Built-in support for retries, rollbacks, parallel groups, chaining, and fallback
-  recovery.
-
-Key components:
-- Action: wraps a function or coroutine into a standard executable unit.
-- ChainedAction: runs actions sequentially, optionally injecting last results.
-- ActionGroup: runs actions in parallel and gathers results.
-- ProcessAction: executes CPU-bound functions in a separate process.
-- LiteralInputAction: injects static values into workflows.
-- FallbackAction: gracefully recovers from failures or missing data.
-
-This design promotes clean, fault-tolerant, modular CLI and automation systems.
-"""
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import Any, Callable
-
-from rich.console import Console
-from rich.tree import Tree
-
-from falyx.console import console
-from falyx.context import SharedContext
-from falyx.debug import register_debug_hooks
-from falyx.hook_manager import Hook, HookManager, HookType
-from falyx.hooks import spinner_before_hook, spinner_teardown_hook
-from falyx.logger import logger
-from falyx.options_manager import OptionsManager
-from falyx.themes import OneColors
-
-
-class BaseAction(ABC):
-    """
-    Base class for actions. Actions can be simple functions or more
-    complex actions like `ChainedAction` or `ActionGroup`. They can also
-    be run independently or as part of Falyx.
-
-    Args:
-        name (str): Name of the action. Used for logging and debugging.
-        hooks (HookManager | None): Hook manager for lifecycle events.
-        inject_last_result (bool): Whether to inject the previous action's result
-                                   into kwargs.
-        inject_into (str): The name of the kwarg key to inject the result as
-                           (default: 'last_result').
-        never_prompt (bool | None): Whether to never prompt for input.
-        logging_hooks (bool): Whether to register debug hooks for logging.
-        ignore_in_history (bool): Whether to ignore this action in execution history last result.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        *,
-        hooks: HookManager | None = None,
-        inject_last_result: bool = False,
-        inject_into: str = "last_result",
-        never_prompt: bool | None = None,
-        logging_hooks: bool = False,
-        ignore_in_history: bool = False,
-        spinner: bool = False,
-        spinner_message: str = "Processing...",
-        spinner_type: str = "dots",
-        spinner_style: str = OneColors.CYAN,
-        spinner_speed: float = 1.0,
-    ) -> None:
-        self.name = name
-        self.hooks = hooks or HookManager()
-        self.is_retryable: bool = False
-        self.shared_context: SharedContext | None = None
-        self.inject_last_result: bool = inject_last_result
-        self.inject_into: str = inject_into
-        self._never_prompt: bool | None = never_prompt
-        self._skip_in_chain: bool = False
-        self.console: Console = console
-        self.options_manager: OptionsManager | None = None
-        self.ignore_in_history: bool = ignore_in_history
-        self.spinner_message = spinner_message
-        self.spinner_type = spinner_type
-        self.spinner_style = spinner_style
-        self.spinner_speed = spinner_speed
-
-        if spinner:
-            self.hooks.register(HookType.BEFORE, spinner_before_hook)
-            self.hooks.register(HookType.ON_TEARDOWN, spinner_teardown_hook)
-
-        if logging_hooks:
-            register_debug_hooks(self.hooks)
-
-    async def __call__(self, *args, **kwargs) -> Any:
-        return await self._run(*args, **kwargs)
-
-    @abstractmethod
-    async def _run(self, *args, **kwargs) -> Any:
-        raise NotImplementedError("_run must be implemented by subclasses")
-
-    @abstractmethod
-    async def preview(self, parent: Tree | None = None):
-        raise NotImplementedError("preview must be implemented by subclasses")
-
-    @abstractmethod
-    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
-        """
-        Returns the callable to be used for argument inference.
-        By default, it returns None.
-        """
-        raise NotImplementedError("get_infer_target must be implemented by subclasses")
-
-    def set_options_manager(self, options_manager: OptionsManager) -> None:
-        self.options_manager = options_manager
-
-    def set_shared_context(self, shared_context: SharedContext) -> None:
-        self.shared_context = shared_context
-
-    def get_option(self, option_name: str, default: Any = None) -> Any:
-        """
-        Resolve an option from the OptionsManager if present, otherwise use the fallback.
-        """
-        if self.options_manager:
-            return self.options_manager.get(option_name, default)
-        return default
-
-    @property
-    def last_result(self) -> Any:
-        """Return the last result from the shared context."""
-        if self.shared_context:
-            return self.shared_context.last_result()
-        return None
-
-    @property
-    def never_prompt(self) -> bool:
-        if self._never_prompt is not None:
-            return self._never_prompt
-        return self.get_option("never_prompt", False)
-
-    @property
-    def spinner_manager(self):
-        """Shortcut to access SpinnerManager via the OptionsManager."""
-        if not self.options_manager:
-            raise RuntimeError("SpinnerManager is not available (no OptionsManager set).")
-        return self.options_manager.spinners
-
-    def prepare(
-        self, shared_context: SharedContext, options_manager: OptionsManager | None = None
-    ) -> BaseAction:
-        """
-        Prepare the action specifically for sequential (ChainedAction) execution.
-        Can be overridden for chain-specific logic.
-        """
-        self.set_shared_context(shared_context)
-        if options_manager:
-            self.set_options_manager(options_manager)
-        return self
-
-    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_into
-            if key in kwargs:
-                logger.warning("[%s] Overriding '%s' with last_result", self.name, key)
-            kwargs = dict(kwargs)
-            kwargs[key] = self.shared_context.last_result()
-        return kwargs
-
-    def register_hooks_recursively(self, hook_type: HookType, hook: Hook):
-        """Register a hook for all actions and sub-actions."""
-        self.hooks.register(hook_type, hook)
-
-    async def _write_stdout(self, data: str) -> None:
-        """Override in subclasses that produce terminal output."""
-
-    def __repr__(self) -> str:
-        return str(self)

falyx/action/chained_action.py

@@ -1,322 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `ChainedAction`, a core Falyx construct for executing a sequence of actions
-in strict order, optionally injecting results from previous steps into subsequent ones.
-
-`ChainedAction` is designed for linear workflows where each step may depend on
-the output of the previous one. It supports rollback semantics, fallback recovery,
-and advanced error handling using `SharedContext`. Literal values are supported via
-automatic wrapping with `LiteralInputAction`.
-
-Key Features:
-- Executes a list of actions sequentially
-- Optional `auto_inject` to forward `last_result` into each step
-- Supports fallback recovery using `FallbackAction` when an error occurs
-- Rollback stack to undo already-completed actions on failure
-- Integrates with the full Falyx hook lifecycle
-- Previews and introspects workflow structure via `Rich`
-
-Use Cases:
-- Ordered pipelines (e.g., build → test → deploy)
-- Data transformations or ETL workflows
-- Linear decision trees or interactive wizards
-
-Special Behaviors:
-- Literal inputs (e.g., strings, numbers) are converted to `LiteralInputAction`
-- If an action raises and is followed by a `FallbackAction`, it will be skipped and recovered
-- If a `BreakChainSignal` is raised, the chain stops early and rollbacks are triggered
-
-Raises:
-- `EmptyChainError`: If no actions are present
-- `BreakChainSignal`: When explicitly triggered by a child action
-- `Exception`: For all unhandled failures during chained execution
-
-Example:
-    ChainedAction(
-        name="DeployFlow",
-        actions=[
-            ActionGroup(
-                name="PreDeploymentChecks",
-                actions=[
-                    Action(
-                        name="ValidateInputs",
-                        action=validate_inputs,
-                    ),
-                    Action(
-                        name="CheckDependencies",
-                        action=check_dependencies,
-                    ),
-                ],
-            ),
-            Action(
-                name="BuildArtifact",
-                action=build_artifact,
-            ),
-            Action(
-                name="Upload",
-                action=upload,
-            ),
-            Action(
-                name="NotifySuccess",
-                action=notify_success,
-            ),
-        ],
-        auto_inject=True,
-    )
-"""
-from __future__ import annotations
-
-from typing import Any, Awaitable, Callable, Sequence
-
-from rich.tree import Tree
-
-from falyx.action.action import Action
-from falyx.action.action_mixins import ActionListMixin
-from falyx.action.base_action import BaseAction
-from falyx.action.fallback_action import FallbackAction
-from falyx.action.literal_input_action import LiteralInputAction
-from falyx.context import ExecutionContext, SharedContext
-from falyx.exceptions import EmptyChainError
-from falyx.execution_registry import ExecutionRegistry as er
-from falyx.hook_manager import Hook, HookManager, HookType
-from falyx.logger import logger
-from falyx.options_manager import OptionsManager
-from falyx.signals import BreakChainSignal
-from falyx.themes import OneColors
-
-
-class ChainedAction(BaseAction, ActionListMixin):
-    """
-    ChainedAction executes a sequence of actions one after another.
-
-    Features:
-    - Supports optional automatic last_result injection (auto_inject).
-    - Recovers from intermediate errors using FallbackAction if present.
-    - Rolls back all previously executed actions if a failure occurs.
-    - Handles literal values with LiteralInputAction.
-
-    Best used for defining robust, ordered workflows where each step can depend on
-    previous results.
-
-    Args:
-        name (str): Name of the chain. Used for logging and debugging.
-        actions (list): List of actions or literals to execute.
-        args (tuple, optional): Positional arguments.
-        kwargs (dict, optional): Keyword arguments.
-        hooks (HookManager, optional): Hooks for lifecycle events.
-        inject_last_result (bool, optional): Whether to inject last results into kwargs
-                                             by default.
-        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.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        actions: (
-            Sequence[BaseAction | Callable[..., Any] | Callable[..., Awaitable[Any]]]
-            | None
-        ) = None,
-        *,
-        args: tuple[Any, ...] = (),
-        kwargs: dict[str, Any] | None = None,
-        hooks: HookManager | None = None,
-        inject_last_result: bool = False,
-        inject_into: str = "last_result",
-        auto_inject: bool = False,
-        return_list: bool = False,
-        never_prompt: bool | None = None,
-        logging_hooks: bool = False,
-        spinner: bool = False,
-        spinner_message: str = "Processing...",
-        spinner_type: str = "dots",
-        spinner_style: str = OneColors.CYAN,
-        spinner_speed: float = 1.0,
-    ) -> None:
-        super().__init__(
-            name,
-            hooks=hooks,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-            never_prompt=never_prompt,
-            logging_hooks=logging_hooks,
-            spinner=spinner,
-            spinner_message=spinner_message,
-            spinner_type=spinner_type,
-            spinner_style=spinner_style,
-            spinner_speed=spinner_speed,
-        )
-        ActionListMixin.__init__(self)
-        self.args = args
-        self.kwargs = kwargs or {}
-        self.auto_inject = auto_inject
-        self.return_list = return_list
-        if actions:
-            self.set_actions(actions)
-
-    def _wrap_if_needed(self, action: BaseAction | Callable[..., Any]) -> BaseAction:
-        if isinstance(action, BaseAction):
-            return action
-        elif callable(action):
-            return Action(name=action.__name__, action=action)
-        else:
-            return LiteralInputAction(action)
-
-    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
-        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 set_options_manager(self, options_manager: OptionsManager) -> None:
-        super().set_options_manager(options_manager)
-        for action in self.actions:
-            action.set_options_manager(options_manager)
-
-    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
-        if self.actions:
-            return self.actions[0].get_infer_target()
-        return None, None
-
-    def _clear_args(self):
-        return (), {}
-
-    async def _run(self, *args, **kwargs) -> Any:
-        if not self.actions:
-            raise EmptyChainError(f"[{self.name}] No actions to execute.")
-
-        combined_args = args + self.args
-        combined_kwargs = {**self.kwargs, **kwargs}
-
-        shared_context = SharedContext(name=self.name, action=self)
-        if self.shared_context:
-            shared_context.add_result(self.shared_context.last_result())
-        updated_kwargs = self._maybe_inject_last_result(combined_kwargs)
-        context = ExecutionContext(
-            name=self.name,
-            args=combined_args,
-            kwargs=updated_kwargs,
-            action=self,
-            extra={"results": [], "rollback_stack": []},
-            shared_context=shared_context,
-        )
-        context.start_timer()
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-
-            for index, action in enumerate(self.actions):
-                if action._skip_in_chain:
-                    logger.debug(
-                        "[%s] Skipping consumed action '%s'", self.name, action.name
-                    )
-                    continue
-                shared_context.current_index = index
-                prepared = action.prepare(shared_context, self.options_manager)
-                try:
-                    result = await prepared(*combined_args, **updated_kwargs)
-                except Exception as error:
-                    if index + 1 < len(self.actions) and isinstance(
-                        self.actions[index + 1], FallbackAction
-                    ):
-                        logger.warning(
-                            "[%s] Fallback triggered: %s, recovering with fallback "
-                            "'%s'.",
-                            self.name,
-                            error,
-                            self.actions[index + 1].name,
-                        )
-                        shared_context.add_result(None)
-                        context.extra["results"].append(None)
-                        fallback = self.actions[index + 1].prepare(shared_context)
-                        result = await fallback()
-                        fallback._skip_in_chain = True
-                    else:
-                        raise
-                shared_context.add_result(result)
-                context.extra["results"].append(result)
-                context.extra["rollback_stack"].append(
-                    (prepared, combined_args, updated_kwargs)
-                )
-                combined_args, updated_kwargs = self._clear_args()
-
-            all_results = context.extra["results"]
-            assert (
-                all_results
-            ), f"[{self.name}] No results captured. Something seriously went wrong."
-            context.result = all_results if self.return_list else all_results[-1]
-            await self.hooks.trigger(HookType.ON_SUCCESS, context)
-            return context.result
-        except BreakChainSignal as error:
-            logger.info("[%s] Chain broken: %s", self.name, error)
-            context.exception = error
-            shared_context.add_error(shared_context.current_index, error)
-            await self._rollback(context.extra["rollback_stack"])
-        except Exception as error:
-            context.exception = error
-            shared_context.add_error(shared_context.current_index, error)
-            await self._rollback(context.extra["rollback_stack"])
-            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 _rollback(
-        self, rollback_stack: list[tuple[Action, tuple[Any, ...], dict[str, Any]]]
-    ):
-        """
-        Roll back all executed actions in reverse order.
-
-        Rollbacks run even if a fallback recovered from failure,
-        ensuring consistent undo of all side effects.
-
-        Actions without rollback handlers are skipped.
-
-        Args:
-            rollback_stack (list): Actions to roll back.
-            *args, **kwargs: Passed to rollback handlers.
-        """
-        for action, args, kwargs in reversed(rollback_stack):
-            rollback = getattr(action, "rollback", None)
-            if rollback:
-                try:
-                    logger.warning("[%s] Rolling back...", action.name)
-                    await rollback(*args, **kwargs)
-                except Exception as error:
-                    logger.error("[%s] Rollback failed: %s", action.name, error)
-
-    def register_hooks_recursively(self, hook_type: HookType, hook: Hook):
-        """Register a hook for all actions and sub-actions."""
-        super().register_hooks_recursively(hook_type, hook)
-        for action in self.actions:
-            action.register_hooks_recursively(hook_type, hook)
-
-    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_into}')[/dim]")
-        tree = parent.add("".join(label)) if parent else Tree("".join(label))
-        for action in self.actions:
-            await action.preview(parent=tree)
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self):
-        return (
-            f"ChainedAction(name={self.name}, "
-            f"actions={[a.name for a in self.actions]}, "
-            f"args={self.args!r}, kwargs={self.kwargs!r}, "
-            f"auto_inject={self.auto_inject}, return_list={self.return_list})"
-        )

falyx/action/confirm_action.py

@@ -1,272 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `ConfirmAction`, a Falyx Action that prompts the user for confirmation
-before continuing execution.
-
-`ConfirmAction` supports a wide range of confirmation strategies, including:
-- Yes/No-style prompts
-- OK/Cancel dialogs
-- Typed confirmation (e.g., "CONFIRM" or "DELETE")
-- Acknowledge-only flows
-
-It is useful for adding safety gates, user-driven approval steps, or destructive
-operation guards in CLI workflows. This Action supports both interactive use and
-non-interactive (headless) behavior via `never_prompt`, as well as full hook lifecycle
-integration and optional result passthrough.
-
-Key Features:
-- Supports all common confirmation types (see `ConfirmType`)
-- Integrates with `PromptSession` for prompt_toolkit-based UX
-- Configurable fallback word validation and behavior on cancel
-- Can return the injected `last_result` instead of a boolean
-- Fully compatible with Falyx hooks, preview, and result injection
-
-Use Cases:
-- Safety checks before deleting, pushing, or overwriting resources
-- Gatekeeping interactive workflows
-- Validating irreversible or sensitive operations
-
-Example:
-    ConfirmAction(
-        name="ConfirmDeploy",
-        message="Are you sure you want to deploy to production?",
-        confirm_type="yes_no_cancel",
-    )
-
-Raises:
-- `CancelSignal`: When the user chooses to abort the action
-- `ValueError`: If an invalid `confirm_type` is provided
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-from prompt_toolkit import PromptSession
-from rich.tree import Tree
-
-from falyx.action.action_types import ConfirmType
-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
-from falyx.logger import logger
-from falyx.prompt_utils import (
-    confirm_async,
-    rich_text_to_prompt_text,
-    should_prompt_user,
-)
-from falyx.signals import CancelSignal
-from falyx.themes import OneColors
-from falyx.validators import word_validator, words_validator
-
-
-class ConfirmAction(BaseAction):
-    """
-    Action to confirm an operation with the user.
-
-    There are several ways to confirm an action, such as using a simple
-    yes/no prompt. You can also use a confirmation type that requires the user
-    to type a specific word or phrase to confirm the action, or use an OK/Cancel
-    dialog.
-
-    This action can be used to ensure that the user explicitly agrees to proceed
-    with an operation.
-
-    Attributes:
-        name (str): Name of the action. Used for logging and debugging.
-        prompt_message (str): The confirmation message to display.
-        confirm_type (ConfirmType | str): The type of confirmation to use.
-            Options include YES_NO, YES_CANCEL, YES_NO_CANCEL, TYPE_WORD, and OK_CANCEL.
-        prompt_session (PromptSession | None): The session to use for input.
-        confirm (bool): Whether to prompt the user for confirmation.
-        word (str): The word to type for TYPE_WORD confirmation.
-        return_last_result (bool): Whether to return the last result of the action
-                                   instead of a boolean.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        prompt_message: str = "Confirm?",
-        confirm_type: ConfirmType | str = ConfirmType.YES_NO,
-        prompt_session: PromptSession | None = None,
-        never_prompt: bool = False,
-        word: str = "CONFIRM",
-        return_last_result: bool = False,
-        inject_last_result: bool = True,
-        inject_into: str = "last_result",
-    ):
-        """
-        Initialize the ConfirmAction.
-
-        Args:
-            message (str): The confirmation message to display.
-            confirm_type (ConfirmType): The type of confirmation to use.
-                Options include YES_NO, YES_CANCEL, YES_NO_CANCEL, TYPE_WORD, and OK_CANCEL.
-            prompt_session (PromptSession | None): The session to use for input.
-            confirm (bool): Whether to prompt the user for confirmation.
-            word (str): The word to type for TYPE_WORD confirmation.
-            return_last_result (bool): Whether to return the last result of the action.
-        """
-        super().__init__(
-            name=name,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-            never_prompt=never_prompt,
-        )
-        self.prompt_message = prompt_message
-        self.confirm_type = ConfirmType(confirm_type)
-        self.prompt_session = prompt_session or PromptSession(
-            interrupt_exception=CancelSignal
-        )
-        self.word = word
-        self.return_last_result = return_last_result
-
-    async def _confirm(self) -> bool:
-        """Confirm the action with the user."""
-        match self.confirm_type:
-            case ConfirmType.YES_NO:
-                return await confirm_async(
-                    rich_text_to_prompt_text(self.prompt_message),
-                    suffix=rich_text_to_prompt_text(
-                        f" [[{OneColors.GREEN_b}]Y[/]]es, "
-                        f"[[{OneColors.DARK_RED_b}]N[/]]o > "
-                    ),
-                    session=self.prompt_session,
-                )
-            case ConfirmType.YES_NO_CANCEL:
-                error_message = "Enter 'Y', 'y' to confirm, 'N', 'n' to decline, or 'C', 'c' to abort."
-                answer = await self.prompt_session.prompt_async(
-                    rich_text_to_prompt_text(
-                        f"❓ {self.prompt_message} [[{OneColors.GREEN_b}]Y[/]]es, "
-                        f"[[{OneColors.DARK_YELLOW_b}]N[/]]o, "
-                        f"or [[{OneColors.DARK_RED_b}]C[/]]ancel to abort > "
-                    ),
-                    validator=words_validator(
-                        ["Y", "N", "C"], error_message=error_message
-                    ),
-                )
-                if answer.upper() == "C":
-                    raise CancelSignal(f"Action '{self.name}' was cancelled by the user.")
-                return answer.upper() == "Y"
-            case ConfirmType.TYPE_WORD:
-                answer = await self.prompt_session.prompt_async(
-                    rich_text_to_prompt_text(
-                        f"❓ {self.prompt_message} [[{OneColors.GREEN_b}]{self.word.upper()}[/]] "
-                        f"to confirm or [[{OneColors.DARK_RED}]N[/{OneColors.DARK_RED}]] > "
-                    ),
-                    validator=word_validator(self.word),
-                )
-                return answer.upper().strip() != "N"
-            case ConfirmType.TYPE_WORD_CANCEL:
-                answer = await self.prompt_session.prompt_async(
-                    rich_text_to_prompt_text(
-                        f"❓ {self.prompt_message} [[{OneColors.GREEN_b}]{self.word.upper()}[/]] "
-                        f"to confirm or [[{OneColors.DARK_RED}]N[/{OneColors.DARK_RED}]] > "
-                    ),
-                    validator=word_validator(self.word),
-                )
-                if answer.upper().strip() == "N":
-                    raise CancelSignal(f"Action '{self.name}' was cancelled by the user.")
-                return answer.upper().strip() == self.word.upper().strip()
-            case ConfirmType.YES_CANCEL:
-                answer = await confirm_async(
-                    rich_text_to_prompt_text(self.prompt_message),
-                    suffix=rich_text_to_prompt_text(
-                        f" [[{OneColors.GREEN_b}]Y[/]]es, "
-                        f"[[{OneColors.DARK_RED_b}]N[/]]o > "
-                    ),
-                    session=self.prompt_session,
-                )
-                if not answer:
-                    raise CancelSignal(f"Action '{self.name}' was cancelled by the user.")
-                return answer
-            case ConfirmType.OK_CANCEL:
-                error_message = "Enter 'O', 'o' to confirm or 'C', 'c' to abort."
-                answer = await self.prompt_session.prompt_async(
-                    rich_text_to_prompt_text(
-                        f"❓ {self.prompt_message} [[{OneColors.GREEN_b}]O[/]]k to confirm, "
-                        f"[[{OneColors.DARK_RED}]C[/]]ancel to abort > "
-                    ),
-                    validator=words_validator(["O", "C"], error_message=error_message),
-                )
-                if answer.upper() == "C":
-                    raise CancelSignal(f"Action '{self.name}' was cancelled by the user.")
-                return answer.upper() == "O"
-            case ConfirmType.ACKNOWLEDGE:
-                answer = await self.prompt_session.prompt_async(
-                    rich_text_to_prompt_text(
-                        f"❓ {self.prompt_message} [[{OneColors.CYAN_b}]A[/]]cknowledge > "
-                    ),
-                    validator=word_validator("A"),
-                )
-                return answer.upper().strip() == "A"
-            case _:
-                raise ValueError(f"Unknown confirm_type: {self.confirm_type}")
-
-    def get_infer_target(self) -> tuple[None, None]:
-        return None, None
-
-    async def _run(self, *args, **kwargs) -> Any:
-        combined_kwargs = self._maybe_inject_last_result(kwargs)
-        context = ExecutionContext(
-            name=self.name, args=args, kwargs=combined_kwargs, action=self
-        )
-        context.start_timer()
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-            if (
-                self.never_prompt
-                or self.options_manager
-                and not should_prompt_user(confirm=True, options=self.options_manager)
-            ):
-                logger.debug(
-                    "Skipping confirmation for '%s' due to never_prompt or options_manager settings.",
-                    self.name,
-                )
-                if self.return_last_result:
-                    result = combined_kwargs[self.inject_into]
-                else:
-                    result = True
-            else:
-                answer = await self._confirm()
-                if self.return_last_result and answer:
-                    result = combined_kwargs[self.inject_into]
-                else:
-                    result = answer
-            logger.debug("Action '%s' confirmed with result: %s", self.name, 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) -> None:
-        tree = (
-            Tree(
-                f"[{OneColors.CYAN_b}]ConfirmAction[/]: {self.name}",
-                guide_style=OneColors.BLUE_b,
-            )
-            if not parent
-            else parent.add(f"[{OneColors.CYAN_b}]ConfirmAction[/]: {self.name}")
-        )
-        tree.add(f"[bold]Message:[/] {self.prompt_message}")
-        tree.add(f"[bold]Type:[/] {self.confirm_type.value}")
-        tree.add(f"[bold]Prompt Required:[/] {'No' if self.never_prompt else 'Yes'}")
-        if self.confirm_type in (ConfirmType.TYPE_WORD, ConfirmType.TYPE_WORD_CANCEL):
-            tree.add(f"[bold]Confirmation Word:[/] {self.word}")
-        if parent is None:
-            self.console.print(tree)
-
-    def __str__(self) -> str:
-        return (
-            f"ConfirmAction(name={self.name}, message={self.prompt_message}, "
-            f"confirm_type={self.confirm_type}, return_last_result={self.return_last_result})"
-        )

falyx/action/fallback_action.py

@@ -1,87 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `FallbackAction`, a lightweight recovery Action used within `ChainedAction`
-pipelines to gracefully handle errors or missing results from a preceding step.
-
-When placed immediately after a failing or null-returning Action, `FallbackAction`
-injects the `last_result` and checks whether it is `None`. If so, it substitutes a
-predefined fallback value and allows the chain to continue. If `last_result` is valid,
-it is passed through unchanged.
-
-This mechanism allows workflows to recover from failure or gaps in data
-without prematurely terminating the entire chain.
-
-Key Features:
-- Injects and inspects `last_result`
-- Replaces `None` with a fallback value
-- Consumes upstream errors when used with `ChainedAction`
-- Fully compatible with Falyx's preview and hook systems
-
-Typical Use Cases:
-- Graceful degradation in chained workflows
-- Providing default values when earlier steps are optional
-- Replacing missing data with static or precomputed values
-
-Example:
-    ChainedAction(
-        name="FetchWithFallback",
-        actions=[
-            Action("MaybeFetchRemoteAction", action=fetch_data),
-            FallbackAction(fallback={"data": "default"}),
-            Action("ProcessDataAction", action=process_data),
-        ],
-        auto_inject=True,
-    )
-
-The `FallbackAction` ensures that even if `MaybeFetchRemoteAction` fails or returns
-None, `ProcessDataAction` still receives a usable input.
-"""
-from functools import cached_property
-from typing import Any
-
-from rich.tree import Tree
-
-from falyx.action.action import Action
-from falyx.themes import OneColors
-
-
-class FallbackAction(Action):
-    """
-    FallbackAction provides a default value if the previous action failed or
-    returned None.
-
-    It injects the last result and checks:
-    - If last_result is not None, it passes it through unchanged.
-    - If last_result is None (e.g., due to failure), it replaces it with a fallback value.
-
-    Used in ChainedAction pipelines to gracefully recover from errors or missing data.
-    When activated, it consumes the preceding error and allows the chain to continue
-    normally.
-
-    Args:
-        fallback (Any): The fallback value to use if last_result is None.
-    """
-
-    def __init__(self, fallback: Any):
-        self._fallback = fallback
-
-        async def _fallback_logic(last_result):
-            return last_result if last_result is not None else fallback
-
-        super().__init__(name="Fallback", action=_fallback_logic, inject_last_result=True)
-
-    @cached_property
-    def fallback(self) -> Any:
-        """Return the fallback value."""
-        return self._fallback
-
-    async def preview(self, parent: Tree | None = None):
-        label = [f"[{OneColors.LIGHT_RED}]🛟 Fallback[/] '{self.name}'"]
-        label.append(f" [dim](uses fallback = {repr(self.fallback)})[/dim]")
-        if parent:
-            parent.add("".join(label))
-        else:
-            self.console.print(Tree("".join(label)))
-
-    def __str__(self) -> str:
-        return f"FallbackAction(fallback={self.fallback!r})"

falyx/action/http_action.py

@@ -1,169 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines an Action subclass for making HTTP requests using aiohttp within Falyx workflows.
-
-Features:
-- Automatic reuse of aiohttp.ClientSession via SharedContext
-- JSON, query param, header, and body support
-- Retry integration and last_result injection
-- Clean resource teardown using hooks
-"""
-from typing import Any
-
-import aiohttp
-from rich.tree import Tree
-
-from falyx.action.action import Action
-from falyx.context import ExecutionContext, SharedContext
-from falyx.hook_manager import HookManager, HookType
-from falyx.logger import logger
-from falyx.themes import OneColors
-
-
-async def close_shared_http_session(context: ExecutionContext) -> None:
-    try:
-        shared_context: SharedContext = context.get_shared_context()
-        session = shared_context.get("http_session")
-        should_close = shared_context.get("_session_should_close", False)
-        if session and should_close:
-            await session.close()
-    except Exception as error:
-        logger.warning("Error closing shared HTTP session: %s", error)
-
-
-class HTTPAction(Action):
-    """
-    An Action for executing HTTP requests using aiohttp with shared session reuse.
-
-    This action integrates seamlessly into Falyx pipelines, with automatic session
-    management, result injection, and lifecycle hook support. It is ideal for CLI-driven
-    API workflows where you need to call remote services and process their responses.
-
-    Features:
-    - Uses aiohttp for asynchronous HTTP requests
-    - Reuses a shared session via SharedContext to reduce connection overhead
-    - Automatically closes the session at the end of an ActionGroup (if applicable)
-    - Supports GET, POST, PUT, DELETE, etc. with full header, query, body support
-    - Retry and result injection compatible
-
-    Args:
-        name (str): Name of the action. Used for logging and debugging.
-        method (str): HTTP method (e.g., 'GET', 'POST').
-        url (str): The request URL.
-        headers (dict[str, str], optional): Request headers.
-        params (dict[str, Any], optional): URL query parameters.
-        json (dict[str, Any], optional): JSON body to send.
-        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_into (str): Name of injected key.
-        retry (bool): Enable retry logic.
-        retry_policy (RetryPolicy): Retry settings.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        method: str,
-        url: str,
-        *,
-        args: tuple[Any, ...] = (),
-        headers: dict[str, str] | None = None,
-        params: dict[str, Any] | None = None,
-        json: dict[str, Any] | None = None,
-        data: Any = None,
-        hooks=None,
-        inject_last_result: bool = False,
-        inject_into: str = "last_result",
-        retry: bool = False,
-        retry_policy=None,
-        spinner: bool = False,
-        spinner_message: str = "Processing...",
-        spinner_type: str = "dots",
-        spinner_style: str = OneColors.CYAN,
-        spinner_speed: float = 1.0,
-    ):
-        self.method = method.upper()
-        self.url = url
-        self.headers = headers
-        self.params = params
-        self.json = json
-        self.data = data
-
-        super().__init__(
-            name=name,
-            action=self._request,
-            args=args,
-            kwargs={},
-            hooks=hooks,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-            retry=retry,
-            retry_policy=retry_policy,
-            spinner=spinner,
-            spinner_message=spinner_message,
-            spinner_type=spinner_type,
-            spinner_style=spinner_style,
-            spinner_speed=spinner_speed,
-        )
-
-    async def _request(self, *_, **__) -> dict[str, Any]:
-        if self.shared_context:
-            context: SharedContext = self.shared_context
-            session = context.get("http_session")
-            if session is None:
-                session = aiohttp.ClientSession()
-                context.set("http_session", session)
-                context.set("_session_should_close", True)
-        else:
-            session = aiohttp.ClientSession()
-
-        try:
-            async with session.request(
-                self.method,
-                self.url,
-                headers=self.headers,
-                params=self.params,
-                json=self.json,
-                data=self.data,
-            ) as response:
-                body = await response.text()
-                return {
-                    "status": response.status,
-                    "url": str(response.url),
-                    "headers": dict(response.headers),
-                    "body": body,
-                }
-        finally:
-            if not self.shared_context:
-                await session.close()
-
-    def register_teardown(self, hooks: HookManager):
-        hooks.register(HookType.ON_TEARDOWN, close_shared_http_session)
-
-    async def preview(self, parent: Tree | None = None):
-        label = [
-            f"[{OneColors.CYAN_b}]🌐 HTTPAction[/] '{self.name}'",
-            f"\n[dim]Method:[/] {self.method}",
-            f"\n[dim]URL:[/] {self.url}",
-        ]
-        if self.inject_last_result:
-            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, "
-                f"delay {self.retry_policy.delay}s, backoff {self.retry_policy.backoff}x"
-            )
-
-        if parent:
-            parent.add("".join(label))
-        else:
-            self.console.print(Tree("".join(label)))
-
-    def __str__(self):
-        return (
-            f"HTTPAction(name={self.name!r}, method={self.method!r}, url={self.url!r}, "
-            f"headers={self.headers!r}, params={self.params!r}, json={self.json!r}, "
-            f"data={self.data!r}, retry={self.retry_policy.enabled}, "
-            f"inject_last_result={self.inject_last_result})"
-        )

falyx/action/io_action.py

@@ -1,172 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-BaseIOAction: A base class for stream- or buffer-based IO-driven Actions.
-
-This module defines `BaseIOAction`, a specialized variant of `BaseAction`
-that interacts with standard input and output, enabling command-line pipelines,
-text filters, and stream processing tasks.
-
-Features:
-- Supports buffered or streaming input modes.
-- Reads from stdin and writes to stdout automatically.
-- Integrates with lifecycle hooks and retry logic.
-- Subclasses must implement `from_input()`, `to_output()`, and `_run()`.
-
-Common usage includes shell-like filters, input transformers, or any tool that
-needs to consume input from another process or pipeline.
-"""
-import asyncio
-import sys
-from typing import Any, Callable
-
-from rich.tree import Tree
-
-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
-from falyx.themes import OneColors
-
-
-class BaseIOAction(BaseAction):
-    """
-    Base class for IO-driven Actions that operate on stdin/stdout input streams.
-
-    Designed for use in shell pipelines or programmatic workflows that pass data
-    through chained commands. It handles reading input, transforming it, and
-    emitting output — either as a one-time buffered operation or line-by-line streaming.
-
-    Core responsibilities:
-    - Reads input from stdin or previous action result.
-    - Supports buffered or streaming modes via `mode`.
-    - Parses input via `from_input()` and formats output via `to_output()`.
-    - Executes `_run()` with the parsed input.
-    - Writes output to stdout.
-
-    Subclasses must implement:
-    - `from_input(raw)`: Convert raw stdin or injected data into typed input.
-    - `to_output(data)`: Convert result into output string or bytes.
-    - `_run(parsed_input, *args, **kwargs)`: Core execution logic.
-
-    Args:
-        name (str): Name of the action. Used for logging and debugging.
-        hooks (HookManager | None): Hook manager for lifecycle events.
-        mode (str): Either "buffered" or "stream". Controls input behavior.
-        logging_hooks (bool): Whether to register debug hooks for logging.
-        inject_last_result (bool): Whether to inject shared context input.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        *,
-        hooks: HookManager | None = None,
-        mode: str = "buffered",
-        logging_hooks: bool = True,
-        inject_last_result: bool = True,
-    ):
-        super().__init__(
-            name=name,
-            hooks=hooks,
-            logging_hooks=logging_hooks,
-            inject_last_result=inject_last_result,
-        )
-        self.mode = mode
-
-    def from_input(self, raw: str | bytes) -> Any:
-        raise NotImplementedError
-
-    def to_output(self, result: Any) -> str | bytes:
-        raise NotImplementedError
-
-    async def _resolve_input(
-        self, args: tuple[Any], kwargs: dict[str, Any]
-    ) -> str | bytes:
-        data = await self._read_stdin()
-        if data:
-            return self.from_input(data)
-
-        if len(args) == 1:
-            return self.from_input(args[0])
-
-        if self.inject_last_result and self.shared_context:
-            return self.shared_context.last_result()
-
-        return ""
-
-    def get_infer_target(self) -> tuple[Callable[..., Any] | None, dict[str, Any] | None]:
-        return None, None
-
-    async def __call__(self, *args, **kwargs):
-        context = ExecutionContext(
-            name=self.name,
-            args=args,
-            kwargs=kwargs,
-            action=self,
-        )
-
-        context.start_timer()
-        await self.hooks.trigger(HookType.BEFORE, context)
-
-        try:
-            if self.mode == "stream":
-                line_gen = await self._read_stdin_stream()
-                async for _ in self._stream_lines(line_gen, args, kwargs):
-                    pass
-                result = getattr(self, "_last_result", None)
-            else:
-                parsed_input = await self._resolve_input(args, kwargs)
-                result = await self._run(parsed_input)
-                output = self.to_output(result)
-                await self._write_stdout(output)
-            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 _read_stdin(self) -> str:
-        if not sys.stdin.isatty():
-            return await asyncio.to_thread(sys.stdin.read)
-        return ""
-
-    async def _read_stdin_stream(self) -> Any:
-        """Returns a generator that yields lines from stdin in a background thread."""
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(None, lambda: iter(sys.stdin))
-
-    async def _stream_lines(self, line_gen, args, kwargs):
-        for line in line_gen:
-            parsed = self.from_input(line)
-            result = await self._run(parsed, *args, **kwargs)
-            self._last_result = result
-            output = self.to_output(result)
-            await self._write_stdout(output)
-            yield result
-
-    async def _write_stdout(self, data: str) -> None:
-        await asyncio.to_thread(sys.stdout.write, data)
-        await asyncio.to_thread(sys.stdout.flush)
-
-    async def _run(self, parsed_input: Any, *args, **kwargs) -> Any:
-        """Subclasses should override this with actual logic."""
-        raise NotImplementedError("Must implement _run()")
-
-    def __str__(self):
-        return f"<{self.__class__.__name__} '{self.name}' IOAction>"
-
-    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_into}')[/dim]")
-        if parent:
-            parent.add("".join(label))
-        else:
-            self.console.print(Tree("".join(label)))

falyx/action/literal_input_action.py

@@ -1,80 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `LiteralInputAction`, a lightweight Falyx Action that injects a static,
-predefined value into a `ChainedAction` workflow.
-
-This Action is useful for embedding literal values (e.g., strings, numbers,
-dicts) as part of a CLI pipeline without writing custom callables. It behaves
-like a constant-returning function that can serve as the starting point,
-fallback, or manual override within a sequence of actions.
-
-Key Features:
-- Wraps any static value as a Falyx-compatible Action
-- Fully hookable and previewable like any other Action
-- Enables declarative workflows with no required user input
-- Compatible with auto-injection and shared context in `ChainedAction`
-
-Common Use Cases:
-- Supplying default parameters or configuration values mid-pipeline
-- Starting a chain with a fixed value (e.g., base URL, credentials)
-- Bridging gaps between conditional or dynamically generated Actions
-
-Example:
-    ChainedAction(
-        name="SendStaticMessage",
-        actions=[
-            LiteralInputAction("hello world"),
-            SendMessageAction(),
-        ]
-    )
-
-The `LiteralInputAction` is a foundational building block for pipelines that
-require predictable, declarative value injection at any stage.
-"""
-from __future__ import annotations
-
-from functools import cached_property
-from typing import Any
-
-from rich.tree import Tree
-
-from falyx.action.action import Action
-from falyx.themes import OneColors
-
-
-class LiteralInputAction(Action):
-    """
-    LiteralInputAction injects a static value into a ChainedAction.
-
-    This allows embedding hardcoded values mid-pipeline, useful when:
-    - Providing default or fallback inputs.
-    - Starting a pipeline with a fixed input.
-    - Supplying missing context manually.
-
-    Args:
-        value (Any): The static value to inject.
-    """
-
-    def __init__(self, value: Any):
-        self._value = value
-
-        async def literal(*_, **__):
-            return value
-
-        super().__init__("Input", literal)
-
-    @cached_property
-    def value(self) -> Any:
-        """Return the literal value."""
-        return self._value
-
-    async def preview(self, parent: Tree | None = None):
-        label = [f"[{OneColors.LIGHT_YELLOW}]📥 LiteralInput[/] '{self.name}'"]
-        label.append(f" [dim](value = {repr(self.value)})[/dim]")
-        if parent:
-            parent.add("".join(label))
-        else:
-            self.console.print(Tree("".join(label)))
-
-    def __str__(self) -> str:
-        return f"LiteralInputAction(value={self.value!r})"

falyx/action/load_file_action.py

@@ -1,264 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `LoadFileAction`, a Falyx Action for reading and parsing the contents of a file
-at runtime in a structured, introspectable, and lifecycle-aware manner.
-
-This action supports multiple common file types—including plain text, structured data
-formats (JSON, YAML, TOML), tabular formats (CSV, TSV), XML, and raw Path objects—
-making it ideal for configuration loading, data ingestion, and file-driven workflows.
-
-It integrates seamlessly with Falyx pipelines and supports `last_result` injection,
-Rich-powered previews, and lifecycle hook execution.
-
-Key Features:
-- Format-aware parsing for structured and unstructured files
-- Supports injection of `last_result` as the target file path
-- Headless-compatible via `never_prompt` and argument overrides
-- Lifecycle hooks: before, success, error, after, teardown
-- Preview renders file metadata, size, modified timestamp, and parsed content
-- Fully typed and alias-compatible via `FileType`
-
-Supported File Types:
-- `TEXT`: Raw text string (UTF-8)
-- `PATH`: The file path itself as a `Path` object
-- `JSON`, `YAML`, `TOML`: Parsed into `dict` or `list`
-- `CSV`, `TSV`: Parsed into `list[list[str]]`
-- `XML`: Returns the root `ElementTree.Element`
-
-Example:
-    LoadFileAction(
-        name="LoadSettings",
-        file_path="config/settings.yaml",
-        file_type="yaml"
-    )
-
-This module is a foundational building block for file-driven CLI workflows in Falyx.
-It is often paired with `SaveFileAction`, `SelectionAction`, or `ConfirmAction` for
-robust and interactive pipelines.
-"""
-import csv
-import json
-import xml.etree.ElementTree as ET
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-
-import toml
-import yaml
-from rich.tree import Tree
-
-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
-from falyx.logger import logger
-from falyx.themes import OneColors
-
-
-class LoadFileAction(BaseAction):
-    """
-    LoadFileAction loads and parses the contents of a file at runtime.
-
-    This action supports multiple common file formats—including plain text, JSON,
-    YAML, TOML, XML, CSV, and TSV—and returns a parsed representation of the file.
-    It can be used to inject external data into a CLI workflow, load configuration files,
-    or process structured datasets interactively or in headless mode.
-
-    Key Features:
-    - Supports rich previewing of file metadata and contents
-    - Auto-injects `last_result` as `file_path` if configured
-    - Hookable at every lifecycle stage (before, success, error, after, teardown)
-    - Supports both static and dynamic file targets (via args or injected values)
-
-    Args:
-        name (str): Name of the action for tracking and logging.
-        file_path (str | Path | None): Path to the file to be loaded. Can be passed
-            directly or injected via `last_result`.
-        file_type (FileType | str): Type of file to parse. Options include:
-            TEXT, JSON, YAML, TOML, CSV, TSV, XML, PATH.
-        encoding (str): Encoding to use when reading files (default: 'UTF-8').
-        inject_last_result (bool): Whether to use the last result as the file path.
-        inject_into (str): Name of the kwarg to inject `last_result` into (default: 'file_path').
-
-    Returns:
-        Any: The parsed file content. Format depends on `file_type`:
-            - TEXT: str
-            - JSON/YAML/TOML: dict or list
-            - CSV/TSV: list[list[str]]
-            - XML: xml.etree.ElementTree
-            - PATH: Path object
-
-    Raises:
-        ValueError: If `file_path` is missing or invalid.
-        FileNotFoundError: If the file does not exist.
-        TypeError: If `file_type` is unsupported or the factory does not return a BaseAction.
-        Any parsing errors will be logged but not raised unless fatal.
-
-    Example:
-        LoadFileAction(
-            name="LoadConfig",
-            file_path="config/settings.yaml",
-            file_type="yaml"
-        )
-    """
-
-    def __init__(
-        self,
-        name: str,
-        file_path: str | Path | None = None,
-        file_type: FileType | str = FileType.TEXT,
-        encoding: str = "UTF-8",
-        inject_last_result: bool = False,
-        inject_into: str = "file_path",
-    ):
-        super().__init__(
-            name=name, inject_last_result=inject_last_result, inject_into=inject_into
-        )
-        self._file_path = self._coerce_file_path(file_path)
-        self._file_type = FileType(file_type)
-        self.encoding = encoding
-
-    @property
-    def file_path(self) -> Path | None:
-        """Get the file path as a Path object."""
-        return self._file_path
-
-    @file_path.setter
-    def file_path(self, value: str | Path):
-        """Set the file path, converting to Path if necessary."""
-        self._file_path = self._coerce_file_path(value)
-
-    def _coerce_file_path(self, file_path: str | Path | None) -> Path | None:
-        """Coerce the file path to a Path object."""
-        if isinstance(file_path, Path):
-            return file_path
-        elif isinstance(file_path, str):
-            return Path(file_path)
-        elif file_path is None:
-            return None
-        else:
-            raise TypeError("file_path must be a string or Path object")
-
-    @property
-    def file_type(self) -> FileType:
-        """Get the file type."""
-        return self._file_type
-
-    def get_infer_target(self) -> tuple[None, None]:
-        return None, None
-
-    async def load_file(self) -> Any:
-        """Load and parse the file based on its type."""
-        if self.file_path is None:
-            raise ValueError("file_path must be set before loading a file")
-        elif not self.file_path.exists():
-            raise FileNotFoundError(f"File not found: {self.file_path}")
-        elif not self.file_path.is_file():
-            raise ValueError(f"Path is not a regular file: {self.file_path}")
-        value: Any = None
-        try:
-            if self.file_type == FileType.TEXT:
-                value = self.file_path.read_text(encoding=self.encoding)
-            elif self.file_type == FileType.PATH:
-                value = self.file_path
-            elif self.file_type == FileType.JSON:
-                value = json.loads(self.file_path.read_text(encoding=self.encoding))
-            elif self.file_type == FileType.TOML:
-                value = toml.loads(self.file_path.read_text(encoding=self.encoding))
-            elif self.file_type == FileType.YAML:
-                value = yaml.safe_load(self.file_path.read_text(encoding=self.encoding))
-            elif self.file_type == FileType.CSV:
-                with open(self.file_path, newline="", encoding=self.encoding) as csvfile:
-                    reader = csv.reader(csvfile)
-                    value = list(reader)
-            elif self.file_type == FileType.TSV:
-                with open(self.file_path, newline="", encoding=self.encoding) as tsvfile:
-                    reader = csv.reader(tsvfile, delimiter="\t")
-                    value = list(reader)
-            elif self.file_type == FileType.XML:
-                tree = ET.parse(
-                    self.file_path, parser=ET.XMLParser(encoding=self.encoding)
-                )
-                root = tree.getroot()
-                value = root
-            else:
-                raise ValueError(f"Unsupported return type: {self.file_type}")
-
-        except Exception as error:
-            logger.error("Failed to parse %s: %s", self.file_path.name, error)
-        return value
-
-    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)
-
-            if "file_path" in kwargs:
-                self.file_path = kwargs["file_path"]
-            elif self.inject_last_result and self.last_result:
-                self.file_path = self.last_result
-
-            result = await self.load_file()
-            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}]📄 LoadFileAction[/] '{self.name}'"
-        tree = parent.add(label) if parent else Tree(label)
-
-        tree.add(f"[dim]Path:[/] {self.file_path}")
-        tree.add(f"[dim]Type:[/] {self.file_type.name if self.file_type else 'None'}")
-        if self.file_path is None:
-            tree.add(f"[{OneColors.DARK_RED_b}]❌ File path is not set[/]")
-        elif not self.file_path.exists():
-            tree.add(f"[{OneColors.DARK_RED_b}]❌ File does not exist[/]")
-        elif not self.file_path.is_file():
-            tree.add(f"[{OneColors.LIGHT_YELLOW_b}]⚠️ Not a regular file[/]")
-        else:
-            try:
-                stat = self.file_path.stat()
-                tree.add(f"[dim]Size:[/] {stat.st_size:,} bytes")
-                tree.add(
-                    f"[dim]Modified:[/] {datetime.fromtimestamp(stat.st_mtime):%Y-%m-%d %H:%M:%S}"
-                )
-                tree.add(
-                    f"[dim]Created:[/] {datetime.fromtimestamp(stat.st_ctime):%Y-%m-%d %H:%M:%S}"
-                )
-                if self.file_type == FileType.TEXT:
-                    preview_lines = self.file_path.read_text(
-                        encoding="UTF-8"
-                    ).splitlines()[:10]
-                    content_tree = tree.add("[dim]Preview (first 10 lines):[/]")
-                    for line in preview_lines:
-                        content_tree.add(f"[dim]{line}[/]")
-                elif self.file_type in {FileType.JSON, FileType.YAML, FileType.TOML}:
-                    raw = self.load_file()
-                    if raw is not None:
-                        preview_str = (
-                            json.dumps(raw, indent=2)
-                            if isinstance(raw, dict)
-                            else str(raw)
-                        )
-                        preview_lines = preview_str.splitlines()[:10]
-                        content_tree = tree.add("[dim]Parsed preview:[/]")
-                        for line in preview_lines:
-                            content_tree.add(f"[dim]{line}[/]")
-            except Exception as e:
-                tree.add(f"[{OneColors.DARK_RED_b}]❌ Error reading file:[/] {e}")
-
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self) -> str:
-        return f"LoadFileAction(file_path={self.file_path}, file_type={self.file_type})"

falyx/action/menu_action.py

@@ -1,249 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `MenuAction`, a one-shot, interactive menu-style Falyx Action that presents
-a set of labeled options to the user and executes the corresponding action based on
-their selection.
-
-Unlike the persistent top-level Falyx menu, `MenuAction` is intended for embedded,
-self-contained decision points within a workflow. It supports both interactive and
-non-interactive (headless) usage, integrates fully with the Falyx hook lifecycle,
-and allows optional defaulting or input injection from previous actions.
-
-Each selectable item is defined in a `MenuOptionMap`, mapping a single-character or
-keyword to a `MenuOption`, which includes a description and a corresponding `BaseAction`.
-
-Key Features:
-- Renders a Rich-powered multi-column menu table
-- Accepts custom prompt sessions or tables
-- Supports `last_result` injection for context-aware defaults
-- Gracefully handles `BackSignal` and `QuitSignal` for flow control
-- Compatible with preview trees and introspection tools
-
-Use Cases:
-- In-workflow submenus or branches
-- Interactive control points in chained or grouped workflows
-- Configurable menus for multi-step user-driven automation
-
-Example:
-    MenuAction(
-        name="SelectEnv",
-        menu_options=MenuOptionMap(options={
-            "D": MenuOption("Deploy to Dev", DeployDevAction()),
-            "P": MenuOption("Deploy to Prod", DeployProdAction()),
-        }),
-        default_selection="D",
-    )
-
-This module is ideal for enabling structured, discoverable, and declarative
-menus in both interactive and programmatic CLI automation.
-"""
-from typing import Any
-
-from prompt_toolkit import PromptSession
-from rich.table import Table
-from rich.tree import Tree
-
-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
-from falyx.logger import logger
-from falyx.menu import MenuOptionMap
-from falyx.prompt_utils import rich_text_to_prompt_text
-from falyx.selection import prompt_for_selection, render_table_base
-from falyx.signals import BackSignal, CancelSignal, QuitSignal
-from falyx.themes import OneColors
-from falyx.utils import chunks
-
-
-class MenuAction(BaseAction):
-    """
-    MenuAction displays a one-time interactive menu of predefined options,
-    each mapped to a corresponding Action.
-
-    Unlike the main Falyx menu system, `MenuAction` is intended for scoped,
-    self-contained selection logic—ideal for small in-flow menus, decision branches,
-    or embedded control points in larger workflows.
-
-    Each selectable item is defined in a `MenuOptionMap`, which maps a string key
-    to a `MenuOption`, bundling a description and a callable Action.
-
-    Key Features:
-    - One-shot selection from labeled actions
-    - Optional default or last_result-based selection
-    - Full hook lifecycle (before, success, error, after, teardown)
-    - Works with or without rendering a table (for headless use)
-    - Compatible with `BackSignal` and `QuitSignal` for graceful control flow exits
-
-    Args:
-        name (str): Name of the action. Used for logging and debugging.
-        menu_options (MenuOptionMap): Mapping of keys to `MenuOption` objects.
-        title (str): Table title displayed when prompting the user.
-        columns (int): Number of columns in the rendered table.
-        prompt_message (str): Prompt text displayed before selection.
-        default_selection (str): Key to use if no user input is provided.
-        inject_last_result (bool): Whether to inject `last_result` into args/kwargs.
-        inject_into (str): Key under which to inject `last_result`.
-        prompt_session (PromptSession | None): Custom session for Prompt Toolkit input.
-        never_prompt (bool): If True, skips interaction and uses default or last_result.
-        include_reserved (bool): Whether to include reserved keys (like 'X' for Exit).
-        show_table (bool): Whether to render the Rich menu table.
-        custom_table (Table | None): Pre-rendered Rich Table (bypasses auto-building).
-
-    Returns:
-        Any: The result of the selected option's Action.
-
-    Raises:
-        BackSignal: When the user chooses to return to a previous menu.
-        QuitSignal: When the user chooses to exit the program.
-        ValueError: If `never_prompt=True` but no default selection is resolvable.
-        Exception: Any error raised during the execution of the selected Action.
-
-    Example:
-        MenuAction(
-            name="ChooseBranch",
-            menu_options=MenuOptionMap(options={
-                "A": MenuOption("Run analysis", ActionGroup(...)),
-                "B": MenuOption("Run report", Action(...)),
-            }),
-        )
-    """
-
-    def __init__(
-        self,
-        name: str,
-        menu_options: MenuOptionMap,
-        *,
-        title: str = "Select an option",
-        columns: int = 2,
-        prompt_message: str = "Select > ",
-        default_selection: str = "",
-        inject_last_result: bool = False,
-        inject_into: str = "last_result",
-        prompt_session: PromptSession | None = None,
-        never_prompt: bool = False,
-        include_reserved: bool = True,
-        show_table: bool = True,
-        custom_table: Table | None = None,
-    ):
-        super().__init__(
-            name,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-            never_prompt=never_prompt,
-        )
-        self.menu_options = menu_options
-        self.title = title
-        self.columns = columns
-        self.prompt_message = rich_text_to_prompt_text(prompt_message)
-        self.default_selection = default_selection
-        self.prompt_session = prompt_session or PromptSession(
-            interrupt_exception=CancelSignal
-        )
-        self.include_reserved = include_reserved
-        self.show_table = show_table
-        self.custom_table = custom_table
-
-    def _build_table(self) -> Table:
-        if self.custom_table:
-            return self.custom_table
-        table = render_table_base(
-            title=self.title,
-            columns=self.columns,
-        )
-        for chunk in chunks(
-            self.menu_options.items(include_reserved=self.include_reserved), self.columns
-        ):
-            row = []
-            for key, option in chunk:
-                row.append(option.render(key))
-            table.add_row(*row)
-        return table
-
-    def get_infer_target(self) -> tuple[None, None]:
-        return None, None
-
-    async def _run(self, *args, **kwargs) -> Any:
-        kwargs = self._maybe_inject_last_result(kwargs)
-        context = ExecutionContext(
-            name=self.name,
-            args=args,
-            kwargs=kwargs,
-            action=self,
-        )
-
-        effective_default = self.default_selection
-        maybe_result = str(self.last_result)
-        if maybe_result in self.menu_options:
-            effective_default = maybe_result
-        elif self.inject_last_result:
-            logger.warning(
-                "[%s] Injected last result '%s' not found in menu options",
-                self.name,
-                maybe_result,
-            )
-
-        if self.never_prompt and not effective_default:
-            raise ValueError(
-                f"[{self.name}] 'never_prompt' is True but no valid default_selection"
-                " was provided."
-            )
-
-        context.start_timer()
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-            key = effective_default
-            if not self.never_prompt:
-                table = self._build_table()
-                key_ = await prompt_for_selection(
-                    self.menu_options.keys(),
-                    table,
-                    default_selection=self.default_selection,
-                    prompt_session=self.prompt_session,
-                    prompt_message=self.prompt_message,
-                    show_table=self.show_table,
-                )
-                if isinstance(key_, str):
-                    key = key_
-                else:
-                    assert False, "Unreachable, MenuAction only supports single selection"
-            option = self.menu_options[key]
-            result = await option.action(*args, **kwargs)
-            context.result = result
-            await self.hooks.trigger(HookType.ON_SUCCESS, context)
-            return result
-
-        except BackSignal:
-            logger.debug("[%s][BackSignal] <- Returning to previous menu", self.name)
-            return None
-        except QuitSignal:
-            logger.debug("[%s][QuitSignal] <- Exiting application", self.name)
-            raise
-        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.DARK_YELLOW_b}]📋 MenuAction[/] '{self.name}'"
-        tree = parent.add(label) if parent else Tree(label)
-        for key, option in self.menu_options.items():
-            tree.add(
-                f"[dim]{key}[/]: {option.description} → [italic]{option.action.name}[/]"
-            )
-            await option.action.preview(parent=tree)
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self) -> str:
-        return (
-            f"MenuAction(name={self.name!r}, options={list(self.menu_options.keys())!r}, "
-            f"default_selection={self.default_selection!r}, "
-            f"include_reserved={self.include_reserved}, "
-            f"prompt={'off' if self.never_prompt else 'on'})"
-        )

falyx/action/process_action.py

@@ -1,181 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `ProcessAction`, a Falyx Action that executes a blocking or CPU-bound function
-in a separate process using `concurrent.futures.ProcessPoolExecutor`.
-
-This is useful for offloading expensive computations or subprocess-compatible operations
-from the main event loop, while maintaining Falyx's composable, hookable, and injectable
-execution model.
-
-`ProcessAction` mirrors the behavior of a normal `Action`, but ensures isolation from
-the asyncio event loop and handles serialization (pickling) of arguments and injected
-state.
-
-Key Features:
-- Runs a callable in a separate Python process
-- Compatible with `last_result` injection for chained workflows
-- Validates that injected values are pickleable before dispatch
-- Supports hook lifecycle (`before`, `on_success`, `on_error`, etc.)
-- Custom executor support for reuse or configuration
-
-Use Cases:
-- CPU-intensive operations (e.g., image processing, simulations, data transformations)
-- Blocking third-party libraries that don't cooperate with asyncio
-- CLI workflows that require subprocess-level parallelism or safety
-
-Example:
-    ProcessAction(
-        name="ComputeChecksum",
-        action=calculate_sha256,
-        args=("large_file.bin",),
-    )
-
-Raises:
-- `ValueError`: If an injected value is not pickleable
-- `Exception`: Propagated from the subprocess on failure
-
-This module enables structured offloading of workload in CLI pipelines while maintaining
-full introspection and lifecycle management.
-"""
-from __future__ import annotations
-
-import asyncio
-from concurrent.futures import ProcessPoolExecutor
-from functools import partial
-from typing import Any, Callable
-
-from rich.tree import Tree
-
-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
-from falyx.themes import OneColors
-
-
-class ProcessAction(BaseAction):
-    """
-    ProcessAction runs a function in a separate process using ProcessPoolExecutor.
-
-    Features:
-    - Executes CPU-bound or blocking tasks without blocking the main event loop.
-    - Supports last_result injection into the subprocess.
-    - Validates that last_result is pickleable when injection is enabled.
-
-    Args:
-        name (str): Name of the action.
-        func (Callable): Function to execute in a new process.
-        args (tuple, optional): Positional arguments.
-        kwargs (dict, optional): Keyword arguments.
-        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_into (str, optional): Name of the injected key.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        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_into: str = "last_result",
-        never_prompt: bool | None = None,
-        logging_hooks: bool = False,
-        spinner: bool = False,
-        spinner_message: str = "Processing...",
-        spinner_type: str = "dots",
-        spinner_style: str = OneColors.CYAN,
-        spinner_speed: float = 1.0,
-    ):
-        super().__init__(
-            name,
-            hooks=hooks,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-            never_prompt=never_prompt,
-            logging_hooks=logging_hooks,
-            spinner=spinner,
-            spinner_message=spinner_message,
-            spinner_type=spinner_type,
-            spinner_style=spinner_style,
-            spinner_speed=spinner_speed,
-        )
-        self.action = action
-        self.args = args
-        self.kwargs = kwargs or {}
-        self.executor = executor or ProcessPoolExecutor()
-        self.is_retryable = True
-
-    def get_infer_target(self) -> tuple[Callable[..., Any] | None, None]:
-        return self.action, None
-
-    async def _run(self, *args, **kwargs) -> Any:
-        if self.inject_last_result and self.shared_context:
-            last_result = self.shared_context.last_result()
-            if not self._validate_pickleable(last_result):
-                raise ValueError(
-                    f"Cannot inject last result into {self.name}: "
-                    f"last result is not pickleable."
-                )
-        combined_args = args + self.args
-        combined_kwargs = self._maybe_inject_last_result({**self.kwargs, **kwargs})
-        context = ExecutionContext(
-            name=self.name,
-            args=combined_args,
-            kwargs=combined_kwargs,
-            action=self,
-        )
-        loop = asyncio.get_running_loop()
-
-        context.start_timer()
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-            result = await loop.run_in_executor(
-                self.executor, partial(self.action, *combined_args, **combined_kwargs)
-            )
-            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)
-            if context.result is not None:
-                return context.result
-            raise
-        finally:
-            context.stop_timer()
-            await self.hooks.trigger(HookType.AFTER, context)
-            await self.hooks.trigger(HookType.ON_TEARDOWN, context)
-            er.record(context)
-
-    def _validate_pickleable(self, obj: Any) -> bool:
-        try:
-            import pickle
-
-            pickle.dumps(obj)
-            return True
-        except (pickle.PicklingError, TypeError):
-            return False
-
-    async def preview(self, parent: Tree | None = None):
-        label = [
-            f"[{OneColors.DARK_YELLOW_b}]🧠 ProcessAction (new process)[/] '{self.name}'"
-        ]
-        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)))
-
-    def __str__(self) -> str:
-        return (
-            f"ProcessAction(name={self.name!r}, "
-            f"action={getattr(self.action, '__name__', repr(self.action))}, "
-            f"args={self.args!r}, kwargs={self.kwargs!r})"
-        )

falyx/action/process_pool_action.py

@@ -1,235 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `ProcessPoolAction`, a parallelized action executor that distributes
-tasks across multiple processes using Python's `concurrent.futures.ProcessPoolExecutor`.
-
-This module enables structured execution of CPU-bound tasks in parallel while
-retaining Falyx's core guarantees: lifecycle hooks, error isolation, execution context
-tracking, and introspectable previews.
-
-Key Components:
-- ProcessTask: Lightweight wrapper for a task + args/kwargs
-- ProcessPoolAction: Parallel action that runs tasks concurrently in separate processes
-
-Use this module to accelerate workflows involving expensive computation or
-external resources that benefit from true parallelism.
-"""
-from __future__ import annotations
-
-import asyncio
-import random
-from concurrent.futures import ProcessPoolExecutor
-from dataclasses import dataclass, field
-from functools import partial
-from typing import Any, Callable, Sequence
-
-from rich.tree import Tree
-
-from falyx.action.base_action import BaseAction
-from falyx.context import ExecutionContext, SharedContext
-from falyx.exceptions import EmptyPoolError
-from falyx.execution_registry import ExecutionRegistry as er
-from falyx.hook_manager import HookManager, HookType
-from falyx.logger import logger
-from falyx.parser.utils import same_argument_definitions
-from falyx.themes import OneColors
-
-
-@dataclass
-class ProcessTask:
-    """
-    Represents a callable task with its arguments for parallel execution.
-
-    This lightweight container is used to queue individual tasks for execution
-    inside a `ProcessPoolAction`.
-
-    Attributes:
-        task (Callable): A function to execute.
-        args (tuple): Positional arguments to pass to the function.
-        kwargs (dict): Keyword arguments to pass to the function.
-
-    Raises:
-        TypeError: If `task` is not callable.
-    """
-
-    task: Callable[..., Any]
-    args: tuple = ()
-    kwargs: dict[str, Any] = field(default_factory=dict)
-
-    def __post_init__(self):
-        if not callable(self.task):
-            raise TypeError(f"Expected a callable task, got {type(self.task).__name__}")
-
-
-class ProcessPoolAction(BaseAction):
-    """
-    Executes a set of independent tasks in parallel using a process pool.
-
-    `ProcessPoolAction` is ideal for CPU-bound tasks that benefit from
-    concurrent execution in separate processes. Each task is wrapped in a
-    `ProcessTask` instance and executed in a `concurrent.futures.ProcessPoolExecutor`.
-
-    Key Features:
-    - Parallel, process-based execution
-    - Hook lifecycle support across all stages
-    - Supports argument injection (e.g., `last_result`)
-    - Compatible with retry behavior and shared context propagation
-    - Captures all task results (including exceptions) and records execution context
-
-    Args:
-        name (str): Name of the action. Used for logging and debugging.
-        actions (Sequence[ProcessTask] | None): A list of tasks to run.
-        hooks (HookManager | None): Optional hook manager for lifecycle events.
-        executor (ProcessPoolExecutor | None): Custom executor instance (optional).
-        inject_last_result (bool): Whether to inject the last result into task kwargs.
-        inject_into (str): Name of the kwarg to use for injected result.
-
-    Returns:
-        list[Any]: A list of task results in submission order. Exceptions are preserved.
-
-    Raises:
-        EmptyPoolError: If no actions are registered.
-        ValueError: If injected `last_result` is not pickleable.
-
-    Example:
-        ProcessPoolAction(
-            name="ParallelTransforms",
-            actions=[
-                ProcessTask(func_a, args=(1,)),
-                ProcessTask(func_b, kwargs={"x": 2}),
-            ]
-        )
-    """
-
-    def __init__(
-        self,
-        name: str,
-        actions: Sequence[ProcessTask] | None = None,
-        *,
-        hooks: HookManager | None = None,
-        executor: ProcessPoolExecutor | None = None,
-        inject_last_result: bool = False,
-        inject_into: str = "last_result",
-    ):
-        super().__init__(
-            name,
-            hooks=hooks,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-        )
-        self.executor = executor or ProcessPoolExecutor()
-        self.is_retryable = True
-        self.actions: list[ProcessTask] = []
-        if actions:
-            self.set_actions(actions)
-
-    def set_actions(self, actions: Sequence[ProcessTask]) -> None:
-        """Replaces the current action list with a new one."""
-        self.actions.clear()
-        for action in actions:
-            self.add_action(action)
-
-    def add_action(self, action: ProcessTask) -> None:
-        if not isinstance(action, ProcessTask):
-            raise TypeError(f"Expected a ProcessTask, got {type(action).__name__}")
-        self.actions.append(action)
-
-    def get_infer_target(self) -> tuple[Callable[..., Any] | None, None]:
-        arg_defs = same_argument_definitions([action.task for action in self.actions])
-        if arg_defs:
-            return self.actions[0].task, None
-        logger.debug(
-            "[%s] auto_args disabled: mismatched ProcessPoolAction arguments",
-            self.name,
-        )
-        return None, None
-
-    async def _run(self, *args, **kwargs) -> Any:
-        if not self.actions:
-            raise EmptyPoolError(f"[{self.name}] No actions to execute.")
-        shared_context = SharedContext(name=self.name, action=self, is_parallel=True)
-        if self.shared_context:
-            shared_context.set_shared_result(self.shared_context.last_result())
-        if self.inject_last_result and self.shared_context:
-            last_result = self.shared_context.last_result()
-            if not self._validate_pickleable(last_result):
-                raise ValueError(
-                    f"Cannot inject last result into {self.name}: "
-                    f"last result is not pickleable."
-                )
-        updated_kwargs = self._maybe_inject_last_result(kwargs)
-        context = ExecutionContext(
-            name=self.name,
-            args=args,
-            kwargs=updated_kwargs,
-            action=self,
-        )
-        loop = asyncio.get_running_loop()
-
-        context.start_timer()
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-            futures = [
-                loop.run_in_executor(
-                    self.executor,
-                    partial(
-                        task.task,
-                        *(*args, *task.args),
-                        **{**updated_kwargs, **task.kwargs},
-                    ),
-                )
-                for task in self.actions
-            ]
-            results = await asyncio.gather(*futures, return_exceptions=True)
-            context.result = results
-            await self.hooks.trigger(HookType.ON_SUCCESS, context)
-            return results
-        except Exception as error:
-            context.exception = error
-            await self.hooks.trigger(HookType.ON_ERROR, context)
-            if context.result is not None:
-                return context.result
-            raise
-        finally:
-            context.stop_timer()
-            await self.hooks.trigger(HookType.AFTER, context)
-            await self.hooks.trigger(HookType.ON_TEARDOWN, context)
-            er.record(context)
-
-    def _validate_pickleable(self, obj: Any) -> bool:
-        try:
-            import pickle
-
-            pickle.dumps(obj)
-            return True
-        except (pickle.PicklingError, TypeError):
-            return False
-
-    async def preview(self, parent: Tree | None = None):
-        label = [f"[{OneColors.DARK_YELLOW_b}]🧠 ProcessPoolAction[/] '{self.name}'"]
-        if self.inject_last_result:
-            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)
-        for action in actions:
-            label = [
-                f"[{OneColors.DARK_YELLOW_b}]  - {getattr(action.task, '__name__', repr(action.task))}[/] "
-                f"[dim]({', '.join(map(repr, action.args))})[/]"
-            ]
-            if action.kwargs:
-                label.append(
-                    f" [dim]({', '.join(f'{k}={v!r}' for k, v in action.kwargs.items())})[/]"
-                )
-            tree.add("".join(label))
-
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self) -> str:
-        return (
-            f"ProcessPoolAction(name={self.name!r}, "
-            f"actions={[getattr(action.task, '__name__', repr(action.task)) for action in self.actions]}, "
-            f"inject_last_result={self.inject_last_result}, "
-            f"inject_into={self.inject_into!r})"
-        )

falyx/action/prompt_menu_action.py

@@ -1,191 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `PromptMenuAction`, a Falyx Action that prompts the user to choose from
-a list of labeled options using a single-line prompt input. Each option corresponds
-to a `MenuOption` that wraps a description and an executable action.
-
-Unlike `MenuAction`, this action renders a flat, inline prompt (e.g., `Option1 | Option2`)
-without using a rich table. It is ideal for compact decision points, hotkey-style menus,
-or contextual user input flows.
-
-Key Components:
-- PromptMenuAction: Inline prompt-driven menu runner
-"""
-from typing import Any
-
-from prompt_toolkit import PromptSession
-from prompt_toolkit.formatted_text import FormattedText, merge_formatted_text
-from rich.tree import Tree
-
-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
-from falyx.logger import logger
-from falyx.menu import MenuOptionMap
-from falyx.prompt_utils import rich_text_to_prompt_text
-from falyx.signals import BackSignal, CancelSignal, QuitSignal
-from falyx.themes import OneColors
-
-
-class PromptMenuAction(BaseAction):
-    """
-    Displays a single-line interactive prompt for selecting an option from a menu.
-
-    `PromptMenuAction` is a lightweight alternative to `MenuAction`, offering a more
-    compact selection interface. Instead of rendering a full table, it displays
-    available keys inline as a placeholder (e.g., `A | B | C`) and accepts the user's
-    input to execute the associated action.
-
-    Each key is defined in a `MenuOptionMap`, which maps to a `MenuOption` containing
-    a description and an executable action.
-
-    Key Features:
-    - Minimal UI: rendered as a single prompt line with placeholder
-    - Optional fallback to `default_selection` or injected `last_result`
-    - Fully hookable lifecycle (before, success, error, after, teardown)
-    - Supports reserved keys and structured error recovery
-
-    Args:
-        name (str): Name of the action. Used for logging and debugging.
-        menu_options (MenuOptionMap): A mapping of keys to `MenuOption` objects.
-        prompt_message (str): Text displayed before user input (default: "Select > ").
-        default_selection (str): Fallback key if no input is provided.
-        inject_last_result (bool): Whether to use `last_result` as a fallback input key.
-        inject_into (str): Kwarg name under which to inject the last result.
-        prompt_session (PromptSession | None): Custom Prompt Toolkit session.
-        never_prompt (bool): If True, skips user input and uses `default_selection`.
-        include_reserved (bool): Whether to include reserved keys in logic and preview.
-
-    Returns:
-        Any: The result of the selected option's action.
-
-    Raises:
-        BackSignal: If the user signals to return to the previous menu.
-        QuitSignal: If the user signals to exit the CLI entirely.
-        ValueError: If `never_prompt` is enabled but no fallback is available.
-        Exception: If an error occurs during the action's execution.
-
-    Example:
-        PromptMenuAction(
-            name="HotkeyPrompt",
-            menu_options=MenuOptionMap(options={
-                "R": MenuOption("Run", ChainedAction(...)),
-                "S": MenuOption("Skip", Action(...)),
-            }),
-            prompt_message="Choose action > ",
-        )
-    """
-
-    def __init__(
-        self,
-        name: str,
-        menu_options: MenuOptionMap,
-        *,
-        prompt_message: str = "Select > ",
-        default_selection: str = "",
-        inject_last_result: bool = False,
-        inject_into: str = "last_result",
-        prompt_session: PromptSession | None = None,
-        never_prompt: bool = False,
-        include_reserved: bool = True,
-    ):
-        super().__init__(
-            name,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-            never_prompt=never_prompt,
-        )
-        self.menu_options = menu_options
-        self.prompt_message = rich_text_to_prompt_text(prompt_message)
-        self.default_selection = default_selection
-        self.prompt_session = prompt_session or PromptSession(
-            interrupt_exception=CancelSignal
-        )
-        self.include_reserved = include_reserved
-
-    def get_infer_target(self) -> tuple[None, None]:
-        return None, None
-
-    async def _run(self, *args, **kwargs) -> Any:
-        kwargs = self._maybe_inject_last_result(kwargs)
-        context = ExecutionContext(
-            name=self.name,
-            args=args,
-            kwargs=kwargs,
-            action=self,
-        )
-
-        effective_default = self.default_selection
-        maybe_result = str(self.last_result)
-        if maybe_result in self.menu_options:
-            effective_default = maybe_result
-        elif self.inject_last_result:
-            logger.warning(
-                "[%s] Injected last result '%s' not found in menu options",
-                self.name,
-                maybe_result,
-            )
-
-        if self.never_prompt and not effective_default:
-            raise ValueError(
-                f"[{self.name}] 'never_prompt' is True but no valid default_selection"
-                " was provided."
-            )
-
-        context.start_timer()
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-            key = effective_default
-            if not self.never_prompt:
-                placeholder_formatted_text = []
-                for index, (key, option) in enumerate(self.menu_options.items()):
-                    placeholder_formatted_text.append(option.render_prompt(key))
-                    if index < len(self.menu_options) - 1:
-                        placeholder_formatted_text.append(
-                            FormattedText([(OneColors.WHITE, " | ")])
-                        )
-                placeholder = merge_formatted_text(placeholder_formatted_text)
-                key = await self.prompt_session.prompt_async(
-                    message=self.prompt_message, placeholder=placeholder
-                )
-            option = self.menu_options[key]
-            result = await option.action(*args, **kwargs)
-            context.result = result
-            await self.hooks.trigger(HookType.ON_SUCCESS, context)
-            return result
-
-        except BackSignal:
-            logger.debug("[%s][BackSignal] ← Returning to previous menu", self.name)
-            return None
-        except QuitSignal:
-            logger.debug("[%s][QuitSignal] ← Exiting application", self.name)
-            raise
-        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.LIGHT_YELLOW_b}]📋 PromptMenuAction[/] '{self.name}'"
-        tree = parent.add(label) if parent else Tree(label)
-        for key, option in self.menu_options.items():
-            tree.add(
-                f"[dim]{key}[/]: {option.description} → [italic]{option.action.name}[/]"
-            )
-            await option.action.preview(parent=tree)
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self) -> str:
-        return (
-            f"PromptMenuAction(name={self.name!r}, options={list(self.menu_options.keys())!r}, "
-            f"default_selection={self.default_selection!r}, "
-            f"include_reserved={self.include_reserved}, "
-            f"prompt={'off' if self.never_prompt else 'on'})"
-        )

falyx/action/save_file_action.py

@@ -1,296 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `SaveFileAction`, a Falyx Action for writing structured or unstructured data
-to a file in a variety of supported formats.
-
-Supports overwrite control, automatic directory creation, and full lifecycle hook
-integration. Compatible with chaining and injection of upstream results via
-`inject_last_result`.
-
-Supported formats: TEXT, JSON, YAML, TOML, CSV, TSV, XML
-
-Key Features:
-- Auto-serialization of Python data to structured formats
-- Flexible path control with directory creation and overwrite handling
-- Injection of data via chaining (`last_result`)
-- Preview mode with file metadata visualization
-
-Common use cases:
-- Writing processed results to disk
-- Logging artifacts from batch pipelines
-- Exporting config or user input to JSON/YAML for reuse
-"""
-import csv
-import json
-import xml.etree.ElementTree as ET
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Literal
-
-import toml
-import yaml
-from rich.tree import Tree
-
-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
-from falyx.logger import logger
-from falyx.themes import OneColors
-
-
-class SaveFileAction(BaseAction):
-    """
-    Saves data to a file in the specified format.
-
-    `SaveFileAction` serializes and writes input data to disk using the format
-    defined by `file_type`. It supports plain text and structured formats like
-    JSON, YAML, TOML, CSV, TSV, and XML. Files may be overwritten or appended
-    based on settings, and parent directories are created if missing.
-
-    Data can be provided directly via the `data` argument or dynamically injected
-    from the previous Action using `inject_last_result`.
-
-    Key Features:
-    - Format-aware saving with validation
-    - Lifecycle hook support (before, success, error, after, teardown)
-    - Chain-compatible via last_result injection
-    - Supports safe overwrite behavior and preview diagnostics
-
-    Args:
-        name (str): Name of the action. Used for logging and debugging.
-        file_path (str | Path): Destination file path.
-        file_type (FileType | str): Output format (e.g., "json", "yaml", "text").
-        mode (Literal["w", "a"]): File mode—write or append. Default is "w".
-        encoding (str): Encoding to use when writing files (default: "UTF-8").
-        data (Any): Data to save. If omitted, uses last_result injection.
-        overwrite (bool): Whether to overwrite existing files. Default is True.
-        create_dirs (bool): Whether to auto-create parent directories.
-        inject_last_result (bool): Inject previous result as input if enabled.
-        inject_into (str): Name of kwarg to inject last_result into (default: "data").
-
-    Returns:
-        str: The full path to the saved file.
-
-    Raises:
-        FileExistsError: If the file exists and `overwrite` is False.
-        FileNotFoundError: If parent directory is missing and `create_dirs` is False.
-        ValueError: If data format is invalid for the target file type.
-        Exception: Any errors encountered during file writing.
-
-    Example:
-        SaveFileAction(
-            name="SaveOutput",
-            file_path="output/data.json",
-            file_type="json",
-            inject_last_result=True
-        )
-    """
-
-    def __init__(
-        self,
-        name: str,
-        file_path: str,
-        file_type: FileType | str = FileType.TEXT,
-        mode: Literal["w", "a"] = "w",
-        encoding: str = "UTF-8",
-        data: Any = None,
-        overwrite: bool = True,
-        create_dirs: bool = True,
-        inject_last_result: bool = False,
-        inject_into: str = "data",
-    ):
-        """
-        SaveFileAction allows saving data to a file.
-
-        Args:
-            name (str): Name of the action.
-            file_path (str | Path): Path to the file where data will be saved.
-            file_type (FileType | str): Format to write to (e.g. TEXT, JSON, YAML).
-            mode (Literal["w", "a"]): File mode (default: "w").
-            encoding (str): Encoding to use when writing files (default: "UTF-8").
-            data (Any): Data to be saved (if not using inject_last_result).
-            overwrite (bool): Whether to overwrite the file if it exists.
-            create_dirs (bool): Whether to create parent directories if they do not exist.
-            inject_last_result (bool): Whether to inject result from previous action.
-            inject_into (str): Kwarg name to inject the last result as.
-        """
-        super().__init__(
-            name=name, inject_last_result=inject_last_result, inject_into=inject_into
-        )
-        self._file_path = self._coerce_file_path(file_path)
-        self._file_type = FileType(file_type)
-        self.data = data
-        self.overwrite = overwrite
-        self.mode = mode
-        self.create_dirs = create_dirs
-        self.encoding = encoding
-
-    @property
-    def file_path(self) -> Path | None:
-        """Get the file path as a Path object."""
-        return self._file_path
-
-    @file_path.setter
-    def file_path(self, value: str | Path):
-        """Set the file path, converting to Path if necessary."""
-        self._file_path = self._coerce_file_path(value)
-
-    def _coerce_file_path(self, file_path: str | Path | None) -> Path | None:
-        """Coerce the file path to a Path object."""
-        if isinstance(file_path, Path):
-            return file_path
-        elif isinstance(file_path, str):
-            return Path(file_path)
-        elif file_path is None:
-            return None
-        else:
-            raise TypeError("file_path must be a string or Path object")
-
-    @property
-    def file_type(self) -> FileType:
-        """Get the file type."""
-        return self._file_type
-
-    def get_infer_target(self) -> tuple[None, None]:
-        return None, None
-
-    def _dict_to_xml(self, data: dict, root: ET.Element) -> None:
-        """Convert a dictionary to XML format."""
-        for key, value in data.items():
-            if isinstance(value, dict):
-                sub_element = ET.SubElement(root, key)
-                self._dict_to_xml(value, sub_element)
-            elif isinstance(value, list):
-                for item in value:
-                    item_element = ET.SubElement(root, key)
-                    if isinstance(item, dict):
-                        self._dict_to_xml(item, item_element)
-                    else:
-                        item_element.text = str(item)
-            else:
-                element = ET.SubElement(root, key)
-                element.text = str(value)
-
-    async def save_file(self, data: Any) -> None:
-        """Save data to the specified file in the desired format."""
-        if self.file_path is None:
-            raise ValueError("file_path must be set before saving a file")
-        elif self.file_path.exists() and not self.overwrite:
-            raise FileExistsError(f"File already exists: {self.file_path}")
-
-        if self.file_path.parent and not self.file_path.parent.exists():
-            if self.create_dirs:
-                self.file_path.parent.mkdir(parents=True, exist_ok=True)
-            else:
-                raise FileNotFoundError(
-                    f"Directory does not exist: {self.file_path.parent}"
-                )
-
-        try:
-            if self.file_type == FileType.TEXT:
-                self.file_path.write_text(data, encoding=self.encoding)
-            elif self.file_type == FileType.JSON:
-                self.file_path.write_text(
-                    json.dumps(data, indent=4), encoding=self.encoding
-                )
-            elif self.file_type == FileType.TOML:
-                self.file_path.write_text(toml.dumps(data), encoding=self.encoding)
-            elif self.file_type == FileType.YAML:
-                self.file_path.write_text(yaml.dump(data), encoding=self.encoding)
-            elif self.file_type == FileType.CSV:
-                if not isinstance(data, list) or not all(
-                    isinstance(row, list) for row in data
-                ):
-                    raise ValueError(
-                        f"{self.file_type.name} file type requires a list of lists"
-                    )
-                with open(
-                    self.file_path, mode=self.mode, newline="", encoding=self.encoding
-                ) as csvfile:
-                    writer = csv.writer(csvfile)
-                    writer.writerows(data)
-            elif self.file_type == FileType.TSV:
-                if not isinstance(data, list) or not all(
-                    isinstance(row, list) for row in data
-                ):
-                    raise ValueError(
-                        f"{self.file_type.name} file type requires a list of lists"
-                    )
-                with open(
-                    self.file_path, mode=self.mode, newline="", encoding=self.encoding
-                ) as tsvfile:
-                    writer = csv.writer(tsvfile, delimiter="\t")
-                    writer.writerows(data)
-            elif self.file_type == FileType.XML:
-                if not isinstance(data, dict):
-                    raise ValueError("XML file type requires data to be a dictionary")
-                root = ET.Element("root")
-                self._dict_to_xml(data, root)
-                tree = ET.ElementTree(root)
-                tree.write(self.file_path, encoding=self.encoding, xml_declaration=True)
-            else:
-                raise ValueError(f"Unsupported file type: {self.file_type}")
-
-        except Exception as error:
-            logger.error("Failed to save %s: %s", self.file_path.name, error)
-            raise
-
-    async def _run(self, *args, **kwargs):
-        combined_kwargs = self._maybe_inject_last_result(kwargs)
-        data = self.data or combined_kwargs.get(self.inject_into)
-
-        context = ExecutionContext(
-            name=self.name, args=args, kwargs=combined_kwargs, action=self
-        )
-        context.start_timer()
-
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-
-            await self.save_file(data)
-            logger.debug("File saved successfully: %s", self.file_path)
-
-            await self.hooks.trigger(HookType.ON_SUCCESS, context)
-            return str(self.file_path)
-
-        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}]💾 SaveFileAction[/] '{self.name}'"
-        tree = parent.add(label) if parent else Tree(label)
-
-        tree.add(f"[dim]Path:[/] {self.file_path}")
-        tree.add(f"[dim]Type:[/] {self.file_type.name}")
-        tree.add(f"[dim]Overwrite:[/] {self.overwrite}")
-
-        if self.file_path and self.file_path.exists():
-            if self.overwrite:
-                tree.add(f"[{OneColors.LIGHT_YELLOW}]⚠️ File will be overwritten[/]")
-            else:
-                tree.add(
-                    f"[{OneColors.DARK_RED}]❌ File exists and overwrite is disabled[/]"
-                )
-            stat = self.file_path.stat()
-            tree.add(f"[dim]Size:[/] {stat.st_size:,} bytes")
-            tree.add(
-                f"[dim]Modified:[/] {datetime.fromtimestamp(stat.st_mtime):%Y-%m-%d %H:%M:%S}"
-            )
-            tree.add(
-                f"[dim]Created:[/] {datetime.fromtimestamp(stat.st_ctime):%Y-%m-%d %H:%M:%S}"
-            )
-
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self) -> str:
-        return f"SaveFileAction(file_path={self.file_path}, file_type={self.file_type})"

falyx/action/select_file_action.py

@@ -1,294 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `SelectFileAction`, a Falyx Action that allows users to select one or more
-files from a target directory and optionally return either their content or path,
-parsed based on a selected `FileType`.
-
-This action combines rich interactive selection (via `SelectionOption`) with
-format-aware parsing, making it ideal for loading external resources, injecting
-config files, or dynamically selecting inputs mid-pipeline.
-
-Supports filtering by file suffix, customizable prompt layout, multi-select mode,
-and automatic content parsing for common formats.
-
-Key Features:
-- Lists files from a directory and renders them in a Rich-powered menu
-- Supports suffix filtering (e.g., only `.yaml` or `.json` files)
-- Returns content parsed as `str`, `dict`, `list`, or raw `Path` depending on `FileType`
-- Works in single or multi-selection mode
-- Fully compatible with Falyx hooks and context system
-- Graceful cancellation via `CancelSignal`
-
-Supported Return Types (`FileType`):
-- `TEXT`: UTF-8 string content
-- `PATH`: File path object (`Path`)
-- `JSON`, `YAML`, `TOML`: Parsed dictionaries or lists
-- `CSV`, `TSV`: `list[list[str]]` from structured rows
-- `XML`: `ElementTree.Element` root object
-
-Use Cases:
-- Prompting users to select a config file during setup
-- Dynamically loading data into chained workflows
-- CLI interfaces that require structured file ingestion
-
-Example:
-    SelectFileAction(
-        name="ChooseConfigFile",
-        directory="configs/",
-        suffix_filter=".yaml",
-        return_type="yaml",
-    )
-
-This module is ideal for use cases where file choice is deferred to runtime
-and needs to feed into structured automation pipelines.
-"""
-from __future__ import annotations
-
-import csv
-import json
-import xml.etree.ElementTree as ET
-from pathlib import Path
-from typing import Any
-
-import toml
-import yaml
-from prompt_toolkit import PromptSession
-from rich.tree import Tree
-
-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
-from falyx.logger import logger
-from falyx.prompt_utils import rich_text_to_prompt_text
-from falyx.selection import (
-    SelectionOption,
-    prompt_for_selection,
-    render_selection_dict_table,
-)
-from falyx.signals import CancelSignal
-from falyx.themes import OneColors
-
-
-class SelectFileAction(BaseAction):
-    """
-    SelectFileAction allows users to select a file(s) from a directory and return:
-    - file content (as text, JSON, CSV, etc.)
-    - or the file path itself.
-
-    Supported formats: text, json, yaml, toml, csv, tsv, 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 (FileType): What to return (path, content, parsed).
-        number_selections (int | str): How many files to select (1, 2, '*').
-        separator (str): Separator for multiple selections.
-        allow_duplicates (bool): Allow selecting the same file multiple times.
-        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: FileType | str = FileType.PATH,
-        encoding: str = "UTF-8",
-        number_selections: int | str = 1,
-        separator: str = ",",
-        allow_duplicates: bool = False,
-        prompt_session: PromptSession | None = None,
-    ):
-        super().__init__(name)
-        self.directory = Path(directory).resolve()
-        self.title = title
-        self.columns = columns
-        self.prompt_message = rich_text_to_prompt_text(prompt_message)
-        self.suffix_filter = suffix_filter
-        self.style = style
-        self.number_selections = number_selections
-        self.separator = separator
-        self.allow_duplicates = allow_duplicates
-        self.prompt_session = prompt_session or PromptSession(
-            interrupt_exception=CancelSignal
-        )
-        self.return_type = FileType(return_type)
-        self.encoding = encoding
-
-    @property
-    def number_selections(self) -> int | str:
-        return self._number_selections
-
-    @number_selections.setter
-    def number_selections(self, value: int | str):
-        if isinstance(value, int) and value > 0:
-            self._number_selections: int | str = value
-        elif isinstance(value, str):
-            if value not in ("*"):
-                raise ValueError("number_selections string must be one of '*'")
-            self._number_selections = value
-        else:
-            raise ValueError("number_selections must be a positive integer or one of '*'")
-
-    def get_options(self, files: list[Path]) -> dict[str, SelectionOption]:
-        options = {}
-        for index, file in enumerate(files):
-            options[str(index)] = SelectionOption(
-                description=file.name,
-                value=file,  # Store the Path only — parsing will happen later
-                style=self.style,
-            )
-        return options
-
-    def parse_file(self, file: Path) -> Any:
-        value: Any
-        try:
-            if self.return_type == FileType.TEXT:
-                value = file.read_text(encoding=self.encoding)
-            elif self.return_type == FileType.PATH:
-                value = file
-            elif self.return_type == FileType.JSON:
-                value = json.loads(file.read_text(encoding=self.encoding))
-            elif self.return_type == FileType.TOML:
-                value = toml.loads(file.read_text(encoding=self.encoding))
-            elif self.return_type == FileType.YAML:
-                value = yaml.safe_load(file.read_text(encoding=self.encoding))
-            elif self.return_type == FileType.CSV:
-                with open(file, newline="", encoding=self.encoding) as csvfile:
-                    reader = csv.reader(csvfile)
-                    value = list(reader)
-            elif self.return_type == FileType.TSV:
-                with open(file, newline="", encoding=self.encoding) as tsvfile:
-                    reader = csv.reader(tsvfile, delimiter="\t")
-                    value = list(reader)
-            elif self.return_type == FileType.XML:
-                tree = ET.parse(file, parser=ET.XMLParser(encoding=self.encoding))
-                value = tree.getroot()
-            else:
-                raise ValueError(f"Unsupported return type: {self.return_type}")
-        except Exception as error:
-            logger.error("Failed to parse %s: %s", file.name, error)
-        return value
-
-    def _find_cancel_key(self, options) -> str:
-        """Return first numeric value not already used in the selection dict."""
-        for index in range(len(options)):
-            if str(index) not in options:
-                return str(index)
-        return str(len(options))
-
-    def get_infer_target(self) -> tuple[None, None]:
-        return None, None
-
-    async def _run(self, *args, **kwargs) -> Any:
-        context = ExecutionContext(name=self.name, args=args, kwargs=kwargs, action=self)
-        context.start_timer()
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-
-            if not self.directory.exists():
-                raise FileNotFoundError(f"Directory {self.directory} does not exist.")
-            elif not self.directory.is_dir():
-                raise NotADirectoryError(f"{self.directory} is not a directory.")
-
-            files = [
-                file
-                for file in self.directory.iterdir()
-                if file.is_file()
-                and (self.suffix_filter is None or file.suffix == self.suffix_filter)
-            ]
-            if not files:
-                raise FileNotFoundError("No files found in directory.")
-
-            options = self.get_options(files)
-
-            cancel_key = self._find_cancel_key(options)
-            cancel_option = {
-                cancel_key: SelectionOption(
-                    description="Cancel", value=CancelSignal(), style=OneColors.DARK_RED
-                )
-            }
-
-            table = render_selection_dict_table(
-                title=self.title, selections=options | cancel_option, columns=self.columns
-            )
-
-            keys = await prompt_for_selection(
-                (options | cancel_option).keys(),
-                table,
-                prompt_session=self.prompt_session,
-                prompt_message=self.prompt_message,
-                number_selections=self.number_selections,
-                separator=self.separator,
-                allow_duplicates=self.allow_duplicates,
-                cancel_key=cancel_key,
-            )
-
-            if isinstance(keys, str):
-                if keys == cancel_key:
-                    raise CancelSignal("User canceled the selection.")
-                result = self.parse_file(options[keys].value)
-            elif isinstance(keys, list):
-                result = [self.parse_file(options[key].value) for key in keys]
-
-            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}]📁 SelectFileAction[/] '{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}")
-        tree.add("[dim]Loading:[/] Lazy (parsing occurs after selection)")
-        try:
-            files = list(self.directory.iterdir())
-            if self.suffix_filter:
-                files = [file for file in files if file.suffix == self.suffix_filter]
-            sample = files[:10]
-            file_list = tree.add("[dim]Files:[/]")
-            for file in sample:
-                file_list.add(f"[dim]{file.name}[/]")
-            if len(files) > 10:
-                file_list.add(f"[dim]... ({len(files) - 10} more)[/]")
-        except Exception as error:
-            tree.add(f"[{OneColors.DARK_RED_b}]⚠️ Error scanning directory: {error}[/]")
-
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self) -> str:
-        return (
-            f"SelectFileAction(name={self.name!r}, dir={str(self.directory)!r}, "
-            f"suffix_filter={self.suffix_filter!r}, return_type={self.return_type})"
-        )

falyx/action/selection_action.py

@@ -1,555 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `SelectionAction`, a highly flexible Falyx Action for interactive or headless
-selection from a list or dictionary of user-defined options.
-
-This module powers workflows that require prompting the user for input, selecting
-configuration presets, branching execution paths, or collecting multiple values
-in a type-safe, hook-compatible, and composable way.
-
-Key Features:
-- Supports both flat lists and structured dictionaries (`SelectionOptionMap`)
-- Handles single or multi-selection with configurable separators
-- Returns results in various formats (key, value, description, item, or mapping)
-- Integrates fully with Falyx lifecycle hooks and `last_result` injection
-- Works in interactive (`prompt_toolkit`) and non-interactive (headless) modes
-- Renders a Rich-based table preview for diagnostics or dry runs
-
-Usage Scenarios:
-- Guided CLI wizards or configuration menus
-- Dynamic branching or conditional step logic
-- User-driven parameterization in chained workflows
-- Reusable pickers for environments, files, datasets, etc.
-
-Example:
-    SelectionAction(
-        name="ChooseMode",
-        selections={"dev": "Development", "prod": "Production"},
-        return_type="key"
-    )
-
-This module is foundational to creating expressive, user-centered CLI experiences
-within Falyx while preserving reproducibility and automation friendliness.
-"""
-from typing import Any
-
-from prompt_toolkit import PromptSession
-from rich.tree import Tree
-
-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
-from falyx.logger import logger
-from falyx.prompt_utils import rich_text_to_prompt_text
-from falyx.selection import (
-    SelectionOption,
-    SelectionOptionMap,
-    prompt_for_index,
-    prompt_for_selection,
-    render_selection_dict_table,
-    render_selection_indexed_table,
-)
-from falyx.signals import CancelSignal
-from falyx.themes import OneColors
-
-
-class SelectionAction(BaseAction):
-    """
-    A Falyx Action for interactively or programmatically selecting one or more items
-    from a list or dictionary of options.
-
-    `SelectionAction` supports both `list[str]` and `dict[str, SelectionOption]`
-    inputs. It renders a prompt (unless `never_prompt=True`), validates user input
-    or injected defaults, and returns a structured result based on the specified
-    `return_type`.
-
-    It is commonly used for item pickers, confirmation flows, dynamic parameterization,
-    or guided workflows in interactive or headless CLI pipelines.
-
-    Features:
-    - Supports single or multiple selections (`number_selections`)
-    - Dictionary mode allows rich metadata (description, value, style)
-    - Flexible return values: key(s), value(s), item(s), description(s), or mappings
-    - Fully hookable lifecycle (`before`, `on_success`, `on_error`, `after`, `on_teardown`)
-    - Default selection logic supports previous results (`last_result`)
-    - Can run in headless mode using `never_prompt` and fallback defaults
-
-    Args:
-        name (str): Action name for tracking and logging.
-        selections (list[str] | dict[str, SelectionOption] | dict[str, Any]):
-            The available choices. If a plain dict is passed, values are converted
-            into `SelectionOption` instances.
-        title (str): Title shown in the selection UI (default: "Select an option").
-        columns (int): Number of columns in the selection table.
-        prompt_message (str): Input prompt for the user (default: "Select > ").
-        default_selection (str | list[str]): Key(s) or index(es) used as fallback selection.
-        number_selections (int | str): Max number of choices allowed (or "*" for unlimited).
-        separator (str): Character used to separate multi-selections (default: ",").
-        allow_duplicates (bool): Whether duplicate selections are allowed.
-        inject_last_result (bool): If True, attempts to inject the last result as default.
-        inject_into (str): The keyword name for injected value (default: "last_result").
-        return_type (SelectionReturnType | str): The type of result to return.
-        prompt_session (PromptSession | None): Reused or customized prompt_toolkit session.
-        never_prompt (bool): If True, skips prompting and uses default_selection or last_result.
-        show_table (bool): Whether to render the selection table before prompting.
-
-    Returns:
-        Any: The selected result(s), shaped according to `return_type`.
-
-    Raises:
-        CancelSignal: If the user chooses the cancel option.
-        ValueError: If configuration is invalid or no selection can be resolved.
-        TypeError: If `selections` is not a supported type.
-
-    Example:
-        SelectionAction(
-            name="PickEnv",
-            selections={"dev": "Development", "prod": "Production"},
-            return_type="key",
-        )
-
-    This Action supports use in both interactive menus and chained, non-interactive CLI flows.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        selections: (
-            list[str]
-            | set[str]
-            | tuple[str, ...]
-            | dict[str, SelectionOption]
-            | dict[str, Any]
-        ),
-        *,
-        title: str = "Select an option",
-        columns: int = 5,
-        prompt_message: str = "Select > ",
-        default_selection: str | list[str] = "",
-        number_selections: int | str = 1,
-        separator: str = ",",
-        allow_duplicates: bool = False,
-        inject_last_result: bool = False,
-        inject_into: str = "last_result",
-        return_type: SelectionReturnType | str = "value",
-        prompt_session: PromptSession | None = None,
-        never_prompt: bool = False,
-        show_table: bool = True,
-    ):
-        super().__init__(
-            name,
-            inject_last_result=inject_last_result,
-            inject_into=inject_into,
-            never_prompt=never_prompt,
-        )
-        # Setter normalizes to correct type, mypy can't infer that
-        self.selections: list[str] | SelectionOptionMap = selections  # type: ignore[assignment]
-        self.return_type: SelectionReturnType = SelectionReturnType(return_type)
-        self.title = title
-        self.columns = columns
-        self.prompt_session = prompt_session or PromptSession(
-            interrupt_exception=CancelSignal
-        )
-        self.default_selection = default_selection
-        self.number_selections = number_selections
-        self.separator = separator
-        self.allow_duplicates = allow_duplicates
-        self.prompt_message = rich_text_to_prompt_text(prompt_message)
-        self.show_table = show_table
-
-    @property
-    def number_selections(self) -> int | str:
-        return self._number_selections
-
-    @number_selections.setter
-    def number_selections(self, value: int | str):
-        if isinstance(value, int) and value > 0:
-            self._number_selections: int | str = value
-        elif isinstance(value, str):
-            if value not in ("*"):
-                raise ValueError("number_selections string must be '*'")
-            self._number_selections = value
-        else:
-            raise ValueError("number_selections must be a positive integer or '*'")
-
-    @property
-    def selections(self) -> list[str] | SelectionOptionMap:
-        return self._selections
-
-    @selections.setter
-    def selections(
-        self, value: list[str] | set[str] | tuple[str, ...] | dict[str, SelectionOption]
-    ):
-        if isinstance(value, (list, tuple, set)):
-            self._selections: list[str] | SelectionOptionMap = list(value)
-        elif isinstance(value, dict):
-            som = SelectionOptionMap()
-            if all(isinstance(key, str) for key in value) and all(
-                not isinstance(value[key], SelectionOption) for key in value
-            ):
-                som.update(
-                    {
-                        str(index): SelectionOption(key, option)
-                        for index, (key, option) in enumerate(value.items())
-                    }
-                )
-            elif all(isinstance(key, str) for key in value) and all(
-                isinstance(value[key], SelectionOption) for key in value
-            ):
-                som.update(value)
-            else:
-                raise ValueError("Invalid dictionary format. Keys must be strings")
-            self._selections = som
-        else:
-            raise TypeError(
-                "'selections' must be a list[str] or dict[str, SelectionOption], "
-                f"got {type(value).__name__}"
-            )
-
-    def _find_cancel_key(self) -> str:
-        """Find the cancel key in the selections."""
-        if isinstance(self.selections, dict):
-            for index in range(len(self.selections) + 1):
-                if str(index) not in self.selections:
-                    return str(index)
-        return str(len(self.selections))
-
-    @property
-    def cancel_key(self) -> str:
-        return self._cancel_key
-
-    @cancel_key.setter
-    def cancel_key(self, value: str) -> None:
-        """Set the cancel key for the selection."""
-        if not isinstance(value, str):
-            raise TypeError("Cancel key must be a string.")
-        if isinstance(self.selections, dict) and value in self.selections:
-            raise ValueError(
-                "Cancel key cannot be one of the selection keys. "
-                f"Current selections: {self.selections}"
-            )
-        if isinstance(self.selections, list):
-            if not value.isdigit() or int(value) > len(self.selections):
-                raise ValueError(
-                    "cancel_key must be a digit and not greater than the number of selections."
-                )
-        self._cancel_key = value
-
-    def cancel_formatter(self, index: int, selection: str) -> str:
-        """Format the cancel option for display."""
-        if self.cancel_key == str(index):
-            return f"[{index}] [{OneColors.DARK_RED}]Cancel[/]"
-        return f"[{index}] {selection}"
-
-    def get_infer_target(self) -> tuple[None, None]:
-        return None, None
-
-    def _get_result_from_keys(self, keys: str | list[str]) -> Any:
-        if not isinstance(self.selections, dict):
-            raise TypeError("Selections must be a dictionary to get result by keys.")
-        if self.return_type == SelectionReturnType.KEY:
-            result: Any = keys
-        elif self.return_type == SelectionReturnType.VALUE:
-            if isinstance(keys, list):
-                result = [self.selections[key].value for key in keys]
-            elif isinstance(keys, str):
-                result = self.selections[keys].value
-        elif self.return_type == SelectionReturnType.ITEMS:
-            if isinstance(keys, list):
-                result = {key: self.selections[key] for key in keys}
-            elif isinstance(keys, str):
-                result = {keys: self.selections[keys]}
-        elif self.return_type == SelectionReturnType.DESCRIPTION:
-            if isinstance(keys, list):
-                result = [self.selections[key].description for key in keys]
-            elif isinstance(keys, str):
-                result = self.selections[keys].description
-        elif self.return_type == SelectionReturnType.DESCRIPTION_VALUE:
-            if isinstance(keys, list):
-                result = {
-                    self.selections[key].description: self.selections[key].value
-                    for key in keys
-                }
-            elif isinstance(keys, str):
-                result = {self.selections[keys].description: self.selections[keys].value}
-        else:
-            raise ValueError(f"Unsupported return type: {self.return_type}")
-        return result
-
-    async def _resolve_effective_default(self) -> str:
-        effective_default: str | list[str] = self.default_selection
-        maybe_result = self.last_result
-        if self.number_selections == 1:
-            if isinstance(effective_default, list):
-                effective_default = effective_default[0] if effective_default else ""
-            elif isinstance(maybe_result, list):
-                maybe_result = maybe_result[0] if maybe_result else ""
-            default = await self._resolve_single_default(maybe_result)
-            if not default:
-                default = await self._resolve_single_default(effective_default)
-            if not default and self.inject_last_result:
-                logger.warning(
-                    "[%s] Injected last result '%s' not found in selections",
-                    self.name,
-                    maybe_result,
-                )
-            return default
-
-        if maybe_result and isinstance(maybe_result, list):
-            maybe_result = [
-                await self._resolve_single_default(item) for item in maybe_result
-            ]
-            if (
-                maybe_result
-                and self.number_selections != "*"
-                and len(maybe_result) != self.number_selections
-            ):
-                raise ValueError(
-                    f"[{self.name}] 'number_selections' is {self.number_selections}, "
-                    f"but last_result has a different length: {len(maybe_result)}."
-                )
-            return self.separator.join(maybe_result)
-        elif effective_default and isinstance(effective_default, list):
-            effective_default = [
-                await self._resolve_single_default(item) for item in effective_default
-            ]
-            if (
-                effective_default
-                and self.number_selections != "*"
-                and len(effective_default) != self.number_selections
-            ):
-                raise ValueError(
-                    f"[{self.name}] 'number_selections' is {self.number_selections}, "
-                    f"but default_selection has a different length: {len(effective_default)}."
-                )
-            return self.separator.join(effective_default)
-        if self.inject_last_result:
-            logger.warning(
-                "[%s] Injected last result '%s' not found in selections",
-                self.name,
-                maybe_result,
-            )
-        return ""
-
-    async def _resolve_single_default(self, maybe_result: str) -> str:
-        effective_default = ""
-        if isinstance(self.selections, dict):
-            if str(maybe_result) in self.selections:
-                effective_default = str(maybe_result)
-            elif maybe_result in (
-                selection.value for selection in self.selections.values()
-            ):
-                selection = [
-                    key
-                    for key, sel in self.selections.items()
-                    if sel.value == maybe_result
-                ]
-                if selection:
-                    effective_default = selection[0]
-            elif maybe_result in (
-                selection.description for selection in self.selections.values()
-            ):
-                selection = [
-                    key
-                    for key, sel in self.selections.items()
-                    if sel.description == maybe_result
-                ]
-                if selection:
-                    effective_default = selection[0]
-        elif isinstance(self.selections, list):
-            if str(maybe_result).isdigit() and int(maybe_result) in range(
-                len(self.selections)
-            ):
-                effective_default = maybe_result
-            elif maybe_result in self.selections:
-                effective_default = str(self.selections.index(maybe_result))
-        return effective_default
-
-    async def _run(self, *args, **kwargs) -> Any:
-        kwargs = self._maybe_inject_last_result(kwargs)
-        context = ExecutionContext(
-            name=self.name,
-            args=args,
-            kwargs=kwargs,
-            action=self,
-        )
-
-        effective_default = await self._resolve_effective_default()
-
-        if self.never_prompt and not effective_default:
-            raise ValueError(
-                f"[{self.name}] 'never_prompt' is True but no valid default_selection "
-                "or usable last_result was available."
-            )
-
-        context.start_timer()
-        try:
-            self.cancel_key = self._find_cancel_key()
-            await self.hooks.trigger(HookType.BEFORE, context)
-            if isinstance(self.selections, list):
-                table = render_selection_indexed_table(
-                    title=self.title,
-                    selections=self.selections + ["Cancel"],
-                    columns=self.columns,
-                    formatter=self.cancel_formatter,
-                )
-                if effective_default is None or isinstance(effective_default, int):
-                    effective_default = ""
-
-                if not self.never_prompt:
-                    indices: int | list[int] = await prompt_for_index(
-                        len(self.selections),
-                        table,
-                        default_selection=effective_default,
-                        prompt_session=self.prompt_session,
-                        prompt_message=self.prompt_message,
-                        show_table=self.show_table,
-                        number_selections=self.number_selections,
-                        separator=self.separator,
-                        allow_duplicates=self.allow_duplicates,
-                        cancel_key=self.cancel_key,
-                    )
-                else:
-                    if effective_default and self.number_selections == 1:
-                        indices = int(effective_default)
-                    elif effective_default:
-                        indices = [
-                            int(index)
-                            for index in effective_default.split(self.separator)
-                        ]
-                    else:
-                        raise ValueError(
-                            f"[{self.name}] 'never_prompt' is True but no valid "
-                            "default_selection was provided."
-                        )
-
-                if indices == int(self.cancel_key):
-                    raise CancelSignal("User cancelled the selection.")
-                if isinstance(indices, list):
-                    result: str | list[str] = [
-                        self.selections[index] for index in indices
-                    ]
-                elif isinstance(indices, int):
-                    result = self.selections[indices]
-                else:
-                    assert False, "unreachable"
-            elif isinstance(self.selections, dict):
-                cancel_option = {
-                    self.cancel_key: SelectionOption(
-                        description="Cancel", value=CancelSignal, style=OneColors.DARK_RED
-                    )
-                }
-                table = render_selection_dict_table(
-                    title=self.title,
-                    selections=self.selections | cancel_option,
-                    columns=self.columns,
-                )
-                if not self.never_prompt:
-                    keys = await prompt_for_selection(
-                        (self.selections | cancel_option).keys(),
-                        table,
-                        default_selection=effective_default,
-                        prompt_session=self.prompt_session,
-                        prompt_message=self.prompt_message,
-                        show_table=self.show_table,
-                        number_selections=self.number_selections,
-                        separator=self.separator,
-                        allow_duplicates=self.allow_duplicates,
-                        cancel_key=self.cancel_key,
-                    )
-                else:
-                    if effective_default and self.number_selections == 1:
-                        keys = effective_default
-                    elif effective_default:
-                        keys = effective_default.split(self.separator)
-                    else:
-                        raise ValueError(
-                            f"[{self.name}] 'never_prompt' is True but no valid "
-                            "default_selection was provided."
-                        )
-                if keys == self.cancel_key:
-                    raise CancelSignal("User cancelled the selection.")
-
-                result = self._get_result_from_keys(keys)
-            else:
-                raise TypeError(
-                    "'selections' must be a list[str] or dict[str, Any], "
-                    f"got {type(self.selections).__name__}"
-                )
-            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.LIGHT_RED}]🧭 SelectionAction[/] '{self.name}'"
-        tree = parent.add(label) if parent else Tree(label)
-
-        if isinstance(self.selections, list):
-            sub = tree.add(f"[dim]Type:[/] List[str] ({len(self.selections)} items)")
-            for i, item in enumerate(self.selections[:10]):
-                sub.add(f"[dim]{i}[/]: {item}")
-            if len(self.selections) > 10:
-                sub.add(f"[dim]... ({len(self.selections) - 10} more)[/]")
-        elif isinstance(self.selections, dict):
-            sub = tree.add(
-                f"[dim]Type:[/] Dict[str, SelectionOption] ({len(self.selections)} items)"
-            )
-            for i, (key, option) in enumerate(list(self.selections.items())[:10]):
-                sub.add(f"[dim]{key}[/]: {option.description}")
-            if len(self.selections) > 10:
-                sub.add(f"[dim]... ({len(self.selections) - 10} more)[/]")
-        else:
-            tree.add(f"[{OneColors.DARK_RED_b}]Invalid selections type[/]")
-            return
-
-        default = self.default_selection or self.last_result
-        if isinstance(default, list):
-            default_display = self.separator.join(str(d) for d in default)
-        else:
-            default_display = str(default or "")
-
-        tree.add(f"[dim]Default:[/] '{default_display}'")
-
-        return_behavior = {
-            "KEY": "selected key(s)",
-            "VALUE": "mapped value(s)",
-            "DESCRIPTION": "description(s)",
-            "ITEMS": "SelectionOption object(s)",
-            "DESCRIPTION_VALUE": "{description: value}",
-        }.get(self.return_type.name, self.return_type.name)
-
-        tree.add(
-            f"[dim]Return:[/] {self.return_type.name.capitalize()} → {return_behavior}"
-        )
-        tree.add(f"[dim]Prompt:[/] {'Disabled' if self.never_prompt else 'Enabled'}")
-        tree.add(f"[dim]Columns:[/] {self.columns}")
-        tree.add(
-            f"[dim]Multi-select:[/] {'Yes' if self.number_selections != 1 else 'No'}"
-        )
-
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self) -> str:
-        selection_type = (
-            "List"
-            if isinstance(self.selections, list)
-            else "Dict" if isinstance(self.selections, dict) else "Unknown"
-        )
-        return (
-            f"SelectionAction(name={self.name!r}, type={selection_type}, "
-            f"default_selection={self.default_selection!r}, "
-            f"return_type={self.return_type!r}, "
-            f"prompt={'off' if self.never_prompt else 'on'})"
-        )

falyx/action/shell_action.py

@@ -1,104 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""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/action/signal_action.py

@@ -1,96 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `SignalAction`, a lightweight Falyx Action that raises a `FlowSignal`
-(such as `BackSignal`, `QuitSignal`, or `BreakChainSignal`) during execution to
-alter or exit the CLI flow.
-
-Unlike traditional actions, `SignalAction` does not return a result—instead, it raises
-a signal to break, back out, or exit gracefully. Despite its minimal behavior,
-it fully supports Falyx's hook lifecycle, including `before`, `on_error`, `after`,
-and `on_teardown`—allowing it to trigger logging, audit events, UI updates, or custom
-telemetry before halting flow.
-
-Key Features:
-- Declaratively raises a `FlowSignal` from within any Falyx workflow
-- Works in menus, chained actions, or conditionals
-- Hook-compatible: can run pre- and post-signal lifecycle hooks
-- Supports previewing and structured introspection
-
-Use Cases:
-- Implementing "Back", "Cancel", or "Quit" options in `MenuAction` or `PromptMenuAction`
-- Triggering an intentional early exit from a `ChainedAction`
-- Running cleanup hooks before stopping execution
-
-Example:
-    SignalAction("ExitApp", QuitSignal(), hooks=my_hook_manager)
-"""
-from rich.tree import Tree
-
-from falyx.action.action import Action
-from falyx.hook_manager import HookManager
-from falyx.signals import FlowSignal
-from falyx.themes import OneColors
-
-
-class SignalAction(Action):
-    """
-    A hook-compatible action that raises a control flow signal when invoked.
-
-    `SignalAction` raises a `FlowSignal` (e.g., `BackSignal`, `QuitSignal`,
-    `BreakChainSignal`) during execution. It is commonly used to exit menus,
-    break from chained actions, or halt workflows intentionally.
-
-    Even though the signal interrupts normal flow, all registered lifecycle hooks
-    (`before`, `on_error`, `after`, `on_teardown`) are triggered as expected—
-    allowing structured behavior such as logging, analytics, or UI changes
-    before the signal is raised.
-
-    Args:
-        name (str): Name of the action (used for logging and debugging).
-        signal (FlowSignal): A subclass of `FlowSignal` to raise (e.g., QuitSignal).
-        hooks (HookManager | None): Optional hook manager to attach lifecycle hooks.
-
-    Raises:
-        FlowSignal: Always raises the provided signal when the action is run.
-    """
-
-    def __init__(self, name: str, signal: FlowSignal, hooks: HookManager | None = None):
-        self.signal = signal
-        super().__init__(name, action=self.raise_signal, hooks=hooks)
-
-    async def raise_signal(self, *args, **kwargs):
-        """
-        Raises the configured `FlowSignal`.
-
-        This method is called internally by the Falyx runtime and is the core
-        behavior of the action. All hooks surrounding execution are still triggered.
-        """
-        raise self.signal
-
-    @property
-    def signal(self):
-        """Returns the configured `FlowSignal` instance."""
-        return self._signal
-
-    @signal.setter
-    def signal(self, value: FlowSignal):
-        """
-        Validates that the provided value is a `FlowSignal`.
-
-        Raises:
-            TypeError: If `value` is not an instance of `FlowSignal`.
-        """
-        if not isinstance(value, FlowSignal):
-            raise TypeError(
-                f"Signal must be an FlowSignal instance, got {type(value).__name__}"
-            )
-        self._signal = value
-
-    def __str__(self):
-        return f"SignalAction(name={self.name}, signal={self._signal.__class__.__name__})"
-
-    async def preview(self, parent: Tree | None = None):
-        label = f"[{OneColors.LIGHT_RED}]⚡ SignalAction[/] '{self.signal.__class__.__name__}'"
-        tree = parent.add(label) if parent else Tree(label)
-        if not parent:
-            self.console.print(tree)

falyx/action/user_input_action.py

@@ -1,136 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `UserInputAction`, a Falyx Action that prompts the user for input using
-Prompt Toolkit and returns the result as a string.
-
-This action is ideal for interactive CLI workflows that require user input mid-pipeline.
-It supports dynamic prompt interpolation, prompt validation, default text fallback,
-and full lifecycle hook execution.
-
-Key Features:
-- Rich Prompt Toolkit integration for input and validation
-- Dynamic prompt formatting using `last_result` injection
-- Optional `Validator` support for structured input (e.g., emails, numbers)
-- Hook lifecycle compatibility (before, on_success, on_error, after, teardown)
-- Preview support for introspection or dry-run flows
-
-Use Cases:
-- Asking for confirmation text or field input mid-chain
-- Injecting user-provided variables into automated pipelines
-- Interactive menu or wizard experiences
-
-Example:
-    UserInputAction(
-        name="GetUsername",
-        prompt_message="Enter your username > ",
-        validator=Validator.from_callable(lambda s: len(s) > 0),
-    )
-"""
-from prompt_toolkit import PromptSession
-from prompt_toolkit.validation import Validator
-from rich.tree import Tree
-
-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
-from falyx.prompt_utils import rich_text_to_prompt_text
-from falyx.signals import CancelSignal
-from falyx.themes.colors import OneColors
-
-
-class UserInputAction(BaseAction):
-    """
-    Prompts the user for textual input and returns their response.
-
-    `UserInputAction` uses Prompt Toolkit to gather input with optional validation,
-    lifecycle hook compatibility, and support for default text. If `inject_last_result`
-    is enabled, the prompt message can interpolate `{last_result}` dynamically.
-
-    Args:
-        name (str): Name of the action (used for introspection and logging).
-        prompt_message (str): The prompt message shown to the user.
-            Can include `{last_result}` if `inject_last_result=True`.
-        default_text (str): Optional default value shown in the prompt.
-        validator (Validator | None): Prompt Toolkit validator for input constraints.
-        prompt_session (PromptSession | None): Optional custom prompt session.
-        inject_last_result (bool): Whether to inject `last_result` into the prompt.
-    """
-
-    def __init__(
-        self,
-        name: str,
-        *,
-        prompt_message: str = "Input > ",
-        default_text: str = "",
-        multiline: bool = False,
-        validator: Validator | None = None,
-        prompt_session: PromptSession | None = None,
-        inject_last_result: bool = False,
-    ):
-        super().__init__(
-            name=name,
-            inject_last_result=inject_last_result,
-        )
-        self.prompt_message = prompt_message
-        self.default_text = default_text
-        self.multiline = multiline
-        self.validator = validator
-        self.prompt_session = prompt_session or PromptSession(
-            interrupt_exception=CancelSignal
-        )
-
-    def get_infer_target(self) -> tuple[None, None]:
-        return None, None
-
-    async def _run(self, *args, **kwargs) -> str:
-        context = ExecutionContext(
-            name=self.name,
-            args=args,
-            kwargs=kwargs,
-            action=self,
-        )
-        context.start_timer()
-        try:
-            await self.hooks.trigger(HookType.BEFORE, context)
-
-            prompt_message = self.prompt_message
-            if self.inject_last_result and self.last_result:
-                prompt_message = prompt_message.format(last_result=self.last_result)
-
-            answer = await self.prompt_session.prompt_async(
-                rich_text_to_prompt_text(prompt_message),
-                validator=self.validator,
-                default=kwargs.get("default_text", self.default_text),
-                multiline=self.multiline,
-            )
-            context.result = answer
-            await self.hooks.trigger(HookType.ON_SUCCESS, context)
-            return answer
-        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.MAGENTA}]⌨ UserInputAction[/] '{self.name}'"
-        tree = parent.add(label) if parent else Tree(label)
-
-        prompt_message = (
-            self.prompt_message.replace("{last_result}", "<last_result>")
-            if "{last_result}" in self.prompt_message
-            else self.prompt_message
-        )
-        tree.add(f"[dim]Prompt:[/] {prompt_message}")
-        if self.validator:
-            tree.add("[dim]Validator:[/] Yes")
-        if not parent:
-            self.console.print(tree)
-
-    def __str__(self):
-        return f"UserInputAction(name={self.name!r}, prompt={self.prompt!r})"

falyx/bottom_bar.py

@@ -1,50 +1,14 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""bottom_bar.py"""
-"""
-Provides the `BottomBar` class for managing a customizable bottom status bar in
-Falyx-based CLI applications.
-
-The bottom bar is rendered using `prompt_toolkit` and supports:
-- Rich-formatted static content
-- Live-updating value trackers and counters
-- Toggle switches activated via Ctrl+<key> bindings
-- Config-driven visual and behavioral controls
-
-Each item in the bar is registered by name and rendered in columns across the
-bottom of the terminal. Toggles are linked to user-defined state accessors and
-mutators, and can be automatically bound to `OptionsManager` values for full
-integration with Falyx CLI argument parsing.
-
-Key Features:
-- Live rendering of structured status items using Rich-style HTML
-- Custom or built-in item types: static text, dynamic counters, toggles, value displays
-- Ctrl+key toggle handling via `prompt_toolkit.KeyBindings`
-- Columnar layout with automatic width scaling
-- Optional integration with `OptionsManager` for dynamic state toggling
-
-Example:
-    ```
-    bar = BottomBar(columns=3)
-    bar.add_static("env", "ENV: dev")
-    bar.add_toggle("d", "Debug", get_debug, toggle_debug)
-    bar.add_value_tracker("attempts", "Retries", get_retry_count)
-    bar.render()
-    ```
-
-Used by Falyx to provide a persistent UI element showing toggles, system state,
-and runtime telemetry below the input prompt.
-"""
 
 from typing import Any, Callable
 
 from prompt_toolkit.formatted_text import HTML, merge_formatted_text
 from prompt_toolkit.key_binding import KeyBindings
-from prompt_toolkit.key_binding.key_processor import KeyPressEvent
 from rich.console import Console
 
-from falyx.console import console
 from falyx.options_manager import OptionsManager
-from falyx.themes import OneColors
+from falyx.themes.colors import OneColors
-from falyx.utils import CaseInsensitiveDict, chunks
+from falyx.utils import CaseInsensitiveDict
 
 
 class BottomBar:
@@ -58,19 +22,20 @@ class BottomBar:
             Must return True if key is available, otherwise False.
     """
 
-    RESERVED_CTRL_KEYS = {"c", "d", "z", "v"}
-
     def __init__(
         self,
         columns: int = 3,
         key_bindings: KeyBindings | None = None,
+        key_validator: Callable[[str], bool] | None = None,
     ) -> None:
         self.columns = columns
-        self.console: Console = console
+        self.console = Console()
+        self._items: list[Callable[[], HTML]] = []
         self._named_items: dict[str, Callable[[], HTML]] = {}
         self._value_getters: dict[str, Callable[[], Any]] = CaseInsensitiveDict()
         self.toggle_keys: list[str] = []
         self.key_bindings = key_bindings or KeyBindings()
+        self.key_validator = key_validator
 
     @staticmethod
     def default_render(label: str, value: Any, fg: str, bg: str, width: int) -> HTML:
@@ -80,7 +45,11 @@ class BottomBar:
     def space(self) -> int:
         return self.console.width // self.columns
 
-    def add_custom(self, name: str, render_fn: Callable[[], HTML]) -> None:
+    def add_custom(
+        self,
+        name: str,
+        render_fn: Callable[[], HTML]
+    ) -> None:
         """Add a custom render function to the bottom bar."""
         if not callable(render_fn):
             raise ValueError("`render_fn` must be callable")
@@ -94,7 +63,9 @@ class BottomBar:
         bg: str = OneColors.WHITE,
     ) -> None:
         def render():
-            return HTML(f"<style fg='{fg}' bg='{bg}'>{text:^{self.space}}</style>")
+            return HTML(
+                f"<style fg='{fg}' bg='{bg}'>{text:^{self.space}}</style>"
+            )
 
         self._add_named(name, render)
 
@@ -114,7 +85,9 @@ class BottomBar:
             get_value_ = self._value_getters[name]
             current_ = get_value_()
             text = f"{label}: {current_}"
-            return HTML(f"<style fg='{fg}' bg='{bg}'>{text:^{self.space}}</style>")
+            return HTML(
+                f"<style fg='{fg}' bg='{bg}'>{text:^{self.space}}</style>"
+            )
 
         self._add_named(name, render)
 
@@ -126,7 +99,6 @@ class BottomBar:
         total: int,
         fg: str = OneColors.BLACK,
         bg: str = OneColors.WHITE,
-        enforce_total: bool = True,
     ) -> None:
         if not callable(get_current):
             raise ValueError("`get_current` must be a callable returning int")
@@ -136,12 +108,14 @@ class BottomBar:
         def render():
             get_current_ = self._value_getters[name]
             current_value = get_current_()
-            if current_value > total and enforce_total:
+            if current_value > total:
                 raise ValueError(
                     f"Current value {current_value} is greater than total value {total}"
                 )
             text = f"{label}: {current_value}/{total}"
-            return HTML(f"<style fg='{fg}' bg='{bg}'>{text:^{self.space}}</style>")
+            return HTML(
+                f"<style fg='{fg}' bg='{bg}'>{text:^{self.space}}</style>"
+            )
 
         self._add_named(name, render)
 
@@ -155,31 +129,15 @@ class BottomBar:
         bg_on: str = OneColors.GREEN,
         bg_off: str = OneColors.DARK_RED,
     ) -> None:
-        """
-        Add a toggle to the bottom bar.
-        Always uses the ctrl + key combination for toggling.
-
-        Args:
-            key (str): The key to toggle the state.
-            label (str): The label for the toggle.
-            get_state (Callable[[], bool]): Function to get the current state.
-            toggle_state (Callable[[], None]): Function to toggle the state.
-            fg (str): Foreground color for the label.
-            bg_on (str): Background color when the toggle is ON.
-            bg_off (str): Background color when the toggle is OFF.
-        """
-        key = key.lower()
-        if key in self.RESERVED_CTRL_KEYS:
-            raise ValueError(
-                f"'{key}' is a reserved terminal control key and cannot be used for toggles."
-            )
         if not callable(get_state):
             raise ValueError("`get_state` must be a callable returning bool")
         if not callable(toggle_state):
             raise ValueError("`toggle_state` must be a callable")
+        key = key.upper()
         if key in self.toggle_keys:
             raise ValueError(f"Key {key} is already used as a toggle")
-
+        if self.key_validator and not self.key_validator(key):
+            raise ValueError(f"Key '{key}' conflicts with existing command, toggle, or reserved key.")
         self._value_getters[key] = get_state
         self.toggle_keys.append(key)
 
@@ -187,13 +145,17 @@ class BottomBar:
             get_state_ = self._value_getters[key]
             color = bg_on if get_state_() else bg_off
             status = "ON" if get_state_() else "OFF"
-            text = f"(^{key.lower()}) {label}: {status}"
+            text = f"({key.upper()}) {label}: {status}"
-            return HTML(f"<style bg='{color}' fg='{fg}'>{text:^{self.space}}</style>")
+            return HTML(
+                f"<style bg='{color}' fg='{fg}'>{text:^{self.space}}</style>"
+            )
 
         self._add_named(key, render)
 
-        @self.key_bindings.add(f"c-{key.lower()}", eager=True)
+        for k in (key.upper(), key.lower()):
-        def _(_: KeyPressEvent):
+
+            @self.key_bindings.add(k)
+            def _(event):
                 toggle_state()
 
     def add_toggle_from_option(
@@ -207,7 +169,6 @@ class BottomBar:
         bg_on: str = OneColors.GREEN,
         bg_off: str = OneColors.DARK_RED,
     ) -> None:
-        """Add a toggle to the bottom bar based on an option from OptionsManager."""
         self.add_toggle(
             key=key,
             label=label,
@@ -224,33 +185,15 @@ class BottomBar:
         return {label: getter() for label, getter in self._value_getters.items()}
 
     def get_value(self, name: str) -> Any:
-        """Get the current value of a registered item."""
         if name not in self._value_getters:
             raise ValueError(f"No value getter registered under name: '{name}'")
         return self._value_getters[name]()
 
-    def remove_item(self, name: str) -> None:
-        """Remove an item from the bottom bar."""
-        self._named_items.pop(name, None)
-        self._value_getters.pop(name, None)
-        if name in self.toggle_keys:
-            self.toggle_keys.remove(name)
-
-    def clear(self) -> None:
-        """Clear all items from the bottom bar."""
-        self._value_getters.clear()
-        self._named_items.clear()
-        self.toggle_keys.clear()
-
     def _add_named(self, name: str, render_fn: Callable[[], HTML]) -> None:
         if name in self._named_items:
             raise ValueError(f"Bottom bar item '{name}' already exists")
         self._named_items[name] = render_fn
+        self._items = list(self._named_items.values())
 
     def render(self):
-        """Render the bottom bar."""
+        return merge_formatted_text([fn() for fn in self._items])
-        lines = []
-        for chunk in chunks(self._named_items.values(), self.columns):
-            lines.extend(list(chunk))
-            lines.append(lambda: HTML("\n"))
-        return merge_formatted_text([fn() for fn in lines[:-1]])

falyx/command.py

@@ -1,124 +1,43 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""command.py
-"""
+Any Action or Command is callable and supports the signature:
-Defines the Command class for Falyx CLI.
+    result = thing(*args, **kwargs)
 
-Commands are callable units representing a menu option or CLI task,
+This guarantees:
-wrapping either a BaseAction or a simple function. They provide:
+- Hook lifecycle (before/after/error/teardown)
-
+- Timing
-- Hook lifecycle (before, on_success, on_error, after, on_teardown)
+- Consistent return values
-- Execution timing and duration tracking
-- Retry logic (single action or recursively through action trees)
-- Confirmation prompts and spinner integration
-- Result capturing and summary logging
-- Rich-based preview for CLI display
-
-Every Command is self-contained, configurable, and plays a critical role
-in building robust interactive menus.
 """
 from __future__ import annotations
 
-import shlex
+from typing import Any, Callable
-from typing import Any, Awaitable, Callable
 
 from prompt_toolkit.formatted_text import FormattedText
 from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator
+from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action.action import Action
+from falyx.action import Action, BaseAction
-from falyx.action.base_action import BaseAction
-from falyx.console import console
 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.mode import FalyxMode
-from falyx.options_manager import OptionsManager
-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
 from falyx.retry import RetryPolicy
-from falyx.retry_utils import enable_retries_recursively
+from falyx.themes.colors import OneColors
-from falyx.signals import CancelSignal
+from falyx.utils import _noop, ensure_async, logger
-from falyx.themes import OneColors
+
-from falyx.utils import ensure_async
+console = Console()
 
 
 class Command(BaseModel):
-    """
+    """Class representing an command in the menu."""
-    Represents a selectable command in a Falyx menu system.
-
-    A Command wraps an executable action (function, coroutine, or BaseAction)
-    and enhances it with:
-
-    - Lifecycle hooks (before, success, error, after, teardown)
-    - Retry support (single action or recursive for chained/grouped actions)
-    - Confirmation prompts for safe execution
-    - Spinner visuals during execution
-    - Tagging for categorization and filtering
-    - Rich-based CLI previews
-    - Result tracking and summary reporting
-
-    Commands are built to be flexible yet robust, enabling dynamic CLI workflows
-    without sacrificing control or reliability.
-
-    Attributes:
-        key (str): Primary trigger key for the command.
-        description (str): Short description for the menu display.
-        hidden (bool): Toggles visibility in the menu.
-        aliases (list[str]): Alternate keys or phrases.
-        action (BaseAction | Callable): The executable logic.
-        args (tuple): Static positional arguments.
-        kwargs (dict): Static keyword arguments.
-        help_text (str): Additional help or guidance text.
-        style (str): Rich style for description.
-        confirm (bool): Whether to require confirmation before executing.
-        confirm_message (str): Custom confirmation prompt.
-        preview_before_confirm (bool): Whether to preview before confirming.
-        spinner (bool): Whether to show a spinner during execution.
-        spinner_message (str): Spinner text message.
-        spinner_type (str): Spinner style (e.g., dots, line, etc.).
-        spinner_style (str): Color or style of the spinner.
-        spinner_speed (float): Speed of the spinner animation.
-        hooks (HookManager): Hook manager for lifecycle events.
-        retry (bool): Enable retry on failure.
-        retry_all (bool): Enable retry across chained or grouped actions.
-        retry_policy (RetryPolicy): Retry behavior configuration.
-        tags (list[str]): Organizational tags for the command.
-        logging_hooks (bool): Whether to attach logging hooks automatically.
-        options_manager (OptionsManager): Manages global command-line options.
-        arg_parser (CommandArgumentParser): Parses command arguments.
-        arguments (list[dict[str, Any]]): Argument definitions for the command.
-        argument_config (Callable[[CommandArgumentParser], None] | None): Function to configure arguments
-            for the command parser.
-        custom_parser (ArgParserProtocol | None): Custom argument parser.
-        custom_help (Callable[[], str | None] | None): Custom help message generator.
-        auto_args (bool): Automatically infer arguments from the action.
-        arg_metadata (dict[str, str | dict[str, Any]]): Metadata for arguments,
-            such as help text or choices.
-        simple_help_signature (bool): Whether to use a simplified help signature.
-        ignore_in_history (bool): Whether to ignore this command in execution history last result.
-        program: (str | None): The parent program name.
-
-    Methods:
-        __call__(): Executes the command, respecting hooks and retries.
-        preview(): Rich tree preview of the command.
-        confirmation_prompt(): Formatted prompt for confirmation.
-        result: Property exposing the last result.
-        log_summary(): Summarizes execution details to the console.
-    """
-
     key: str
     description: str
-    action: BaseAction | Callable[..., Any] | Callable[..., Awaitable[Any]]
+    aliases: list[str] = Field(default_factory=list)
+    action: BaseAction | Callable[[], Any] = _noop
     args: tuple = ()
     kwargs: dict[str, Any] = Field(default_factory=dict)
-    hidden: bool = False
-    aliases: list[str] = Field(default_factory=list)
     help_text: str = ""
-    help_epilog: str = ""
+    color: str = OneColors.WHITE
-    style: str = OneColors.WHITE
     confirm: bool = False
     confirm_message: str = "Are you sure?"
     preview_before_confirm: bool = True
@@ -126,64 +45,31 @@ class Command(BaseModel):
     spinner_message: str = "Processing..."
     spinner_type: str = "dots"
     spinner_style: str = OneColors.CYAN
-    spinner_speed: float = 1.0
+    spinner_kwargs: dict[str, Any] = Field(default_factory=dict)
     hooks: "HookManager" = Field(default_factory=HookManager)
     retry: bool = False
     retry_all: bool = False
     retry_policy: RetryPolicy = Field(default_factory=RetryPolicy)
     tags: list[str] = Field(default_factory=list)
     logging_hooks: bool = False
-    options_manager: OptionsManager = Field(default_factory=OptionsManager)
-    arg_parser: CommandArgumentParser | None = None
-    arguments: list[dict[str, Any]] = Field(default_factory=list)
-    argument_config: Callable[[CommandArgumentParser], None] | None = None
-    custom_parser: ArgParserProtocol | None = None
-    custom_help: Callable[[], str | None] | None = None
-    auto_args: bool = True
-    arg_metadata: dict[str, str | dict[str, Any]] = Field(default_factory=dict)
-    simple_help_signature: bool = False
-    ignore_in_history: bool = False
-    program: str | None = None
 
     _context: ExecutionContext | None = PrivateAttr(default=None)
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    async def parse_args(
+    def model_post_init(self, __context: Any) -> None:
-        self, raw_args: list[str] | str, from_validate: bool = False
+        """Post-initialization to set up the action and hooks."""
-    ) -> tuple[tuple, dict]:
+        if self.retry and isinstance(self.action, Action):
-        if callable(self.custom_parser):
+            self.action.enable_retry()
-            if isinstance(raw_args, str):
+        elif self.retry_policy and isinstance(self.action, Action):
-                try:
+            self.action.set_retry_policy(self.retry_policy)
-                    raw_args = shlex.split(raw_args)
+        elif self.retry:
-                except ValueError:
+            logger.warning(f"[Command:{self.key}] Retry requested, but action is not an Action instance.")
-                    logger.warning(
+        if self.retry_all:
-                        "[Command:%s] Failed to split arguments: %s",
+            self.action.enable_retries_recursively(self.action, self.retry_policy)
-                        self.key,
-                        raw_args,
-                    )
-                    return ((), {})
-            return self.custom_parser(raw_args)
 
-        if isinstance(raw_args, str):
+        if self.logging_hooks and isinstance(self.action, BaseAction):
-            try:
+            register_debug_hooks(self.action.hooks)
-                raw_args = shlex.split(raw_args)
-            except ValueError:
-                logger.warning(
-                    "[Command:%s] Failed to split arguments: %s",
-                    self.key,
-                    raw_args,
-                )
-                return ((), {})
-        if not isinstance(self.arg_parser, CommandArgumentParser):
-            logger.warning(
-                "[Command:%s] No argument parser configured, using default parsing.",
-                self.key,
-            )
-            return ((), {})
-        return await self.arg_parser.parse_args_split(
-            raw_args, from_validate=from_validate
-        )
 
     @field_validator("action", mode="before")
     @classmethod
@@ -194,75 +80,11 @@ class Command(BaseModel):
             return ensure_async(action)
         raise TypeError("Action must be a callable or an instance of BaseAction")
 
-    def get_argument_definitions(self) -> list[dict[str, Any]]:
+    def __str__(self):
-        if self.arguments:
+        return f"Command(key='{self.key}', description='{self.description}')"
-            return self.arguments
-        elif callable(self.argument_config) and isinstance(
-            self.arg_parser, CommandArgumentParser
-        ):
-            self.argument_config(self.arg_parser)
-        elif self.auto_args:
-            if isinstance(self.action, BaseAction):
-                infer_target, maybe_metadata = self.action.get_infer_target()
-                # merge metadata with the action's metadata if not already in self.arg_metadata
-                if maybe_metadata:
-                    self.arg_metadata = {**maybe_metadata, **self.arg_metadata}
-                return infer_args_from_func(infer_target, self.arg_metadata)
-            elif callable(self.action):
-                return infer_args_from_func(self.action, self.arg_metadata)
-        return []
 
-    def model_post_init(self, _: Any) -> None:
+    async def __call__(self, *args, **kwargs):
-        """Post-initialization to set up the action and hooks."""
+        """Run the action with full hook lifecycle, timing, and error handling."""
-        if self.retry and isinstance(self.action, Action):
-            self.action.enable_retry()
-        elif self.retry_policy and isinstance(self.action, Action):
-            self.action.set_retry_policy(self.retry_policy)
-        elif self.retry:
-            logger.warning(
-                "[Command:%s] Retry requested, but action is not an Action instance.",
-                self.key,
-            )
-        if self.retry_all and isinstance(self.action, BaseAction):
-            self.retry_policy.enabled = True
-            enable_retries_recursively(self.action, self.retry_policy)
-        elif self.retry_all:
-            logger.warning(
-                "[Command:%s] Retry all requested, but action is not a BaseAction.",
-                self.key,
-            )
-
-        if self.logging_hooks and isinstance(self.action, BaseAction):
-            register_debug_hooks(self.action.hooks)
-
-        if self.arg_parser is None and not self.custom_parser:
-            self.arg_parser = CommandArgumentParser(
-                command_key=self.key,
-                command_description=self.description,
-                command_style=self.style,
-                help_text=self.help_text,
-                help_epilog=self.help_epilog,
-                aliases=self.aliases,
-                program=self.program,
-                options_manager=self.options_manager,
-            )
-            for arg_def in self.get_argument_definitions():
-                self.arg_parser.add_argument(*arg_def.pop("flags"), **arg_def)
-
-        if self.ignore_in_history and isinstance(self.action, BaseAction):
-            self.action.ignore_in_history = True
-
-    def _inject_options_manager(self) -> None:
-        """Inject the options manager into the action if applicable."""
-        if isinstance(self.action, BaseAction):
-            self.action.set_options_manager(self.options_manager)
-
-    async def __call__(self, *args, **kwargs) -> Any:
-        """
-        Run the action with full hook lifecycle, timing, error handling,
-        confirmation prompts, preview, and spinner integration.
-        """
-        self._inject_options_manager()
         combined_args = args + self.args
         combined_kwargs = {**self.kwargs, **kwargs}
         context = ExecutionContext(
@@ -272,26 +94,20 @@ class Command(BaseModel):
             action=self,
         )
         self._context = context
-
-        if should_prompt_user(confirm=self.confirm, options=self.options_manager):
-            if self.preview_before_confirm:
-                await self.preview()
-            if not await confirm_async(self.confirmation_prompt):
-                logger.info("[Command:%s] Cancelled by user.", self.key)
-                raise CancelSignal(f"[Command:{self.key}] Cancelled by confirmation.")
-
         context.start_timer()
 
         try:
             await self.hooks.trigger(HookType.BEFORE, context)
             result = await self.action(*combined_args, **combined_kwargs)
-
             context.result = result
             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)
+            if context.result is not None:
+                logger.info(f"✅ Recovered: {self.key}")
+                return context.result
             raise error
         finally:
             context.stop_timer()
@@ -308,7 +124,9 @@ class Command(BaseModel):
     def confirmation_prompt(self) -> FormattedText:
         """Generate a styled prompt_toolkit FormattedText confirmation message."""
         if self.confirm_message and self.confirm_message != "Are you sure?":
-            return FormattedText([("class:confirm", self.confirm_message)])
+            return FormattedText([
+                ("class:confirm", self.confirm_message)
+            ])
 
         action_name = getattr(self.action, "__name__", None)
         if isinstance(self.action, BaseAction):
@@ -323,95 +141,27 @@ class Command(BaseModel):
             prompt.append(("class:confirm", f"(calls `{action_name}`) "))
 
         if self.args or self.kwargs:
-            prompt.append(
+            prompt.append((OneColors.DARK_YELLOW, f"with args={self.args}, kwargs={self.kwargs} "))
-                (OneColors.DARK_YELLOW, f"with args={self.args}, kwargs={self.kwargs} ")
-            )
 
         return FormattedText(prompt)
 
-    @property
+    def log_summary(self):
-    def usage(self) -> str:
-        """Generate a help string for the command arguments."""
-        if not self.arg_parser:
-            return "No arguments defined."
-
-        command_keys_text = self.arg_parser.get_command_keys_text(plain_text=True)
-        options_text = self.arg_parser.get_options_text(plain_text=True)
-        return f"  {command_keys_text:<20}  {options_text} "
-
-    @property
-    def help_signature(self) -> tuple[str, str, str]:
-        """Generate a help signature for the command."""
-        is_cli_mode = self.options_manager.get("mode") in {
-            FalyxMode.RUN,
-            FalyxMode.PREVIEW,
-            FalyxMode.RUN_ALL,
-        }
-
-        program = f"{self.program} run " if is_cli_mode else ""
-
-        if self.arg_parser and not self.simple_help_signature:
-            usage = f"[{self.style}]{program}[/]{self.arg_parser.get_usage()}"
-            description = f"[dim]{self.help_text or self.description}[/dim]"
-            if self.tags:
-                tags = f"[dim]Tags: {', '.join(self.tags)}[/dim]"
-            else:
-                tags = ""
-            return usage, description, tags
-
-        command_keys = " | ".join(
-            [f"[{self.style}]{self.key}[/{self.style}]"]
-            + [f"[{self.style}]{alias}[/{self.style}]" for alias in self.aliases]
-        )
-        return (
-            f"[{self.style}]{program}[/]{command_keys}",
-            f"[dim]{self.description}[/dim]",
-            "",
-        )
-
-    def log_summary(self) -> None:
         if self._context:
             self._context.log_summary()
 
-    def render_help(self) -> bool:
+    async def preview(self):
-        """Display the help message for the command."""
-        if callable(self.custom_help):
-            output = self.custom_help()
-            if output:
-                console.print(output)
-            return True
-        if isinstance(self.arg_parser, CommandArgumentParser):
-            self.arg_parser.render_help()
-            return True
-        return False
-
-    async def preview(self) -> None:
         label = f"[{OneColors.GREEN_b}]Command:[/] '{self.key}' — {self.description}"
 
         if hasattr(self.action, "preview") and callable(self.action.preview):
             tree = Tree(label)
             await self.action.preview(parent=tree)
-            if self.help_text:
-                tree.add(f"[dim]💡 {self.help_text}[/dim]")
             console.print(tree)
-        elif callable(self.action) and not isinstance(self.action, BaseAction):
+        elif callable(self.action):
             console.print(f"{label}")
-            if self.help_text:
-                console.print(f"[dim]💡 {self.help_text}[/dim]")
             console.print(
-                f"[{OneColors.LIGHT_RED_b}]→ Would call:[/] {self.action.__name__}"
+                f"[{OneColors.LIGHT_RED_b}]→ Would call:[/] {self.action.__name__} "
                 f"[dim](args={self.args}, kwargs={self.kwargs})[/dim]"
             )
         else:
             console.print(f"{label}")
-            if self.help_text:
+            console.print(f"[{OneColors.DARK_RED}]⚠️ Action is not callable or lacks a preview method.[/]")
-                console.print(f"[dim]💡 {self.help_text}[/dim]")
-            console.print(
-                f"[{OneColors.DARK_RED}]⚠️ No preview available for this action.[/]"
-            )
-
-    def __str__(self) -> str:
-        return (
-            f"Command(key='{self.key}', description='{self.description}' "
-            f"action='{self.action}')"
-        )

falyx/completer.py

@@ -1,159 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Provides `FalyxCompleter`, an intelligent autocompletion engine for Falyx CLI
-menus using Prompt Toolkit.
-
-This completer supports:
-- Command key and alias completion (e.g. `R`, `HELP`, `X`)
-- Argument flag completion for registered commands (e.g. `--tag`, `--name`)
-- Context-aware suggestions based on cursor position and argument structure
-- Interactive value completions (e.g. choices and suggestions defined per argument)
-
-Completions are sourced from `CommandArgumentParser.suggest_next`, which analyzes
-parsed tokens to determine appropriate next arguments, flags, or values.
-
-Integrated with the `Falyx.prompt_session` to enhance the interactive experience.
-"""
-
-from __future__ import annotations
-
-import os
-import shlex
-from typing import TYPE_CHECKING, Iterable
-
-from prompt_toolkit.completion import Completer, Completion
-from prompt_toolkit.document import Document
-
-if TYPE_CHECKING:
-    from falyx import Falyx
-
-
-class FalyxCompleter(Completer):
-    """
-    Prompt Toolkit completer for Falyx CLI command input.
-
-    This completer provides real-time, context-aware suggestions for:
-    - Command keys and aliases (resolved via Falyx._name_map)
-    - CLI argument flags and values for each command
-    - Suggestions and choices defined in the associated CommandArgumentParser
-
-    It leverages `CommandArgumentParser.suggest_next()` to compute valid completions
-    based on current argument state, including:
-        - Remaining required or optional flags
-        - Flag value suggestions (choices or custom completions)
-        - Next positional argument hints
-
-    Args:
-        falyx (Falyx): The Falyx menu instance containing all command mappings and parsers.
-    """
-
-    def __init__(self, falyx: "Falyx"):
-        self.falyx = falyx
-
-    def get_completions(self, document: Document, complete_event) -> Iterable[Completion]:
-        """
-        Yield completions based on the current document input.
-
-        Args:
-            document (Document): The prompt_toolkit document containing the input buffer.
-            complete_event: The completion trigger event (unused).
-
-        Yields:
-            Completion objects matching command keys or argument suggestions.
-        """
-        text = document.text_before_cursor
-        try:
-            tokens = shlex.split(text)
-            cursor_at_end_of_token = document.text_before_cursor.endswith((" ", "\t"))
-        except ValueError:
-            return
-
-        if not tokens or (len(tokens) == 1 and not cursor_at_end_of_token):
-            # Suggest command keys and aliases
-            stub = tokens[0] if tokens else ""
-            suggestions = [c.text for c in self._suggest_commands(stub)]
-            yield from self._yield_lcp_completions(suggestions, stub)
-            return
-
-        # Identify command
-        command_key = tokens[0].upper()
-        command = self.falyx._name_map.get(command_key)
-        if not command or not command.arg_parser:
-            return
-
-        # If at end of token, e.g., "--t" vs "--tag ", add a stub so suggest_next sees it
-        parsed_args = tokens[1:] if cursor_at_end_of_token else tokens[1:-1]
-        stub = "" if cursor_at_end_of_token else tokens[-1]
-
-        try:
-            suggestions = command.arg_parser.suggest_next(
-                parsed_args + ([stub] if stub else []), cursor_at_end_of_token
-            )
-            yield from self._yield_lcp_completions(suggestions, stub)
-        except Exception:
-            return
-
-    def _suggest_commands(self, prefix: str) -> Iterable[Completion]:
-        """
-        Suggest top-level command keys and aliases based on the given prefix.
-
-        Args:
-            prefix (str): The user input to match against available commands.
-
-        Yields:
-            Completion: Matching keys or aliases from all registered commands.
-        """
-        prefix = prefix.upper()
-        keys = [self.falyx.exit_command.key]
-        keys.extend(self.falyx.exit_command.aliases)
-        if self.falyx.history_command:
-            keys.append(self.falyx.history_command.key)
-            keys.extend(self.falyx.history_command.aliases)
-        if self.falyx.help_command:
-            keys.append(self.falyx.help_command.key)
-            keys.extend(self.falyx.help_command.aliases)
-        for cmd in self.falyx.commands.values():
-            keys.append(cmd.key)
-            keys.extend(cmd.aliases)
-        for key in keys:
-            if key.upper().startswith(prefix):
-                yield Completion(key, start_position=-len(prefix))
-
-    def _ensure_quote(self, text: str) -> str:
-        """
-        Ensure the text is properly quoted for shell commands.
-
-        Args:
-            text (str): The input text to quote.
-
-        Returns:
-            str: The quoted text, suitable for shell command usage.
-        """
-        if " " in text or "\t" in text:
-            return f'"{text}"'
-        return text
-
-    def _yield_lcp_completions(self, suggestions, stub):
-        matches = [s for s in suggestions if s.startswith(stub)]
-        if not matches:
-            return
-
-        lcp = os.path.commonprefix(matches)
-
-        if len(matches) == 1:
-            yield Completion(
-                self._ensure_quote(matches[0]),
-                start_position=-len(stub),
-                display=matches[0],
-            )
-        elif len(lcp) > len(stub) and not lcp.startswith("-"):
-            yield Completion(lcp, start_position=-len(stub), display=lcp)
-            for match in matches:
-                yield Completion(
-                    self._ensure_quote(match), start_position=-len(stub), display=match
-                )
-        else:
-            for match in matches:
-                yield Completion(
-                    self._ensure_quote(match), start_position=-len(stub), display=match
-                )

falyx/config.py

@@ -1,60 +1,16 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""config.py
-"""
+Configuration loader for Falyx CLI commands."""
-Configuration loader and schema definitions for the Falyx CLI framework.
-
-This module supports config-driven initialization of CLI commands and submenus
-from YAML or TOML files. It enables declarative command definitions, auto-imports
-Python callables from dotted paths, and wraps them in `Action` or `Command` objects
-as needed.
-
-Features:
-- Parses Falyx command and submenu definitions from YAML or TOML.
-- Supports hooks, retry policies, confirm prompts, spinners, aliases, and tags.
-- Dynamically imports Python functions/classes from `action:` strings.
-- Wraps user callables into Falyx `Command` or `Action` instances.
-- Validates prompt and retry configuration using `pydantic` models.
-
-Main Components:
-- `FalyxConfig`: Pydantic model for top-level config structure.
-- `RawCommand`: Intermediate command definition model from raw config.
-- `Submenu`: Schema for nested CLI menus.
-- `loader(path)`: Loads and returns a fully constructed `Falyx` instance.
-
-Typical Config (YAML):
-```yaml
-title: My CLI
-commands:
-  - key: A
-    description: Say hello
-    action: my_package.tasks.hello
-    aliases: [hi]
-    tags: [example]
-```
-
-Example:
-    from falyx.config import loader
-    cli = loader("falyx.yaml")
-    cli.run()
-"""
-from __future__ import annotations
 
 import importlib
-import sys
 from pathlib import Path
-from typing import Any, Callable
+from typing import Any
 
 import toml
 import yaml
-from pydantic import BaseModel, Field, field_validator, model_validator
 
-from falyx.action.action import Action
+from falyx.action import Action, BaseAction
-from falyx.action.base_action import BaseAction
 from falyx.command import Command
-from falyx.console import console
-from falyx.falyx import Falyx
-from falyx.logger import logger
 from falyx.retry import RetryPolicy
-from falyx.themes import OneColors
 
 
 def wrap_if_needed(obj: Any, name=None) -> BaseAction | Command:
@@ -64,8 +20,8 @@ def wrap_if_needed(obj: Any, name=None) -> BaseAction | Command:
         return Action(name=name or getattr(obj, "__name__", "unnamed"), action=obj)
     else:
         raise TypeError(
-            f"Cannot wrap object of type '{type(obj).__name__}'. "
+            f"Cannot wrap object of type '{type(obj).__name__}' as a BaseAction or Command. "
-            "Expected a function or BaseAction."
+            "It must be a callable or an instance of BaseAction."
         )
 
 
@@ -73,193 +29,14 @@ def import_action(dotted_path: str) -> Any:
     """Dynamically imports a callable from a dotted path like 'my.module.func'."""
     module_path, _, attr = dotted_path.rpartition(".")
     if not module_path:
-        console.print(f"[{OneColors.DARK_RED}]❌ Invalid action path:[/] {dotted_path}")
+        raise ValueError(f"Invalid action path: {dotted_path}")
-        sys.exit(1)
-    try:
     module = importlib.import_module(module_path)
-    except ModuleNotFoundError as error:
+    return getattr(module, attr)
-        logger.error("Failed to import module '%s': %s", module_path, error)
-        console.print(
-            f"[{OneColors.DARK_RED}]❌ Could not import '{dotted_path}': {error}[/]\n"
-            f"[{OneColors.COMMENT_GREY}]Ensure the module is installed and discoverable "
-            "via PYTHONPATH."
-        )
-        sys.exit(1)
-    try:
-        action = getattr(module, attr)
-    except AttributeError as error:
-        logger.error(
-            "Module '%s' does not have attribute '%s': %s", module_path, attr, error
-        )
-        console.print(
-            f"[{OneColors.DARK_RED}]❌ Module '{module_path}' has no attribute "
-            f"'{attr}': {error}[/]"
-        )
-        sys.exit(1)
-    return action
 
 
-class RawCommand(BaseModel):
+def loader(file_path: str) -> list[dict[str, Any]]:
-    """Raw command model for Falyx CLI configuration."""
-
-    key: str
-    description: str
-    action: str
-
-    args: tuple[Any, ...] = Field(default_factory=tuple)
-    kwargs: dict[str, Any] = Field(default_factory=dict)
-    aliases: list[str] = Field(default_factory=list)
-    tags: list[str] = Field(default_factory=list)
-    style: str = OneColors.WHITE
-
-    confirm: bool = False
-    confirm_message: str = "Are you sure?"
-    preview_before_confirm: bool = True
-
-    spinner: bool = False
-    spinner_message: str = "Processing..."
-    spinner_type: str = "dots"
-    spinner_style: str = OneColors.CYAN
-    spinner_speed: float = 1.0
-
-    before_hooks: list[Callable] = Field(default_factory=list)
-    success_hooks: list[Callable] = Field(default_factory=list)
-    error_hooks: list[Callable] = Field(default_factory=list)
-    after_hooks: list[Callable] = Field(default_factory=list)
-    teardown_hooks: list[Callable] = Field(default_factory=list)
-
-    logging_hooks: bool = False
-    retry: bool = False
-    retry_all: bool = False
-    retry_policy: RetryPolicy = Field(default_factory=RetryPolicy)
-    hidden: bool = False
-    help_text: str = ""
-    help_epilog: str = ""
-
-    @field_validator("retry_policy")
-    @classmethod
-    def validate_retry_policy(cls, value: dict | RetryPolicy) -> RetryPolicy:
-        if isinstance(value, RetryPolicy):
-            return value
-        if not isinstance(value, dict):
-            raise ValueError("retry_policy must be a dictionary.")
-        return RetryPolicy(**value)
-
-
-def convert_commands(raw_commands: list[dict[str, Any]]) -> list[Command]:
-    commands = []
-    for entry in raw_commands:
-        raw_command = RawCommand(**entry)
-        commands.append(
-            Command.model_validate(
-                {
-                    **raw_command.model_dump(exclude={"action"}),
-                    "action": wrap_if_needed(
-                        import_action(raw_command.action), name=raw_command.description
-                    ),
-                }
-            )
-        )
-
-    return commands
-
-
-def convert_submenus(
-    raw_submenus: list[dict[str, Any]], *, parent_path: Path | None = None, depth: int = 0
-) -> list[dict[str, Any]]:
-    submenus: list[dict[str, Any]] = []
-    for raw_submenu in raw_submenus:
-        if raw_submenu.get("config"):
-            config_path = Path(raw_submenu["config"])
-            if parent_path:
-                config_path = (parent_path.parent / config_path).resolve()
-            submenu = loader(config_path, _depth=depth + 1)
-        else:
-            submenu_module_path = raw_submenu.get("submenu")
-            if not isinstance(submenu_module_path, str):
-                console.print(
-                    f"[{OneColors.DARK_RED}]❌ Invalid submenu path:[/] {submenu_module_path}"
-                )
-                sys.exit(1)
-            submenu = import_action(submenu_module_path)
-        if not isinstance(submenu, Falyx):
-            console.print(f"[{OneColors.DARK_RED}]❌ Invalid submenu:[/] {submenu}")
-            sys.exit(1)
-
-        key = raw_submenu.get("key")
-        if not isinstance(key, str):
-            console.print(f"[{OneColors.DARK_RED}]❌ Invalid submenu key:[/] {key}")
-            sys.exit(1)
-
-        description = raw_submenu.get("description")
-        if not isinstance(description, str):
-            console.print(
-                f"[{OneColors.DARK_RED}]❌ Invalid submenu description:[/] {description}"
-            )
-            sys.exit(1)
-
-        submenus.append(
-            Submenu(
-                key=key,
-                description=description,
-                submenu=submenu,
-                style=raw_submenu.get("style", OneColors.CYAN),
-            ).model_dump()
-        )
-    return submenus
-
-
-class Submenu(BaseModel):
-    """Submenu model for Falyx CLI configuration."""
-
-    key: str
-    description: str
-    submenu: Any
-    style: str = OneColors.CYAN
-
-
-class FalyxConfig(BaseModel):
-    """Falyx CLI configuration model."""
-
-    title: str = "Falyx CLI"
-    prompt: str | list[tuple[str, str]] | list[list[str]] = [
-        (OneColors.BLUE_b, "FALYX > ")
-    ]
-    columns: int = 4
-    welcome_message: str = ""
-    exit_message: str = ""
-    commands: list[Command] | list[dict] = []
-    submenus: list[dict[str, Any]] = []
-
-    @model_validator(mode="after")
-    def validate_prompt_format(self) -> FalyxConfig:
-        if isinstance(self.prompt, list):
-            for pair in self.prompt:
-                if not isinstance(pair, (list, tuple)) or len(pair) != 2:
-                    raise ValueError(
-                        "Prompt list must contain 2-element (style, text) pairs"
-                    )
-        return self
-
-    def to_falyx(self) -> Falyx:
-        flx = Falyx(
-            title=self.title,
-            prompt=self.prompt,  # type: ignore[arg-type]
-            columns=self.columns,
-            welcome_message=self.welcome_message,
-            exit_message=self.exit_message,
-        )
-        flx.add_commands(self.commands)
-        for submenu in self.submenus:
-            flx.add_submenu(**submenu)
-        return flx
-
-
-def loader(file_path: Path | str, _depth: int = 0) -> Falyx:
     """
-    Load Falyx CLI configuration from a YAML or TOML file.
+    Load command definitions from a YAML or TOML file.
-
-    The file should contain a dictionary with a list of commands.
 
     Each command should be defined as a dictionary with at least:
     - key: a unique single-character key
@@ -270,19 +47,12 @@ def loader(file_path: Path | str, _depth: int = 0) -> Falyx:
         file_path (str): Path to the config file (YAML or TOML).
 
     Returns:
-        Falyx: An instance of the Falyx CLI with loaded commands.
+        list[dict[str, Any]]: A list of command configuration dictionaries.
 
     Raises:
         ValueError: If the file format is unsupported or file cannot be parsed.
     """
-    if _depth > 5:
-        raise ValueError("Maximum submenu depth exceeded (5 levels deep)")
-
-    if isinstance(file_path, (str, Path)):
     path = Path(file_path)
-    else:
-        raise TypeError("file_path must be a string or Path object.")
-
     if not path.is_file():
         raise FileNotFoundError(f"No such config file: {file_path}")
 
@@ -295,25 +65,39 @@ def loader(file_path: Path | str, _depth: int = 0) -> Falyx:
         else:
             raise ValueError(f"Unsupported config format: {suffix}")
 
-    if not isinstance(raw_config, dict):
+    if not isinstance(raw_config, list):
-        raise ValueError(
+        raise ValueError("Configuration file must contain a list of command definitions.")
-            "Configuration file must contain a dictionary with a list of commands.\n"
+
-            "Example:\n"
+
-            "title: 'My CLI'\n"
+    required = ["key", "description", "action"]
-            "commands:\n"
+    commands = []
-            "  - key: 'a'\n"
+    for entry in raw_config:
-            "    description: 'Example command'\n"
+        for field in required:
-            "    action: 'my_module.my_function'"
+            if field not in entry:
-        )
+                raise ValueError(f"Missing '{field}' in command entry: {entry}")
+
+        command_dict = {
+            "key": entry["key"],
+            "description": entry["description"],
+            "aliases": entry.get("aliases", []),
+            "action": wrap_if_needed(import_action(entry["action"]),
+                                     name=entry["description"]),
+            "args": tuple(entry.get("args", ())),
+            "kwargs": entry.get("kwargs", {}),
+            "help_text": entry.get("help_text", ""),
+            "color": entry.get("color", "white"),
+            "confirm": entry.get("confirm", False),
+            "confirm_message": entry.get("confirm_message", "Are you sure?"),
+            "preview_before_confirm": entry.get("preview_before_confirm", True),
+            "spinner": entry.get("spinner", False),
+            "spinner_message": entry.get("spinner_message", "Processing..."),
+            "spinner_type": entry.get("spinner_type", "dots"),
+            "spinner_style": entry.get("spinner_style", "cyan"),
+            "spinner_kwargs": entry.get("spinner_kwargs", {}),
+            "tags": entry.get("tags", []),
+            "retry_policy": RetryPolicy(**entry.get("retry_policy", {})),
+        }
+        commands.append(command_dict)
+
+    return commands
 
-    commands = convert_commands(raw_config["commands"])
-    submenus = convert_submenus(raw_config.get("submenus", []))
-    return FalyxConfig(
-        title=raw_config.get("title", f"[{OneColors.BLUE_b}]Falyx CLI"),
-        prompt=raw_config.get("prompt", [(OneColors.BLUE_b, "FALYX > ")]),
-        columns=raw_config.get("columns", 4),
-        welcome_message=raw_config.get("welcome_message", ""),
-        exit_message=raw_config.get("exit_message", ""),
-        commands=commands,
-        submenus=submenus,
-    ).to_falyx()

falyx/console.py

@@ -1,7 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""Global console instance for Falyx CLI applications."""
-from rich.console import Console
-
-from falyx.themes import get_nord_theme
-
-console = Console(color_system="truecolor", theme=get_nord_theme())

falyx/context.py

@@ -1,95 +1,27 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""context.py"""
-"""
-Execution context management for Falyx CLI actions.
-
-This module defines `ExecutionContext` and `SharedContext`, which are responsible for
-capturing per-action and cross-action metadata during CLI workflow execution. These
-context objects provide structured introspection, result tracking, error recording,
-and time-based performance metrics.
-
-- `ExecutionContext`: Captures runtime information for a single action execution,
-  including arguments, results, exceptions, timing, and logging.
-- `SharedContext`: Maintains shared state and result propagation across
-  `ChainedAction` or `ActionGroup` executions.
-
-These contexts enable rich introspection, traceability, and workflow coordination,
-supporting hook lifecycles, retries, and structured output generation.
-"""
-from __future__ import annotations
-
 import time
 from datetime import datetime
-from traceback import format_exception
 from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
 from rich.console import Console
 
-from falyx.console import console
-
 
 class ExecutionContext(BaseModel):
-    """
-    Represents the runtime metadata and state for a single action execution.
-
-    The `ExecutionContext` tracks arguments, results, exceptions, timing, and
-    additional metadata for each invocation of a Falyx `BaseAction`. It provides
-    integration with the Falyx hook system and execution registry, enabling lifecycle
-    management, diagnostics, and structured logging.
-
-    Attributes:
-        name (str): The name of the action being executed.
-        args (tuple): Positional arguments passed to the action.
-        kwargs (dict): Keyword arguments passed to the action.
-        action (BaseAction | Callable): The action instance being executed.
-        result (Any | None): The result of the action, if successful.
-        exception (BaseException | None): The exception raised, if execution failed.
-        start_time (float | None): High-resolution performance start time.
-        end_time (float | None): High-resolution performance end time.
-        start_wall (datetime | None): Wall-clock timestamp when execution began.
-        end_wall (datetime | None): Wall-clock timestamp when execution ended.
-        extra (dict): Metadata for custom introspection or special use by Actions.
-        console (Console): Rich console instance for logging or UI output.
-        shared_context (SharedContext | None): Optional shared context when running in
-                                               a chain or group.
-
-    Properties:
-        duration (float | None): The execution duration in seconds.
-        success (bool): Whether the action completed without raising an exception.
-        status (str): Returns "OK" if successful, otherwise "ERROR".
-
-    Methods:
-        start_timer(): Starts the timing and timestamp tracking.
-        stop_timer(): Stops timing and stores end timestamps.
-        log_summary(logger=None): Logs a rich or plain summary of execution.
-        to_log_line(): Returns a single-line log entry for metrics or tracing.
-        as_dict(): Serializes core result and diagnostic metadata.
-        get_shared_context(): Returns the shared context or creates a default one.
-
-    This class is used internally by all Falyx actions and hook events. It ensures
-    consistent tracking and reporting across asynchronous workflows, including CLI-driven
-    and automated batch executions.
-    """
-
     name: str
     args: tuple = ()
-    kwargs: dict = Field(default_factory=dict)
+    kwargs: dict = {}
     action: Any
     result: Any | None = None
-    traceback: str | None = None
+    exception: Exception | None = None
-    _exception: BaseException | None = None
 
     start_time: float | None = None
     end_time: float | None = None
     start_wall: datetime | None = None
     end_wall: datetime | None = None
 
-    index: int | None = None
-
     extra: dict[str, Any] = Field(default_factory=dict)
-    console: Console = console
+    console: Console = Field(default_factory=lambda: Console(color_system="auto"))
-
-    shared_context: SharedContext | None = None
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
@@ -101,13 +33,6 @@ class ExecutionContext(BaseModel):
         self.end_time = time.perf_counter()
         self.end_wall = datetime.now()
 
-    def get_shared_context(self) -> SharedContext:
-        if not self.shared_context:
-            raise ValueError(
-                "SharedContext is not set. This context is not part of a chain or group."
-            )
-        return self.shared_context
-
     @property
     def duration(self) -> float | None:
         if self.start_time is None:
@@ -124,63 +49,37 @@ class ExecutionContext(BaseModel):
     def status(self) -> str:
         return "OK" if self.success else "ERROR"
 
-    @property
-    def exception(self) -> BaseException | None:
-        return self._exception
-
-    @exception.setter
-    def exception(self, exc: BaseException | None):
-        self._exception = exc
-        if exc is not None:
-            self.traceback = "".join(format_exception(exc)).strip()
-
-    @property
-    def signature(self) -> str:
-        """
-        Returns a string representation of the action signature, including
-        its name and arguments.
-        """
-        args = ", ".join(map(repr, self.args))
-        kwargs = ", ".join(f"{key}={value!r}" for key, value in self.kwargs.items())
-        signature = ", ".join(filter(None, [args, kwargs]))
-        return f"{self.action} ({signature})"
-
     def as_dict(self) -> dict:
         return {
             "name": self.name,
             "result": self.result,
             "exception": repr(self.exception) if self.exception else None,
-            "traceback": self.traceback,
             "duration": self.duration,
             "extra": self.extra,
         }
 
-    def log_summary(self, logger=None) -> None:
+    def log_summary(self, logger=None):
         summary = self.as_dict()
         message = [f"[SUMMARY] {summary['name']} | "]
 
         if self.start_wall:
             message.append(f"Start: {self.start_wall.strftime('%H:%M:%S')} | ")
 
-        if self.end_wall:
+        if self.end_time:
             message.append(f"End: {self.end_wall.strftime('%H:%M:%S')} | ")
 
         message.append(f"Duration: {summary['duration']:.3f}s | ")
 
         if summary["exception"]:
-            message.append(f"Exception: {summary['exception']}")
+            message.append(f"❌ Exception: {summary['exception']}")
         else:
-            message.append(f"Result: {summary['result']}")
+            message.append(f"✅ Result: {summary['result']}")
         (logger or self.console.print)("".join(message))
 
     def to_log_line(self) -> str:
         """Structured flat-line format for logging and metrics."""
         duration_str = f"{self.duration:.3f}s" if self.duration is not None else "n/a"
-        exception_str = (
+        exception_str = f"{type(self.exception).__name__}: {self.exception}" if self.exception else "None"
-            f"{type(self.exception).__name__}: {self.exception}"
-            if self.exception
-            else "None"
-        )
         return (
             f"[{self.name}] status={self.status} duration={duration_str} "
             f"result={repr(self.result)} exception={exception_str}"
@@ -188,11 +87,7 @@ class ExecutionContext(BaseModel):
 
     def __str__(self) -> str:
         duration_str = f"{self.duration:.3f}s" if self.duration is not None else "n/a"
-        result_str = (
+        result_str = f"Result: {repr(self.result)}" if self.success else f"Exception: {self.exception}"
-            f"Result: {repr(self.result)}"
-            if self.success
-            else f"Exception: {self.exception}"
-        )
         return (
             f"<ExecutionContext '{self.name}' | {self.status} | "
             f"Duration: {duration_str} | {result_str}>"
@@ -208,58 +103,19 @@ class ExecutionContext(BaseModel):
         )
 
 
-class SharedContext(BaseModel):
+class ResultsContext(BaseModel):
-    """
-    SharedContext maintains transient shared state during the execution
-    of a ChainedAction or ActionGroup.
-
-    This context object is passed to all actions within a chain or group,
-    enabling result propagation, shared data exchange, and coordinated
-    tracking of execution order and failures.
-
-    Attributes:
-        name (str): Identifier for the context (usually the parent action name).
-        results (list[Any]): Captures results from each action, in order of execution.
-        errors (list[tuple[int, BaseException]]): Indexed list of errors from failed actions.
-        current_index (int): Index of the currently executing action (used in chains).
-        is_parallel (bool): Whether the context is used in parallel mode (ActionGroup).
-        shared_result (Any | None): Optional shared value available to all actions in
-                                    parallel mode.
-        share (dict[str, Any]): Custom shared key-value store for user-defined
-                                communication
-            between actions (e.g., flags, intermediate data, settings).
-
-    Note:
-        SharedContext is only used within grouped or chained workflows. It should not be
-        used for standalone `Action` executions, where state should be scoped to the
-        individual ExecutionContext instead.
-
-    Example usage:
-        - In a ChainedAction: last_result is pulled from `results[-1]`.
-        - In an ActionGroup: all actions can read/write `shared_result` or use `share`.
-
-    This class supports fault-tolerant and modular composition of CLI workflows
-    by enabling flexible intra-action communication without global state.
-    """
-
     name: str
-    action: Any
     results: list[Any] = Field(default_factory=list)
-    errors: list[tuple[int, BaseException]] = Field(default_factory=list)
+    errors: list[tuple[int, Exception]] = Field(default_factory=list)
     current_index: int = -1
     is_parallel: bool = False
     shared_result: Any | None = None
 
-    share: dict[str, Any] = Field(default_factory=dict)
-
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
     def add_result(self, result: Any) -> None:
         self.results.append(result)
 
-    def add_error(self, index: int, error: BaseException) -> None:
-        self.errors.append((index, error))
-
     def set_shared_result(self, result: Any) -> None:
         self.shared_result = result
         if self.is_parallel:
@@ -270,21 +126,14 @@ class SharedContext(BaseModel):
             return self.shared_result
         return self.results[-1] if self.results else None
 
-    def get(self, key: str, default: Any = None) -> Any:
-        return self.share.get(key, default)
-
-    def set(self, key: str, value: Any) -> None:
-        self.share[key] = value
-
     def __str__(self) -> str:
         parallel_label = "Parallel" if self.is_parallel else "Sequential"
         return (
-            f"<{parallel_label}SharedContext '{self.name}' | "
+            f"<{parallel_label}ResultsContext '{self.name}' | "
             f"Results: {self.results} | "
             f"Errors: {self.errors}>"
         )
 
-
 if __name__ == "__main__":
     import asyncio
 

falyx/debug.py

@@ -1,29 +1,14 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Provides debug logging hooks for Falyx action execution.
-
-This module defines lifecycle hook functions (`log_before`, `log_success`, `log_after`, `log_error`)
-that can be registered with a `HookManager` to trace command execution.
-
-Logs include:
-- Action invocation with argument signature
-- Success result (with truncation for large outputs)
-- Errors with full exception info
-- Total runtime duration after execution
-
-Also exports `register_debug_hooks()` to register all log hooks in bulk.
-"""
 from falyx.context import ExecutionContext
 from falyx.hook_manager import HookManager, HookType
-from falyx.logger import logger
+from falyx.utils import logger
 
 
 def log_before(context: ExecutionContext):
     """Log the start of an action."""
     args = ", ".join(map(repr, context.args))
-    kwargs = ", ".join(f"{key}={value!r}" for key, value in context.kwargs.items())
+    kwargs = ", ".join(f"{k}={v!r}" for k, v in context.kwargs.items())
     signature = ", ".join(filter(None, [args, kwargs]))
-    logger.info("[%s] Starting -> %s(%s)", context.name, context.action, signature)
+    logger.info("[%s] 🚀 Starting → %s(%s)", context.name, context.action, signature)
 
 
 def log_success(context: ExecutionContext):
@@ -31,18 +16,18 @@ def log_success(context: ExecutionContext):
     result_str = repr(context.result)
     if len(result_str) > 100:
         result_str = f"{result_str[:100]} ..."
-    logger.debug("[%s] Success -> Result: %s", context.name, result_str)
+    logger.debug("[%s] ✅ Success → Result: %s", context.name, result_str)
 
 
 def log_after(context: ExecutionContext):
     """Log the completion of an action, regardless of success or failure."""
-    logger.debug("[%s] Finished in %.3fs", context.name, context.duration)
+    logger.debug("[%s] ⏱️ Finished in %.3fs", context.name, context.duration)
 
 
 def log_error(context: ExecutionContext):
     """Log an error that occurred during the action."""
     logger.error(
-        "[%s] Error (%s): %s",
+        "[%s] ❌ Error (%s): %s",
         context.name,
         type(context.exception).__name__,
         context.exception,

falyx/exceptions.py

@@ -1,30 +1,3 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines all custom exception classes used in the Falyx CLI framework.
-
-These exceptions provide structured error handling for common failure cases,
-including command conflicts, invalid actions or hooks, parser errors, and execution guards
-like circuit breakers or empty workflows.
-
-All exceptions inherit from `FalyxError`, the base exception for the framework.
-
-Exception Hierarchy:
-- FalyxError
-    ├── CommandAlreadyExistsError
-    ├── InvalidHookError
-    ├── InvalidActionError
-    ├── NotAFalyxError
-    ├── CircuitBreakerOpen
-    ├── EmptyChainError
-    ├── EmptyGroupError
-    ├── EmptyPoolError
-    └── CommandArgumentError
-
-These are raised internally throughout the Falyx system to signal user-facing or
-developer-facing problems that should be caught and reported.
-"""
-
-
 class FalyxError(Exception):
     """Custom exception for the Menu class."""
 
@@ -47,19 +20,3 @@ class NotAFalyxError(FalyxError):
 
 class CircuitBreakerOpen(FalyxError):
     """Exception raised when the circuit breaker is open."""
-
-
-class EmptyChainError(FalyxError):
-    """Exception raised when the chain is empty."""
-
-
-class EmptyGroupError(FalyxError):
-    """Exception raised when the chain is empty."""
-
-
-class EmptyPoolError(FalyxError):
-    """Exception raised when the chain is empty."""
-
-
-class CommandArgumentError(FalyxError):
-    """Exception raised when there is an error in the command argument parser."""

falyx/execution_registry.py

@@ -1,246 +1,49 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""execution_registry.py"""
-"""
-Provides the `ExecutionRegistry`, a centralized runtime store for capturing and inspecting
-the execution history of Falyx actions.
-
-The registry automatically records every `ExecutionContext` created during action
-execution—including context metadata, results, exceptions, duration, and tracebacks.
-It supports filtering, summarization, and visual inspection via a Rich-rendered table.
-
-Designed for:
-- Workflow debugging and CLI diagnostics
-- Interactive history browsing or replaying previous runs
-- Providing user-visible `history` or `last-result` commands inside CLI apps
-
-Key Features:
-- Global, in-memory store of all `ExecutionContext` objects (by name, index, or full list)
-- Thread-safe indexing and summary display
-- Traceback-aware result inspection and filtering by status (success/error)
-- Used by built-in `History` command in Falyx CLI
-
-Example:
-    from falyx.execution_registry import ExecutionRegistry as er
-
-    # Record a context
-    er.record(context)
-
-    # Display a rich table summary
-    er.summary()
-
-    # Print the last non-ignored result
-    er.summary(last_result=True)
-
-    # Clear execution history
-    er.summary(clear=True)
-
-Note:
-    The registry is volatile and cleared on each process restart or when `clear()` is called.
-    All data is retained in memory only.
-
-Public Interface:
-- record(context): Log an ExecutionContext and assign index.
-- get_all(): List all stored contexts.
-- get_by_name(name): Retrieve all contexts by action name.
-- get_latest(): Retrieve the most recent context.
-- clear(): Reset the registry.
-- summary(...): Rich console summary of stored execution results.
-"""
-from __future__ import annotations
-
 from collections import defaultdict
 from datetime import datetime
-from threading import Lock
+from typing import Dict, List
-from typing import Literal
 
 from rich import box
 from rich.console import Console
 from rich.table import Table
 
-from falyx.console import console
 from falyx.context import ExecutionContext
-from falyx.logger import logger
+from falyx.utils import logger
-from falyx.themes import OneColors
 
 
 class ExecutionRegistry:
-    """
+    _store_by_name: Dict[str, List[ExecutionContext]] = defaultdict(list)
-    Global registry for recording and inspecting Falyx action executions.
+    _store_all: List[ExecutionContext] = []
-
+    _console = Console(color_system="truecolor")
-    This class captures every `ExecutionContext` created by Falyx Actions,
-    tracking metadata, results, exceptions, and performance metrics. It enables
-    rich introspection, post-execution inspection, and formatted summaries
-    suitable for interactive and headless CLI use.
-
-    Data is retained in memory until cleared or process exit.
-
-    Use Cases:
-        - Auditing chained or dynamic workflows
-        - Rendering execution history in a help/debug menu
-        - Accessing previous results or errors for reuse
-
-    Attributes:
-        _store_by_name (dict): Maps action name → list of ExecutionContext objects.
-        _store_by_index (dict): Maps numeric index → ExecutionContext.
-        _store_all (list): Ordered list of all contexts.
-        _index (int): Global counter for assigning unique execution indices.
-        _lock (Lock): Thread lock for atomic writes to the registry.
-        _console (Console): Rich console used for rendering summaries.
-    """
-
-    _store_by_name: dict[str, list[ExecutionContext]] = defaultdict(list)
-    _store_by_index: dict[int, ExecutionContext] = {}
-    _store_all: list[ExecutionContext] = []
-    _console: Console = console
-    _index = 0
-    _lock = Lock()
 
     @classmethod
     def record(cls, context: ExecutionContext):
-        """
+        """Record an execution context."""
-        Record an execution context and assign a unique index.
-
-        This method logs the context, appends it to the registry,
-        and makes it available for future summary or filtering.
-
-        Args:
-            context (ExecutionContext): The context to be tracked.
-        """
         logger.debug(context.to_log_line())
-        with cls._lock:
-            context.index = cls._index
-            cls._store_by_index[cls._index] = context
-            cls._index += 1
         cls._store_by_name[context.name].append(context)
         cls._store_all.append(context)
 
     @classmethod
-    def get_all(cls) -> list[ExecutionContext]:
+    def get_all(cls) -> List[ExecutionContext]:
-        """
-        Return all recorded execution contexts in order of execution.
-
-        Returns:
-            list[ExecutionContext]: All stored action contexts.
-        """
         return cls._store_all
 
     @classmethod
-    def get_by_name(cls, name: str) -> list[ExecutionContext]:
+    def get_by_name(cls, name: str) -> List[ExecutionContext]:
-        """
-        Retrieve all executions recorded under a given action name.
-
-        Args:
-            name (str): The name of the action.
-
-        Returns:
-            list[ExecutionContext]: Matching contexts, or empty if none found.
-        """
         return cls._store_by_name.get(name, [])
 
     @classmethod
     def get_latest(cls) -> ExecutionContext:
-        """
-        Return the most recent execution context.
-
-        Returns:
-            ExecutionContext: The last recorded context.
-        """
         return cls._store_all[-1]
 
     @classmethod
     def clear(cls):
-        """
-        Clear all stored execution data and reset internal indices.
-
-        This operation is destructive and cannot be undone.
-        """
         cls._store_by_name.clear()
         cls._store_all.clear()
-        cls._store_by_index.clear()
 
     @classmethod
-    def summary(
+    def summary(cls):
-        cls,
+        table = Table(title="[📊] Execution History", expand=True, box=box.SIMPLE)
-        name: str = "",
-        index: int | None = None,
-        result_index: int | None = None,
-        clear: bool = False,
-        last_result: bool = False,
-        status: Literal["all", "success", "error"] = "all",
-    ):
-        """
-        Display a formatted Rich table of recorded executions.
 
-        Supports filtering by action name, index, or execution status.
-        Can optionally show only the last result or a specific indexed result.
-        Also supports clearing the registry interactively.
-
-        Args:
-            name (str): Filter by action name.
-            index (int | None): Filter by specific execution index.
-            result_index (int | None): Print result (or traceback) of a specific index.
-            clear (bool): If True, clears the registry and exits.
-            last_result (bool): If True, prints only the most recent result.
-            status (Literal): One of "all", "success", or "error" to filter displayed rows.
-        """
-        if clear:
-            cls.clear()
-            cls._console.print(f"[{OneColors.GREEN}]✅ Execution history cleared.")
-            return
-
-        if last_result:
-            for ctx in reversed(cls._store_all):
-                if not ctx.action.ignore_in_history:
-                    cls._console.print(f"{ctx.signature}:")
-                    if ctx.traceback:
-                        cls._console.print(ctx.traceback)
-                    else:
-                        cls._console.print(ctx.result)
-                    return
-            cls._console.print(
-                f"[{OneColors.DARK_RED}]❌ No valid executions found to display last result."
-            )
-            return
-
-        if result_index is not None and result_index >= 0:
-            try:
-                result_context = cls._store_by_index[result_index]
-            except KeyError:
-                cls._console.print(
-                    f"[{OneColors.DARK_RED}]❌ No execution found for index {result_index}."
-                )
-                return
-            cls._console.print(f"{result_context.signature}:")
-            if result_context.traceback:
-                cls._console.print(result_context.traceback)
-            else:
-                cls._console.print(result_context.result)
-            return
-
-        if name:
-            contexts = cls.get_by_name(name)
-            if not contexts:
-                cls._console.print(
-                    f"[{OneColors.DARK_RED}]❌ No executions found for action '{name}'."
-                )
-                return
-            title = f"📊 Execution History for '{contexts[0].name}'"
-        elif index is not None and index >= 0:
-            try:
-                contexts = [cls._store_by_index[index]]
-                print(contexts)
-            except KeyError:
-                cls._console.print(
-                    f"[{OneColors.DARK_RED}]❌ No execution found for index {index}."
-                )
-                return
-            title = f"📊 Execution History for Index {index}"
-        else:
-            contexts = cls.get_all()
-            title = "📊 Execution History"
-
-        table = Table(title=title, expand=True, box=box.SIMPLE)
-
-        table.add_column("Index", justify="right", style="dim")
         table.add_column("Name", style="bold cyan")
         table.add_column("Start", justify="right", style="dim")
         table.add_column("End", justify="right", style="dim")
@@ -248,32 +51,26 @@ class ExecutionRegistry:
         table.add_column("Status", style="bold")
         table.add_column("Result / Exception", overflow="fold")
 
-        for ctx in contexts:
+        for ctx in cls.get_all():
-            start = (
+            start = datetime.fromtimestamp(ctx.start_time).strftime("%H:%M:%S") if ctx.start_time else "n/a"
-                datetime.fromtimestamp(ctx.start_time).strftime("%H:%M:%S")
+            end = datetime.fromtimestamp(ctx.end_time).strftime("%H:%M:%S") if ctx.end_time else "n/a"
-                if ctx.start_time
-                else "n/a"
-            )
-            end = (
-                datetime.fromtimestamp(ctx.end_time).strftime("%H:%M:%S")
-                if ctx.end_time
-                else "n/a"
-            )
             duration = f"{ctx.duration:.3f}s" if ctx.duration else "n/a"
 
-            if ctx.exception and status.lower() in ["all", "error"]:
+            if ctx.exception:
-                final_status = f"[{OneColors.DARK_RED}]❌ Error"
+                status = "[bold red]❌ Error"
-                final_result = repr(ctx.exception)
+                result = repr(ctx.exception)
-            elif status.lower() in ["all", "success"]:
-                final_status = f"[{OneColors.GREEN}]✅ Success"
-                final_result = repr(ctx.result)
-                if len(final_result) > 50:
-                    final_result = f"{final_result[:50]}..."
             else:
-                continue
+                status = "[green]✅ Success"
+                result = repr(ctx.result)
 
-            table.add_row(
+            table.add_row(ctx.name, start, end, duration, status, result)
-                str(ctx.index), ctx.name, start, end, duration, final_status, final_result
-            )
 
         cls._console.print(table)
+
+    @classmethod
+    def get_history_action(cls) -> "Action":
+        """Return an Action that prints the execution summary."""
+        from falyx.action import Action
+        async def show_history():
+            cls.summary()
+        return Action(name="View Execution History", action=show_history)

falyx/hook_manager.py

@@ -1,58 +1,21 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""hook_manager.py"""
-"""
-Defines the `HookManager` and `HookType` used in the Falyx CLI framework to manage
-execution lifecycle hooks around actions and commands.
-
-The hook system enables structured callbacks for important stages in a Falyx action's
-execution, such as before execution, after success, upon error, and teardown. These
-can be used for logging, side effects, diagnostics, metrics, and rollback logic.
-
-Key Components:
-- HookType: Enum categorizing supported hook lifecycle stages
-- HookManager: Core class for registering and invoking hooks during action execution
-- Hook: Union of sync and async callables accepting an `ExecutionContext`
-
-Usage:
-    hooks = HookManager()
-    hooks.register(HookType.BEFORE, log_before)
-"""
 from __future__ import annotations
 
 import inspect
 from enum import Enum
-from typing import Awaitable, Callable, Union
+from typing import Awaitable, Callable, Dict, List, Optional, Union
 
 from falyx.context import ExecutionContext
-from falyx.logger import logger
+from falyx.utils import logger
 
 Hook = Union[
-    Callable[[ExecutionContext], None], Callable[[ExecutionContext], Awaitable[None]]
+    Callable[[ExecutionContext], None],
+    Callable[[ExecutionContext], Awaitable[None]]
 ]
 
 
 class HookType(Enum):
-    """
+    """Enum for hook types to categorize the hooks."""
-    Enum for supported hook lifecycle phases in Falyx.
-
-    HookType is used to classify lifecycle events that can be intercepted
-    with user-defined callbacks.
-
-    Members:
-        BEFORE: Run before the action is invoked.
-        ON_SUCCESS: Run after successful completion.
-        ON_ERROR: Run when an exception occurs.
-        AFTER: Run after success or failure (always runs).
-        ON_TEARDOWN: Run at the very end, for resource cleanup.
-
-    Aliases:
-        "success" → "on_success"
-        "error" → "on_error"
-        "teardown" → "on_teardown"
-
-    Example:
-        HookType("error") → HookType.ON_ERROR
-    """
-
     BEFORE = "before"
     ON_SUCCESS = "on_success"
     ON_ERROR = "on_error"
@@ -60,80 +23,27 @@ class HookType(Enum):
     ON_TEARDOWN = "on_teardown"
 
     @classmethod
-    def choices(cls) -> list[HookType]:
+    def choices(cls) -> List[HookType]:
         """Return a list of all hook type choices."""
         return list(cls)
 
-    @classmethod
-    def _get_alias(cls, value: str) -> str:
-        aliases = {
-            "success": "on_success",
-            "error": "on_error",
-            "teardown": "on_teardown",
-        }
-        return aliases.get(value, value)
-
-    @classmethod
-    def _missing_(cls, value: object) -> HookType:
-        if not isinstance(value, str):
-            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
-        normalized = value.strip().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 {cls.__name__}: '{value}'. Must be one of: {valid}")
-
     def __str__(self) -> str:
         """Return the string representation of the hook type."""
         return self.value
 
 
 class HookManager:
-    """
-    Manages lifecycle hooks for a command or action.
-
-    `HookManager` tracks user-defined callbacks to be run at key points in a command's
-    lifecycle: before execution, on success, on error, after completion, and during
-    teardown. Both sync and async hooks are supported.
-
-    Methods:
-        register(hook_type, hook): Register a callable for a given HookType.
-        clear(hook_type): Remove hooks for one or all lifecycle stages.
-        trigger(hook_type, context): Execute all hooks of a given type.
-
-    Example:
-        hooks = HookManager()
-        hooks.register(HookType.BEFORE, my_logger)
-    """
-
     def __init__(self) -> None:
-        self._hooks: dict[HookType, list[Hook]] = {
+        self._hooks: Dict[HookType, List[Hook]] = {
             hook_type: [] for hook_type in HookType
         }
 
-    def register(self, hook_type: HookType | str, hook: Hook):
+    def register(self, hook_type: HookType, hook: Hook):
-        """
+        if hook_type not in HookType:
-        Register a new hook for a given lifecycle phase.
+            raise ValueError(f"Unsupported hook type: {hook_type}")
-
-        Args:
-            hook_type (HookType | str): The hook category (e.g. "before", "on_success").
-            hook (Callable): The hook function to register.
-
-        Raises:
-            ValueError: If the hook type is invalid.
-        """
-        hook_type = HookType(hook_type)
         self._hooks[hook_type].append(hook)
 
-    def clear(self, hook_type: HookType | None = None):
+    def clear(self, hook_type: Optional[HookType] = None):
-        """
-        Clear registered hooks for one or all hook types.
-
-        Args:
-            hook_type (HookType | None): If None, clears all hooks.
-        """
         if hook_type:
             self._hooks[hook_type] = []
         else:
@@ -141,17 +51,6 @@ class HookManager:
                 self._hooks[ht] = []
 
     async def trigger(self, hook_type: HookType, context: ExecutionContext):
-        """
-        Invoke all hooks registered for a given lifecycle phase.
-
-        Args:
-            hook_type (HookType): The lifecycle phase to trigger.
-            context (ExecutionContext): The execution context passed to each hook.
-
-        Raises:
-            Exception: Re-raises the original context.exception if a hook fails during
-                       ON_ERROR. Other hook exceptions are logged and skipped.
-        """
         if hook_type not in self._hooks:
             raise ValueError(f"Unsupported hook type: {hook_type}")
         for hook in self._hooks[hook_type]:
@@ -161,27 +60,9 @@ class HookManager:
                 else:
                     hook(context)
             except Exception as hook_error:
-                logger.warning(
+                logger.warning(f"⚠️ Hook '{hook.__name__}' raised an exception during '{hook_type}'"
-                    "[Hook:%s] raised an exception during '%s' for '%s': %s",
+                               f" for '{context.name}': {hook_error}")
-                    hook.__name__,
+
-                    hook_type,
-                    context.name,
-                    hook_error,
-                )
                 if hook_type == HookType.ON_ERROR:
-                    assert isinstance(
+                    assert isinstance(context.exception, BaseException)
-                        context.exception, Exception
-                    ), "Context exception should be set for ON_ERROR hook"
                     raise context.exception from hook_error
-
-    def __str__(self) -> str:
-        """Return a formatted string of registered hooks grouped by hook type."""
-
-        def format_hook_list(hooks: list[Hook]) -> str:
-            return ", ".join(h.__name__ for h in hooks) if hooks else "—"
-
-        lines = ["<HookManager>"]
-        for hook_type in HookType:
-            hook_list = self._hooks.get(hook_type, [])
-            lines.append(f"  {hook_type.value}: {format_hook_list(hook_list)}")
-        return "\n".join(lines)

falyx/hooks.py

@@ -1,109 +1,32 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""hooks.py"""
-"""
-Defines reusable lifecycle hooks for Falyx Actions and Commands.
-
-This module includes:
-- `spinner_before_hook`: Automatically starts a spinner before an action runs.
-- `spinner_teardown_hook`: Stops and clears the spinner after the action completes.
-- `ResultReporter`: A success hook that displays a formatted result with duration.
-- `CircuitBreaker`: A failure-aware hook manager that prevents repeated execution
-  after a configurable number of failures.
-
-These hooks can be registered on `HookManager` instances via lifecycle stages
-(`before`, `on_error`, `after`, etc.) to enhance resiliency and observability.
-
-Intended for use with:
-- Actions that require user feedback during long-running operations.
-- Retryable or unstable actions
-- Interactive CLI feedback
-- Safety checks prior to execution
-
-Example usage:
-    breaker = CircuitBreaker(max_failures=3)
-    hooks.register(HookType.BEFORE, breaker.before_hook)
-    hooks.register(HookType.ON_ERROR, breaker.error_hook)
-    hooks.register(HookType.AFTER, breaker.after_hook)
-
-    reporter = ResultReporter()
-    hooks.register(HookType.ON_SUCCESS, reporter.report)
-"""
 import time
-from typing import Any, Callable
 
 from falyx.context import ExecutionContext
 from falyx.exceptions import CircuitBreakerOpen
-from falyx.logger import logger
+from falyx.themes.colors import OneColors
-from falyx.themes import OneColors
+from falyx.utils import logger
-
-
-async def spinner_before_hook(context: ExecutionContext):
-    """Adds a spinner before the action starts."""
-    cmd = context.action
-    if cmd.options_manager is None:
-        return
-    sm = context.action.options_manager.spinners
-    if hasattr(cmd, "name"):
-        cmd_name = cmd.name
-    else:
-        cmd_name = cmd.key
-    await sm.add(
-        cmd_name,
-        cmd.spinner_message,
-        cmd.spinner_type,
-        cmd.spinner_style,
-        cmd.spinner_speed,
-    )
-
-
-async def spinner_teardown_hook(context: ExecutionContext):
-    """Removes the spinner after the action finishes (success or failure)."""
-    cmd = context.action
-    if cmd.options_manager is None:
-        return
-    if hasattr(cmd, "name"):
-        cmd_name = cmd.name
-    else:
-        cmd_name = cmd.key
-    sm = context.action.options_manager.spinners
-    await sm.remove(cmd_name)
 
 
 class ResultReporter:
-    """Reports the success of an action."""
+    def __init__(self, formatter: callable = None):
-
-    def __init__(self, formatter: Callable[[Any], str] | None = None):
         """
         Optional result formatter. If not provided, uses repr(result).
         """
-        self.formatter = formatter or (self.default_formatter)
+        self.formatter = formatter or (lambda r: repr(r))
-
-    def default_formatter(self, result: Any):
-        """
-        Default formatter for results. Converts the result to a string.
-        """
-        return repr(result)
 
     @property
     def __name__(self):
         return "ResultReporter"
 
     async def report(self, context: ExecutionContext):
-        if not callable(self.formatter):
-            raise TypeError("formatter must be callable")
         if context.result is not None:
             result_text = self.formatter(context.result)
-            duration = (
+            duration = f"{context.duration:.3f}s" if context.duration is not None else "n/a"
-                f"{context.duration:.3f}s" if context.duration is not None else "n/a"
+            context.console.print(f"[{OneColors.GREEN}]✅ '{context.name}' "
-            )
+                  f"completed:[/] {result_text} in {duration}.")
-            context.console.print(
-                f"[{OneColors.GREEN}]✅ '{context.name}' "
-                f"completed:[/] {result_text} in {duration}."
-            )
 
 
 class CircuitBreaker:
-    """Circuit Breaker pattern to prevent repeated failures."""
-
     def __init__(self, max_failures=3, reset_timeout=10):
         self.max_failures = max_failures
         self.reset_timeout = reset_timeout
@@ -114,30 +37,21 @@ class CircuitBreaker:
         name = context.name
         if self.open_until:
             if time.time() < self.open_until:
-                raise CircuitBreakerOpen(
+                raise CircuitBreakerOpen(f"🔴 Circuit open for '{name}' until {time.ctime(self.open_until)}.")
-                    f"Circuit open for '{name}' until {time.ctime(self.open_until)}."
-                )
             else:
-                logger.info("Circuit closed again for '%s'.")
+                logger.info(f"🟢 Circuit closed again for '{name}'.")
                 self.failures = 0
                 self.open_until = None
 
     def error_hook(self, context: ExecutionContext):
         name = context.name
         self.failures += 1
-        logger.warning(
+        logger.warning(f"⚠️ CircuitBreaker: '{name}' failure {self.failures}/{self.max_failures}.")
-            "CircuitBreaker: '%s' failure %s/%s.",
-            name,
-            self.failures,
-            self.max_failures,
-        )
         if self.failures >= self.max_failures:
             self.open_until = time.time() + self.reset_timeout
-            logger.error(
+            logger.error(f"🔴 Circuit opened for '{name}' until {time.ctime(self.open_until)}.")
-                "Circuit opened for '%s' until %s.", name, time.ctime(self.open_until)
-            )
 
-    def after_hook(self, _: ExecutionContext):
+    def after_hook(self, context: ExecutionContext):
         self.failures = 0
 
     def is_open(self):
@@ -146,4 +60,4 @@ class CircuitBreaker:
     def reset(self):
         self.failures = 0
         self.open_until = None
-        logger.info("Circuit reset.")
+        logger.info("🔄 Circuit reset.")

falyx/importer.py

@@ -0,0 +1,29 @@
+"""importer.py"""
+
+import importlib
+from types import ModuleType
+from typing import Any, Callable
+
+
+def resolve_action(path: str) -> Callable[..., Any]:
+    """
+    Resolve a dotted path to a Python callable.
+    Example: 'mypackage.mymodule.myfunction'
+
+    Raises:
+        ImportError if the module or function does not exist.
+        ValueError if the resolved attribute is not callable.
+    """
+    if ":" in path:
+        module_path, function_name = path.split(":")
+    else:
+        *module_parts, function_name = path.split(".")
+        module_path = ".".join(module_parts)
+
+    module: ModuleType = importlib.import_module(module_path)
+    function: Any = getattr(module, function_name)
+
+    if not callable(function):
+        raise ValueError(f"Resolved attribute '{function_name}' is not callable.")
+
+    return function

falyx/init.py

@@ -1,151 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Project and global initializer for Falyx CLI environments.
-
-This module defines functions to bootstrap a new Falyx-based CLI project or
-create a global user-level configuration in `~/.config/falyx`.
-
-Functions:
-- `init_project(name: str)`: Creates a new CLI project folder with `tasks.py`
-  and `falyx.yaml` using example actions and config structure.
-- `init_global()`: Creates a shared config in the user's home directory for
-  defining reusable or always-available CLI commands.
-
-Generated files include:
-- `tasks.py`: Python module with `Action`, `ChainedAction`, and async examples
-- `falyx.yaml`: YAML config with command definitions for CLI entry points
-
-Used by:
-- The `falyx init` and `falyx init --global` commands
-"""
-from pathlib import Path
-
-from falyx.console import console
-
-TEMPLATE_TASKS = """\
-# This file is used by falyx.yaml to define CLI actions.
-# You can run: falyx run [key] or falyx list to see available commands.
-
-import asyncio
-import json
-
-from falyx.action import Action, ChainedAction, ShellAction, 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 = """\
-# 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 = """\
-async def cleanup():
-    print("🧹 Cleaning temp files...")
-"""
-
-GLOBAL_CONFIG = """\
-title: Global Falyx Config
-commands:
-  - key: C
-    description: Cleanup temp files
-    action: tasks.cleanup
-    aliases: [clean, cleanup]
-"""
-
-
-def init_project(name: str) -> None:
-    target = Path(name).resolve()
-    target.mkdir(parents=True, exist_ok=True)
-
-    tasks_path = target / "tasks.py"
-    config_path = target / "falyx.yaml"
-
-    if tasks_path.exists() or config_path.exists():
-        console.print(f"⚠️  Project already initialized at {target}")
-        return None
-
-    tasks_path.write_text(TEMPLATE_TASKS)
-    config_path.write_text(TEMPLATE_CONFIG)
-
-    console.print(f"✅ Initialized Falyx project in {target}")
-
-
-def init_global() -> None:
-    config_dir = Path.home() / ".config" / "falyx"
-    config_dir.mkdir(parents=True, exist_ok=True)
-
-    tasks_path = config_dir / "tasks.py"
-    config_path = config_dir / "falyx.yaml"
-
-    if tasks_path.exists() or config_path.exists():
-        console.print("⚠️  Global Falyx config already exists at ~/.config/falyx")
-        return None
-
-    tasks_path.write_text(GLOBAL_TEMPLATE_TASKS)
-    config_path.write_text(GLOBAL_CONFIG)
-
-    console.print("✅ Initialized global Falyx config at ~/.config/falyx")

falyx/logger.py

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

falyx/main/main.py

@@ -0,0 +1,88 @@
+import asyncio
+import logging
+from rich.markdown import Markdown
+
+from falyx import Action, Falyx
+from falyx.hook_manager import HookType
+from falyx.debug import log_before, log_success, log_error, log_after
+from falyx.themes.colors import OneColors
+from falyx.utils import setup_logging
+
+# Setup logging
+setup_logging(console_log_level=logging.WARNING, json_log_to_file=True)
+
+
+def main():
+    # Create the menu
+    menu = Falyx(
+        title=Markdown("# 🚀 Falyx CLI Demo"),
+        welcome_message="Welcome to Falyx!",
+        exit_message="Thanks for using Falyx!",
+        include_history_command=True,
+        include_help_command=True,
+    )
+
+    # Define async actions
+    async def hello():
+        print("👋 Hello from Falyx CLI!")
+
+    def goodbye():
+        print("👋 Goodbye from Falyx CLI!")
+
+    async def do_task_and_increment(counter_name: str = "tasks"):
+        await asyncio.sleep(3)
+        print("✅ Task completed.")
+        menu.bottom_bar.increment_total_counter(counter_name)
+
+    # Register global logging hooks
+    menu.hooks.register(HookType.BEFORE, log_before)
+    menu.hooks.register(HookType.ON_SUCCESS, log_success)
+    menu.hooks.register(HookType.ON_ERROR, log_error)
+    menu.hooks.register(HookType.AFTER, log_after)
+
+    # Add a toggle to the bottom bar
+    menu.add_toggle("D", "Debug Mode", state=False)
+
+    # Add a counter to the bottom bar
+    menu.add_total_counter("tasks", "Tasks", current=0, total=5)
+
+    # Add static text to the bottom bar
+    menu.add_static("env", "🌐 Local Env")
+
+    # Add commands with help_text
+    menu.add_command(
+        key="S",
+        description="Say Hello",
+        help_text="Greets the user with a friendly hello message.",
+        action=Action("Hello", hello),
+        color=OneColors.CYAN,
+    )
+
+    menu.add_command(
+        key="G",
+        description="Say Goodbye",
+        help_text="Bids farewell and thanks the user for using the app.",
+        action=Action("Goodbye", goodbye),
+        color=OneColors.MAGENTA,
+    )
+
+    menu.add_command(
+        key="T",
+        description="Run a Task",
+        aliases=["task", "run"],
+        help_text="Performs a task and increments the counter by 1.",
+        action=do_task_and_increment,
+        args=("tasks",),
+        color=OneColors.GREEN,
+        spinner=True,
+    )
+
+    asyncio.run(menu.run())
+
+
+if __name__ == "__main__":
+    """
+    Entry point for the Falyx CLI demo application.
+    This function initializes the menu and runs it.
+    """
+    main()

falyx/menu.py

@@ -1,159 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `MenuOption` and `MenuOptionMap`, core components used to construct
-interactive menus within Falyx Actions such as `MenuAction` and `PromptMenuAction`.
-
-Each `MenuOption` represents a single actionable choice with a description,
-styling, and a bound `BaseAction`. `MenuOptionMap` manages collections of these
-options, including support for reserved keys like `B` (Back) and `X` (Exit), which
-can trigger navigation signals when selected.
-
-These constructs enable declarative and reusable menu definitions in both code and config.
-
-Key Components:
-- MenuOption: A user-facing label and action binding
-- MenuOptionMap: A key-aware container for menu options, with reserved entry support
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from prompt_toolkit.formatted_text import FormattedText
-
-from falyx.action.base_action import BaseAction
-from falyx.signals import BackSignal, QuitSignal
-from falyx.themes import OneColors
-from falyx.utils import CaseInsensitiveDict
-
-
-@dataclass
-class MenuOption:
-    """
-    Represents a single menu entry, including its label and associated action.
-
-    Used in conjunction with `MenuOptionMap` to define interactive command menus.
-    Each `MenuOption` contains a description (shown to the user), a `BaseAction`
-    to execute when selected, and an optional Rich-compatible style.
-
-    Attributes:
-        description (str): The label shown next to the menu key.
-        action (BaseAction): The action to invoke when selected.
-        style (str): A Rich-compatible color/style string for UI display.
-
-    Methods:
-        render(key): Returns a Rich-formatted string for menu display.
-        render_prompt(key): Returns a `FormattedText` object for use in prompt placeholders.
-
-    Raises:
-        TypeError: If `description` is not a string or `action` is not a `BaseAction`.
-    """
-
-    description: str
-    action: BaseAction
-    style: str = OneColors.WHITE
-
-    def __post_init__(self):
-        if not isinstance(self.description, str):
-            raise TypeError("MenuOption description must be a string.")
-        if not isinstance(self.action, BaseAction):
-            raise TypeError("MenuOption action must be a BaseAction instance.")
-
-    def render(self, key: str) -> str:
-        """Render the menu option for display."""
-        return f"[{OneColors.WHITE}][{key}][/] [{self.style}]{self.description}[/]"
-
-    def render_prompt(self, key: str) -> FormattedText:
-        """Render the menu option for prompt display."""
-        return FormattedText(
-            [(OneColors.WHITE, f"[{key}] "), (self.style, self.description)]
-        )
-
-
-class MenuOptionMap(CaseInsensitiveDict):
-    """
-    A container for storing and managing `MenuOption` objects by key.
-
-    `MenuOptionMap` is used to define the set of available choices in a
-    Falyx menu. Keys are case-insensitive and mapped to `MenuOption` instances.
-    The map supports special reserved keys—`B` for Back and `X` for Exit—unless
-    explicitly disabled via `allow_reserved=False`.
-
-    This class enforces strict typing of menu options and prevents accidental
-    overwrites of reserved keys.
-
-    Args:
-        options (dict[str, MenuOption] | None): Initial options to populate the menu.
-        allow_reserved (bool): If True, allows overriding reserved keys.
-
-    Methods:
-        items(include_reserved): Returns an iterable of menu options,
-                                 optionally filtering out reserved keys.
-
-    Raises:
-        TypeError: If non-`MenuOption` values are assigned.
-        ValueError: If attempting to use or delete a reserved key without permission.
-    """
-
-    RESERVED_KEYS = {"B", "X"}
-
-    def __init__(
-        self,
-        options: dict[str, MenuOption] | None = None,
-        allow_reserved: bool = False,
-    ):
-        super().__init__()
-        self.allow_reserved = allow_reserved
-        if options:
-            self.update(options)
-        self._inject_reserved_defaults()
-
-    def _inject_reserved_defaults(self):
-        from falyx.action import SignalAction
-
-        self._add_reserved(
-            "B",
-            MenuOption("Back", SignalAction("Back", BackSignal()), OneColors.DARK_YELLOW),
-        )
-        self._add_reserved(
-            "X",
-            MenuOption("Exit", SignalAction("Quit", QuitSignal()), OneColors.DARK_RED),
-        )
-
-    def _add_reserved(self, key: str, option: MenuOption) -> None:
-        """Add a reserved key, bypassing validation."""
-        norm_key = key.upper()
-        super().__setitem__(norm_key, option)
-
-    def __setitem__(self, key: str, option: MenuOption) -> None:
-        if not isinstance(option, MenuOption):
-            raise TypeError(f"Value for key '{key}' must be a MenuOption.")
-        norm_key = key.upper()
-        if norm_key in self.RESERVED_KEYS and not self.allow_reserved:
-            raise ValueError(
-                f"Key '{key}' is reserved and cannot be used in MenuOptionMap."
-            )
-        super().__setitem__(norm_key, option)
-
-    def __delitem__(self, key: str) -> None:
-        if key.upper() in self.RESERVED_KEYS and not self.allow_reserved:
-            raise ValueError(f"Cannot delete reserved option '{key}'.")
-        super().__delitem__(key)
-
-    def update(self, other=None, **kwargs):
-        """Update the selection options with another dictionary."""
-        if other:
-            for key, option in other.items():
-                if not isinstance(option, MenuOption):
-                    raise TypeError(f"Value for key '{key}' must be a SelectionOption.")
-                self[key] = option
-        for key, option in kwargs.items():
-            if not isinstance(option, MenuOption):
-                raise TypeError(f"Value for key '{key}' must be a SelectionOption.")
-            self[key] = option
-
-    def items(self, include_reserved: bool = True):
-        for key, option in super().items():
-            if not include_reserved and key in self.RESERVED_KEYS:
-                continue
-            yield key, option

falyx/mode.py

@@ -1,12 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `FalyxMode`, an enum representing the different modes of operation for Falyx.
-"""
-from enum import Enum
-
-
-class FalyxMode(Enum):
-    MENU = "menu"
-    RUN = "run"
-    PREVIEW = "preview"
-    RUN_ALL = "run-all"

falyx/options_manager.py

@@ -1,55 +1,15 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""options_manager.py"""
-"""
-Manages global or scoped CLI options across namespaces for Falyx commands.
-
-The `OptionsManager` provides a centralized interface for retrieving, setting, toggling,
-and introspecting options defined in `argparse.Namespace` objects. It is used internally
-by Falyx to pass and resolve runtime flags like `--verbose`, `--force-confirm`, etc.
-
-Each option is stored under a namespace key (e.g., "cli_args", "user_config") to
-support multiple sources of configuration.
-
-Key Features:
-- Safe getter/setter for typed option resolution
-- Toggle support for boolean options (used by bottom bar toggles, etc.)
-- Callable getter/toggler wrappers for dynamic UI bindings
-- Namespace merging via `from_namespace`
-
-Typical Usage:
-    options = OptionsManager()
-    options.from_namespace(args, namespace_name="cli_args")
-    if options.get("verbose"):
-        ...
-    options.toggle("force_confirm")
-    value_fn = options.get_value_getter("dry_run")
-    toggle_fn = options.get_toggle_function("debug")
-
-Used by:
-- Falyx CLI runtime configuration
-- Bottom bar toggles
-- Dynamic flag injection into commands and actions
-"""
 
 from argparse import Namespace
 from collections import defaultdict
 from typing import Any, Callable
 
-from falyx.logger import logger
+from falyx.utils import logger
-from falyx.spinner_manager import SpinnerManager
 
 
 class OptionsManager:
-    """
+    def __init__(self, namespaces: list[tuple[str, Namespace]] = None) -> None:
-    Manages CLI option state across multiple argparse namespaces.
+        self.options = defaultdict(lambda: Namespace())
-
-    Allows dynamic retrieval, setting, toggling, and introspection of command-line
-    options. Supports named namespaces (e.g., "cli_args") and is used throughout
-    Falyx for runtime configuration and bottom bar toggle integration.
-    """
-
-    def __init__(self, namespaces: list[tuple[str, Namespace]] | None = None) -> None:
-        self.options: defaultdict = defaultdict(Namespace)
-        self.spinners = SpinnerManager()
         if namespaces:
             for namespace_name, namespace in namespaces:
                 self.from_namespace(namespace, namespace_name)
@@ -65,7 +25,9 @@ class OptionsManager:
         """Get the value of an option."""
         return getattr(self.options[namespace_name], option_name, default)
 
-    def set(self, option_name: str, value: Any, namespace_name: str = "cli_args") -> None:
+    def set(
+        self, option_name: str, value: Any, namespace_name: str = "cli_args"
+    ) -> None:
         """Set the value of an option."""
         setattr(self.options[namespace_name], option_name, value)
 
@@ -81,9 +43,7 @@ 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(
+        logger.debug(f"Toggled '{option_name}' in '{namespace_name}' to {not current}")
-            "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/parser/__init__.py

@@ -1,21 +0,0 @@
-"""
-Falyx CLI Framework
-
-Copyright (c) 2025 rtj.dev LLC.
-Licensed under the MIT License. See LICENSE file for details.
-"""
-
-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__ = [
-    "Argument",
-    "ArgumentAction",
-    "CommandArgumentParser",
-    "get_arg_parsers",
-    "get_root_parser",
-    "get_subparsers",
-    "FalyxParsers",
-]

falyx/parser/argument.py

@@ -1,151 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines the `Argument` dataclass used by `CommandArgumentParser` to represent
-individual command-line parameters in a structured, introspectable format.
-
-Each `Argument` instance describes one CLI input, including its flags, type,
-default behavior, action semantics, help text, and optional resolver integration
-for dynamic evaluation.
-
-Falyx uses this structure to support a declarative CLI design, providing flexible
-argument parsing with full support for positional and keyword arguments, coercion,
-completion, and help rendering.
-
-Arguments should be created using `CommandArgumentParser.add_argument()`
-or defined in YAML configurations, allowing for rich introspection and validation.
-
-Key Attributes:
-- `flags`: One or more short/long flags (e.g. `-v`, `--verbose`)
-- `dest`: Internal name used as the key in parsed results
-- `action`: `ArgumentAction` enum describing behavior (store, count, resolve, etc.)
-- `type`: Type coercion or callable converter
-- `default`: Optional fallback value
-- `choices`: Allowed values, if restricted
-- `nargs`: Number of expected values (`int`, `'?'`, `'*'`, `'+'`)
-- `positional`: Whether this argument is positional (no flag)
-- `resolver`: Optional `BaseAction` to resolve argument value dynamically
-- `lazy_resolver`: Whether to defer resolution until needed
-- `suggestions`: Optional completions for interactive shells
-
-Used By:
-- `CommandArgumentParser`
-- `Falyx` runtime parsing
-- Rich-based CLI help generation
-- Completion and preview suggestions
-"""
-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.
-
-    Attributes:
-        flags (tuple[str, ...]): Short and long flags for the argument.
-        dest (str): The destination name for the argument.
-        action (ArgumentAction): The action to be taken when the argument is encountered.
-        type (Any): The type of the argument (e.g., str, int, float) or a callable that converts the argument value.
-        default (Any): The default value if the argument is not provided.
-        choices (list[str] | None): A list of valid choices for the argument.
-        required (bool): True if the argument is required, False otherwise.
-        help (str): Help text for the argument.
-        nargs (int | str | None): Number of arguments expected. Can be an int, '?', '*', '+', or None.
-        positional (bool): True if the argument is positional (no leading - or -- in flags), False otherwise.
-        resolver (BaseAction | None):
-            An action object that resolves the argument, if applicable.
-        lazy_resolver (bool): True if the resolver should be called lazily, False otherwise
-        suggestions (list[str] | None): Optional completions for interactive shells
-    """
-
-    flags: tuple[str, ...]
-    dest: str
-    action: ArgumentAction = ArgumentAction.STORE
-    type: Any = str
-    default: Any = None
-    choices: list[str] | None = None
-    required: bool = False
-    help: str = ""
-    nargs: int | str | None = None
-    positional: bool = False
-    resolver: BaseAction | None = None
-    lazy_resolver: bool = False
-    suggestions: list[str] | None = None
-
-    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,
-                ArgumentAction.ACTION,
-            )
-            and not self.positional
-        ):
-            choice_text = self.dest.upper()
-        elif self.action in (
-            ArgumentAction.STORE,
-            ArgumentAction.APPEND,
-            ArgumentAction.EXTEND,
-            ArgumentAction.ACTION,
-        ) 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/parser/argument_action.py

@@ -1,94 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines `ArgumentAction`, an enum used to standardize the behavior of CLI arguments
-defined within Falyx command configurations.
-
-Each member of this enum maps to a valid `argparse` like actions or Falyx-specific
-behavior used during command argument parsing. This allows declarative configuration
-of argument behavior when building CLI commands via `CommandArgumentParser`.
-
-Supports alias coercion for shorthand or config-friendly values, and provides
-a consistent interface for downstream argument handling logic.
-
-Exports:
-    - ArgumentAction: Enum of allowed actions for command arguments.
-
-Example:
-    ArgumentAction("store_true") → ArgumentAction.STORE_TRUE
-    ArgumentAction("true")       → ArgumentAction.STORE_TRUE (via alias)
-    ArgumentAction("optional")   → ArgumentAction.STORE_BOOL_OPTIONAL
-"""
-from __future__ import annotations
-
-from enum import Enum
-
-
-class ArgumentAction(Enum):
-    """
-    Defines the action to be taken when the argument is encountered.
-
-    This enum mirrors the core behavior of Python's `argparse` actions, with a few
-    Falyx-specific extensions. It is used when defining command-line arguments for
-    `CommandArgumentParser` or YAML-based argument definitions.
-
-    Members:
-        ACTION: Invoke a callable as the argument handler (Falyx extension).
-        STORE: Store the provided value (default).
-        STORE_TRUE: Store `True` if the flag is present.
-        STORE_FALSE: Store `False` if the flag is present.
-        STORE_BOOL_OPTIONAL: Accept an optional bool (e.g., `--debug` or `--no-debug`).
-        APPEND: Append the value to a list.
-        EXTEND: Extend a list with multiple values.
-        COUNT: Count the number of occurrences.
-        HELP: Display help and exit.
-        TLDR: Display brief examples and exit.
-
-    Aliases:
-        - "true" → "store_true"
-        - "false" → "store_false"
-        - "optional" → "store_bool_optional"
-
-    Example:
-        ArgumentAction("true") → ArgumentAction.STORE_TRUE
-    """
-
-    ACTION = "action"
-    STORE = "store"
-    STORE_TRUE = "store_true"
-    STORE_FALSE = "store_false"
-    STORE_BOOL_OPTIONAL = "store_bool_optional"
-    APPEND = "append"
-    EXTEND = "extend"
-    COUNT = "count"
-    HELP = "help"
-    TLDR = "tldr"
-
-    @classmethod
-    def choices(cls) -> list[ArgumentAction]:
-        """Return a list of all argument actions."""
-        return list(cls)
-
-    @classmethod
-    def _get_alias(cls, value: str) -> str:
-        aliases = {
-            "optional": "store_bool_optional",
-            "true": "store_true",
-            "false": "store_false",
-        }
-        return aliases.get(value, value)
-
-    @classmethod
-    def _missing_(cls, value: object) -> ArgumentAction:
-        if not isinstance(value, str):
-            raise ValueError(f"Invalid {cls.__name__}: {value!r}")
-        normalized = value.strip().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 {cls.__name__}: '{value}'. Must be one of: {valid}")
-
-    def __str__(self) -> str:
-        """Return the string representation of the argument action."""
-        return self.value

falyx/parser/parser_types.py

@@ -1,52 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Type utilities and argument state models for Falyx's custom CLI argument parser.
-
-This module provides specialized helpers and data structures used by
-the `CommandArgumentParser` to handle non-standard parsing behavior.
-
-Contents:
-- `true_none` / `false_none`: Type coercion utilities that allow tri-state boolean
-  semantics (True, False, None). These are especially useful for supporting
-  `--flag` / `--no-flag` optional booleans in CLI arguments.
-- `ArgumentState`: Tracks whether an `Argument` has been consumed during parsing.
-- `TLDRExample`: A structured example for showing usage snippets and descriptions,
-   used in TLDR views.
-
-These tools support richer expressiveness and user-friendly ergonomics in
-Falyx's declarative command-line interfaces.
-"""
-from dataclasses import dataclass
-from typing import Any
-
-from falyx.parser.argument import Argument
-
-
-@dataclass
-class ArgumentState:
-    """Tracks an argument and whether it has been consumed."""
-
-    arg: Argument
-    consumed: bool = False
-
-
-@dataclass(frozen=True)
-class TLDRExample:
-    """Represents a usage example for TLDR output."""
-
-    usage: str
-    description: str
-
-
-def true_none(value: Any) -> bool | None:
-    """Return True if value is not None, else None."""
-    if value is None:
-        return None
-    return True
-
-
-def false_none(value: Any) -> bool | None:
-    """Return False if value is not None, else None."""
-    if value is None:
-        return None
-    return False

falyx/parser/parsers.py

@@ -1,396 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Provides the argument parser infrastructure for the Falyx CLI.
-
-This module defines the `FalyxParsers` dataclass and related utilities for building
-structured CLI interfaces with argparse. It supports top-level CLI commands like
-`run`, `run-all`, `preview`, `list`, and `version`, and integrates seamlessly with
-registered `Command` objects for dynamic help, usage generation, and argument handling.
-
-Key Components:
-- `FalyxParsers`: Container for all CLI subparsers.
-- `get_arg_parsers()`: Factory for generating full parser suite.
-- `get_root_parser()`: Creates the root-level CLI parser with global options.
-- `get_subparsers()`: Helper to attach subcommand parsers to the root parser.
-
-Used internally by the Falyx CLI `run()` entry point to parse arguments and route
-execution across commands and workflows.
-"""
-
-from argparse import (
-    REMAINDER,
-    ArgumentParser,
-    Namespace,
-    RawDescriptionHelpFormatter,
-    _SubParsersAction,
-)
-from dataclasses import asdict, dataclass
-from typing import Any, Sequence
-
-from falyx.command import Command
-
-
-@dataclass
-class FalyxParsers:
-    """Defines the argument parsers for the Falyx CLI."""
-
-    root: ArgumentParser
-    subparsers: _SubParsersAction
-    run: ArgumentParser
-    run_all: ArgumentParser
-    preview: ArgumentParser
-    list: ArgumentParser
-    version: ArgumentParser
-
-    def parse_args(self, args: Sequence[str] | None = None) -> Namespace:
-        """Parse the command line arguments."""
-        return self.root.parse_args(args)
-
-    def as_dict(self) -> dict[str, ArgumentParser]:
-        """Convert the FalyxParsers instance to a dictionary."""
-        return asdict(self)
-
-    def get_parser(self, name: str) -> ArgumentParser | None:
-        """Get the parser by name."""
-        return self.as_dict().get(name)
-
-
-def get_root_parser(
-    prog: str | None = "falyx",
-    usage: str | None = None,
-    description: str | None = "Falyx CLI - Run structured async command workflows.",
-    epilog: str | None = "Tip: Use 'falyx run ?' to show available commands.",
-    parents: Sequence[ArgumentParser] | None = None,
-    prefix_chars: str = "-",
-    fromfile_prefix_chars: str | None = None,
-    argument_default: Any = None,
-    conflict_handler: str = "error",
-    add_help: bool = True,
-    allow_abbrev: bool = True,
-    exit_on_error: bool = True,
-) -> ArgumentParser:
-    """
-    Construct the root-level ArgumentParser for the Falyx CLI.
-
-    This parser handles global arguments shared across subcommands and can serve
-    as the base parser for the Falyx CLI or standalone applications. It includes
-    options for verbosity, debug logging, and version output.
-
-    Args:
-        prog (str | None): Name of the program (e.g., 'falyx').
-        usage (str | None): Optional custom usage string.
-        description (str | None): Description shown in the CLI help.
-        epilog (str | None): Message displayed at the end of help output.
-        parents (Sequence[ArgumentParser] | None): Optional parent parsers.
-        prefix_chars (str): Characters to denote optional arguments (default: "-").
-        fromfile_prefix_chars (str | None): Prefix to indicate argument file input.
-        argument_default (Any): Global default value for arguments.
-        conflict_handler (str): Strategy to resolve conflicting argument names.
-        add_help (bool): Whether to include help (`-h/--help`) in this parser.
-        allow_abbrev (bool): Allow abbreviated long options.
-        exit_on_error (bool): Exit immediately on error or raise an exception.
-
-    Returns:
-        ArgumentParser: The root parser with global options attached.
-
-    Notes:
-        ```
-        Includes the following arguments:
-            --never-prompt       : Run in non-interactive mode.
-            -v / --verbose       : Enable debug logging.
-            --debug-hooks        : Enable hook lifecycle debug logs.
-            --version            : Print the Falyx version.
-        ```
-    """
-    parser = ArgumentParser(
-        prog=prog,
-        usage=usage,
-        description=description,
-        epilog=epilog,
-        parents=parents if parents else [],
-        prefix_chars=prefix_chars,
-        fromfile_prefix_chars=fromfile_prefix_chars,
-        argument_default=argument_default,
-        conflict_handler=conflict_handler,
-        add_help=add_help,
-        allow_abbrev=allow_abbrev,
-        exit_on_error=exit_on_error,
-    )
-    parser.add_argument(
-        "--never-prompt",
-        action="store_true",
-        help="Run in non-interactive mode with all prompts bypassed.",
-    )
-    parser.add_argument(
-        "-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=f"Show {prog} version")
-    return parser
-
-
-def get_subparsers(
-    parser: ArgumentParser,
-    title: str = "Falyx Commands",
-    description: str | None = "Available commands for the Falyx CLI.",
-) -> _SubParsersAction:
-    """
-    Create and return a subparsers object for registering Falyx CLI subcommands.
-
-    This function adds a `subparsers` block to the given root parser, enabling
-    structured subcommands such as `run`, `run-all`, `preview`, etc.
-
-    Args:
-        parser (ArgumentParser): The root parser to attach the subparsers to.
-        title (str): Title used in help output to group subcommands.
-        description (str | None): Optional text describing the group of subcommands.
-
-    Returns:
-        _SubParsersAction: The subparsers object that can be used to add new CLI subcommands.
-
-    Raises:
-        TypeError: If `parser` is not an instance of `ArgumentParser`.
-
-    Example:
-        ```python
-        >>> parser = get_root_parser()
-        >>> subparsers = get_subparsers(parser, title="Available Commands")
-        >>> subparsers.add_parser("run", help="Run a Falyx command")
-        ```
-    """
-    if not isinstance(parser, ArgumentParser):
-        raise TypeError("parser must be an instance of ArgumentParser")
-    subparsers = parser.add_subparsers(
-        title=title,
-        description=description,
-        dest="command",
-    )
-    return subparsers
-
-
-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
-    ) = "Tip: Use 'falyx run ?[COMMAND]' to preview any command from the CLI.",
-    parents: Sequence[ArgumentParser] | None = None,
-    prefix_chars: str = "-",
-    fromfile_prefix_chars: str | None = None,
-    argument_default: Any = None,
-    conflict_handler: str = "error",
-    add_help: bool = True,
-    allow_abbrev: bool = True,
-    exit_on_error: bool = True,
-    commands: dict[str, Command] | None = None,
-    root_parser: ArgumentParser | None = None,
-    subparsers: _SubParsersAction | None = None,
-) -> FalyxParsers:
-    """
-    Create and return the full suite of argument parsers used by the Falyx CLI.
-
-    This function builds the root parser and all subcommand parsers used for structured
-    CLI workflows in Falyx. It supports standard subcommands including `run`, `run-all`,
-    `preview`, `list`, and `version`, and integrates with registered `Command` objects
-    to populate dynamic help and usage documentation.
-
-    Args:
-        prog (str | None): Program name to display in help and usage messages.
-        usage (str | None): Optional usage message to override the default.
-        description (str | None): Description for the CLI root parser.
-        epilog (str | None): Epilog message shown after the help text.
-        parents (Sequence[ArgumentParser] | None): Optional parent parsers.
-        prefix_chars (str): Characters that prefix optional arguments.
-        fromfile_prefix_chars (str | None): Prefix character for reading args from file.
-        argument_default (Any): Default value for arguments if not specified.
-        conflict_handler (str): Strategy for resolving conflicting arguments.
-        add_help (bool): Whether to add the `-h/--help` option to the root parser.
-        allow_abbrev (bool): Whether to allow abbreviated long options.
-        exit_on_error (bool): Whether the parser exits on error or raises.
-        commands (dict[str, Command] | None): Optional dictionary of registered commands
-            to populate help and subcommand descriptions dynamically.
-        root_parser (ArgumentParser | None): Custom root parser to use instead of building one.
-        subparsers (_SubParsersAction | None): Optional existing subparser object to extend.
-
-    Returns:
-        FalyxParsers: A structured container of all parsers, including `run`, `run-all`,
-                      `preview`, `list`, `version`, and the root parser.
-
-    Raises:
-        TypeError: If `root_parser` is not an instance of ArgumentParser or
-                   `subparsers` is not an instance of _SubParsersAction.
-
-    Example:
-        ```python
-        >>> parsers = get_arg_parsers(commands=my_command_dict)
-        >>> args = parsers.root.parse_args()
-        ```
-
-    Notes:
-        - This function integrates dynamic command usage and descriptions if the
-          `commands` argument is provided.
-        - The `run` parser supports additional options for retry logic and confirmation
-          prompts.
-        - The `run-all` parser executes all commands matching a tag.
-        - Use `falyx run ?[COMMAND]` from the CLI to preview a command.
-    """
-    if epilog is None:
-        epilog = f"Tip: Use '{prog} run ?' to show available commands."
-    if root_parser is None:
-        parser = get_root_parser(
-            prog=prog,
-            usage=usage,
-            description=description,
-            epilog=epilog,
-            parents=parents,
-            prefix_chars=prefix_chars,
-            fromfile_prefix_chars=fromfile_prefix_chars,
-            argument_default=argument_default,
-            conflict_handler=conflict_handler,
-            add_help=add_help,
-            allow_abbrev=allow_abbrev,
-            exit_on_error=exit_on_error,
-        )
-    else:
-        if not isinstance(root_parser, ArgumentParser):
-            raise TypeError("root_parser must be an instance of ArgumentParser")
-        parser = root_parser
-
-    if subparsers is None:
-        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")
-
-    run_description = ["Run a command by its key or alias.\n"]
-    run_description.append("commands:")
-    if isinstance(commands, dict):
-        for command in commands.values():
-            run_description.append(command.usage)
-            command_description = command.help_text or command.description
-            run_description.append(f"{' '*24}{command_description}")
-    run_epilog = (
-        f"Tip: Use '{prog} run ?[COMMAND]' to preview commands by their key or alias."
-    )
-    run_parser = subparsers.add_parser(
-        "run",
-        help="Run a specific command",
-        description="\n".join(run_description),
-        epilog=run_epilog,
-        formatter_class=RawDescriptionHelpFormatter,
-    )
-    run_parser.add_argument(
-        "name", help="Run a command by its key or alias", metavar="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
-    )
-    run_parser.add_argument(
-        "--retry-delay",
-        type=float,
-        help="Initial delay between retries in (seconds)",
-        default=0,
-    )
-    run_parser.add_argument(
-        "--retry-backoff", type=float, help="Backoff factor for retries", default=0
-    )
-    run_group = run_parser.add_mutually_exclusive_group(required=False)
-    run_group.add_argument(
-        "-c",
-        "--confirm",
-        dest="force_confirm",
-        action="store_true",
-        help="Force confirmation prompts",
-    )
-    run_group.add_argument(
-        "-s",
-        "--skip-confirm",
-        dest="skip_confirm",
-        action="store_true",
-        help="Skip confirmation prompts",
-    )
-
-    run_parser.add_argument(
-        "command_args",
-        nargs=REMAINDER,
-        help="Arguments to pass to the command (if applicable)",
-        metavar="ARGS",
-    )
-
-    run_all_parser = subparsers.add_parser(
-        "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
-    )
-    run_all_parser.add_argument(
-        "--retry-delay",
-        type=float,
-        help="Initial delay between retries in (seconds)",
-        default=0,
-    )
-    run_all_parser.add_argument(
-        "--retry-backoff", type=float, help="Backoff factor for retries", default=0
-    )
-    run_all_group = run_all_parser.add_mutually_exclusive_group(required=False)
-    run_all_group.add_argument(
-        "-c",
-        "--confirm",
-        dest="force_confirm",
-        action="store_true",
-        help="Force confirmation prompts",
-    )
-    run_all_group.add_argument(
-        "-s",
-        "--skip-confirm",
-        dest="skip_confirm",
-        action="store_true",
-        help="Skip confirmation prompts",
-    )
-
-    preview_parser = subparsers.add_parser(
-        "preview", help="Preview a command without running it"
-    )
-    preview_parser.add_argument("name", help="Key, alias, or description of the command")
-
-    list_parser = subparsers.add_parser(
-        "list", help="List all available commands with tags"
-    )
-
-    list_parser.add_argument(
-        "-t", "--tag", help="Filter commands by tag (case-insensitive)", default=None
-    )
-
-    version_parser = subparsers.add_parser("version", help=f"Show {prog} version")
-
-    return FalyxParsers(
-        root=parser,
-        subparsers=subparsers,
-        run=run_parser,
-        run_all=run_all_parser,
-        preview=preview_parser,
-        list=list_parser,
-        version=version_parser,
-    )

falyx/parser/signature.py

@@ -1,105 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Provides utilities for introspecting Python callables and extracting argument
-metadata compatible with Falyx's `CommandArgumentParser`.
-
-This module is primarily used to auto-generate command argument definitions from
-function signatures, enabling seamless integration of plain functions into the
-Falyx CLI with minimal boilerplate.
-
-Functions:
-- infer_args_from_func: Generate a list of argument definitions based on a function's signature.
-"""
-import inspect
-from typing import Any, Callable
-
-from falyx.logger import logger
-
-
-def infer_args_from_func(
-    func: Callable[[Any], Any] | None,
-    arg_metadata: dict[str, str | dict[str, Any]] | None = None,
-) -> list[dict[str, Any]]:
-    """
-    Infer CLI-style argument definitions from a function signature.
-
-    This utility inspects the parameters of a function and returns a list of dictionaries,
-    each of which can be passed to `CommandArgumentParser.add_argument()`.
-
-    Args:
-        func (Callable | None): The function to inspect.
-        arg_metadata (dict | None): Optional metadata overrides for help text, type hints,
-                                    choices, and suggestions for each parameter.
-
-    Returns:
-        list[dict[str, Any]]: A list of argument definitions inferred from the function.
-    """
-    if not callable(func):
-        logger.debug("Provided argument is not callable: %s", func)
-        return []
-    arg_metadata = arg_metadata or {}
-    signature = inspect.signature(func)
-    arg_defs = []
-
-    for name, param in signature.parameters.items():
-        raw_metadata = arg_metadata.get(name, {})
-        metadata = (
-            {"help": raw_metadata} if isinstance(raw_metadata, str) else raw_metadata
-        )
-        if param.kind not in (
-            inspect.Parameter.POSITIONAL_ONLY,
-            inspect.Parameter.POSITIONAL_OR_KEYWORD,
-            inspect.Parameter.KEYWORD_ONLY,
-        ):
-            continue
-
-        if metadata.get("type"):
-            arg_type = metadata["type"]
-        else:
-            arg_type = (
-                param.annotation
-                if param.annotation is not inspect.Parameter.empty
-                else str
-            )
-            if isinstance(arg_type, str):
-                arg_type = str
-        default = param.default if param.default is not inspect.Parameter.empty else None
-        is_required = param.default is inspect.Parameter.empty
-        if is_required:
-            flags = [f"{name.replace('_', '-')}"]
-        else:
-            flags = [f"--{name.replace('_', '-')}"]
-        action = "store"
-        nargs: int | str | None = None
-
-        if arg_type is bool:
-            if param.default is False:
-                action = "store_true"
-                default = None
-            elif param.default is True:
-                action = "store_false"
-                default = None
-
-        if arg_type is list:
-            action = "append"
-            if is_required:
-                nargs = "+"
-            else:
-                nargs = "*"
-
-        arg_defs.append(
-            {
-                "flags": flags,
-                "dest": name,
-                "type": arg_type,
-                "default": default,
-                "required": is_required,
-                "nargs": nargs,
-                "action": action,
-                "help": metadata.get("help", ""),
-                "choices": metadata.get("choices"),
-                "suggestions": metadata.get("suggestions"),
-            }
-        )
-
-    return arg_defs

falyx/parser/utils.py

@@ -1,164 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Contains value coercion and signature comparison utilities for Falyx argument parsing.
-
-This module provides type coercion functions for converting string input into expected
-Python types, including `Enum`, `bool`, `datetime`, and `Literal`. It also supports
-checking whether multiple actions share identical inferred argument definitions.
-
-Functions:
-- coerce_bool: Convert a string to a boolean.
-- coerce_enum: Convert a string or raw value to an Enum instance.
-- coerce_value: General-purpose coercion to a target type (including nested unions, enums, etc.).
-- same_argument_definitions: Check if multiple callables share the same argument structure.
-"""
-import types
-from datetime import datetime
-from enum import EnumMeta
-from typing import Any, Literal, Union, get_args, get_origin
-
-from dateutil import parser as date_parser
-
-from falyx.action.base_action import BaseAction
-from falyx.logger import logger
-from falyx.parser.signature import infer_args_from_func
-
-
-def coerce_bool(value: str) -> bool:
-    """
-    Convert a string to a boolean.
-
-    Accepts various truthy and falsy representations such as 'true', 'yes', '0', 'off', etc.
-
-    Args:
-        value (str): The input string or boolean.
-
-    Returns:
-        bool: Parsed boolean result.
-    """
-    if isinstance(value, bool):
-        return value
-    value = value.strip().lower()
-    if value in {"true", "t", "1", "yes", "on"}:
-        return True
-    elif value in {"false", "f", "0", "no", "off"}:
-        return False
-    return bool(value)
-
-
-def coerce_enum(value: Any, enum_type: EnumMeta) -> Any:
-    """
-    Convert a raw value or string to an Enum instance.
-
-    Tries to resolve by name, value, or coerced base type.
-
-    Args:
-        value (Any): The input value to convert.
-        enum_type (EnumMeta): The target Enum class.
-
-    Returns:
-        Enum: The corresponding Enum instance.
-
-    Raises:
-        ValueError: If the value cannot be resolved to a valid Enum member.
-    """
-    if isinstance(value, enum_type):
-        return value
-
-    if isinstance(value, str):
-        try:
-            return enum_type[value]
-        except KeyError:
-            pass
-
-    base_type = type(next(iter(enum_type)).value)
-    try:
-        coerced_value = base_type(value)
-        return enum_type(coerced_value)
-    except (ValueError, TypeError):
-        values = [str(enum.value) for enum in enum_type]
-        raise ValueError(f"'{value}' should be one of {{{', '.join(values)}}}") from None
-
-
-def coerce_value(value: str, target_type: type) -> Any:
-    """
-    Attempt to convert a string to the given target type.
-
-    Handles complex typing constructs such as Union, Literal, Enum, and datetime.
-
-    Args:
-        value (str): The input string to convert.
-        target_type (type): The desired type.
-
-    Returns:
-        Any: The coerced value.
-
-    Raises:
-        ValueError: If conversion fails or the value is invalid.
-    """
-    origin = get_origin(target_type)
-    args = get_args(target_type)
-
-    if origin is Literal:
-        if value not in args:
-            raise ValueError(
-                f"Value '{value}' is not a valid literal for type {target_type}"
-            )
-        return value
-
-    if isinstance(target_type, types.UnionType) or get_origin(target_type) is Union:
-        for arg in args:
-            try:
-                return coerce_value(value, arg)
-            except Exception:
-                continue
-        raise ValueError(f"Value '{value}' could not be coerced to any of {args}")
-
-    if isinstance(target_type, EnumMeta):
-        return coerce_enum(value, target_type)
-
-    if target_type is bool:
-        return coerce_bool(value)
-
-    if target_type is datetime:
-        try:
-            return date_parser.parse(value)
-        except ValueError as e:
-            raise ValueError(f"Value '{value}' could not be parsed as a datetime") from e
-
-    return target_type(value)
-
-
-def same_argument_definitions(
-    actions: list[Any],
-    arg_metadata: dict[str, str | dict[str, Any]] | None = None,
-) -> list[dict[str, Any]] | None:
-    """
-    Determine if multiple callables resolve to the same argument definitions.
-
-    This is used to infer whether actions in an ActionGroup or ProcessPool can share
-    a unified argument parser.
-
-    Args:
-        actions (list[Any]): A list of BaseAction instances or callables.
-        arg_metadata (dict | None): Optional overrides for argument help or type info.
-
-    Returns:
-        list[dict[str, Any]] | None: The shared argument definitions if consistent, else None.
-    """
-    arg_sets = []
-    for action in actions:
-        if isinstance(action, BaseAction):
-            infer_target, _ = action.get_infer_target()
-            arg_defs = infer_args_from_func(infer_target, arg_metadata)
-        elif callable(action):
-            arg_defs = infer_args_from_func(action, arg_metadata)
-        else:
-            logger.debug("Auto args unsupported for action: %s", action)
-            return None
-        arg_sets.append(arg_defs)
-
-    first = arg_sets[0]
-    if all(arg_set == first for arg_set in arg_sets[1:]):
-        return first
-    return None

falyx/parsers.py

@@ -0,0 +1,100 @@
+"""parsers.py
+This module contains the argument parsers used for the Falyx CLI.
+"""
+from argparse import ArgumentParser, HelpFormatter, Namespace
+from dataclasses import asdict, dataclass
+from typing import Any, Sequence
+
+
+@dataclass
+class FalyxParsers:
+    """Defines the argument parsers for the Falyx CLI."""
+    root: ArgumentParser
+    run: ArgumentParser
+    run_all: ArgumentParser
+    preview: ArgumentParser
+    list: ArgumentParser
+    version: ArgumentParser
+
+    def parse_args(self, args: Sequence[str] | None = None) -> Namespace:
+        """Parse the command line arguments."""
+        return self.root.parse_args(args)
+
+    def as_dict(self) -> dict[str, ArgumentParser]:
+        """Convert the FalyxParsers instance to a dictionary."""
+        return asdict(self)
+
+    def get_parser(self, name: str) -> ArgumentParser | None:
+        """Get the parser by name."""
+        return self.as_dict().get(name)
+
+
+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,
+        parents: Sequence[ArgumentParser] = [],
+        formatter_class: HelpFormatter = HelpFormatter,
+        prefix_chars: str = "-",
+        fromfile_prefix_chars: str | None = None,
+        argument_default: Any = None,
+        conflict_handler: str = "error",
+        add_help: bool = True,
+        allow_abbrev: bool = True,
+        exit_on_error: bool = True,
+    ) -> FalyxParsers:
+    """Returns the argument parser for the CLI."""
+    parser = ArgumentParser(
+        prog=prog,
+        usage=usage,
+        description=description,
+        epilog=epilog,
+        parents=parents,
+        formatter_class=formatter_class,
+        prefix_chars=prefix_chars,
+        fromfile_prefix_chars=fromfile_prefix_chars,
+        argument_default=argument_default,
+        conflict_handler=conflict_handler,
+        add_help=add_help,
+        allow_abbrev=allow_abbrev,
+        exit_on_error=exit_on_error,
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="Enable debug logging for Falyx.")
+    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")
+    subparsers = parser.add_subparsers(dest="command")
+
+    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("--retries", type=int, help="Number of retries on failure", default=0)
+    run_parser.add_argument("--retry-delay", type=float, help="Initial delay between retries in (seconds)", default=0)
+    run_parser.add_argument("--retry-backoff", type=float, help="Backoff factor for retries", default=0)
+    run_group = run_parser.add_mutually_exclusive_group(required=False)
+    run_group.add_argument("-c", "--confirm", dest="force_confirm", action="store_true", help="Force confirmation prompts")
+    run_group.add_argument("-s", "--skip-confirm", dest="skip_confirm", action="store_true", help="Skip confirmation prompts")
+
+    run_all_parser = subparsers.add_parser("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("--retries", type=int, help="Number of retries on failure", default=0)
+    run_all_parser.add_argument("--retry-delay", type=float, help="Initial delay between retries in (seconds)", default=0)
+    run_all_parser.add_argument("--retry-backoff", type=float, help="Backoff factor for retries", default=0)
+    run_all_group = run_all_parser.add_mutually_exclusive_group(required=False)
+    run_all_group.add_argument("-c", "--confirm", dest="force_confirm", action="store_true", help="Force confirmation prompts")
+    run_all_group.add_argument("-s", "--skip-confirm", dest="skip_confirm", action="store_true", help="Skip confirmation prompts")
+
+    preview_parser = subparsers.add_parser("preview", help="Preview a command without running it")
+    preview_parser.add_argument("name", help="Key, alias, or description of the command")
+
+    list_parser = subparsers.add_parser("list", help="List all available commands with tags")
+
+    version_parser = subparsers.add_parser("version", help="Show the Falyx version")
+
+    return FalyxParsers(
+        root=parser,
+        run=run_parser,
+        run_all=run_all_parser,
+        preview=preview_parser,
+        list=list_parser,
+        version=version_parser,
+    )

falyx/prompt_utils.py

@@ -1,89 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Utilities for user interaction prompts in the Falyx CLI framework.
-
-Provides asynchronous confirmation dialogs and helper logic to determine
-whether a user should be prompted based on command-line options.
-
-Includes:
-- `should_prompt_user()` for conditional prompt logic.
-- `confirm_async()` for interactive yes/no confirmation.
-"""
-
-from prompt_toolkit import PromptSession
-from prompt_toolkit.formatted_text import (
-    AnyFormattedText,
-    FormattedText,
-    StyleAndTextTuples,
-    merge_formatted_text,
-)
-from rich.console import Console
-from rich.text import Text
-
-from falyx.options_manager import OptionsManager
-from falyx.themes import OneColors
-from falyx.validators import yes_no_validator
-
-
-def should_prompt_user(
-    *,
-    confirm: bool,
-    options: OptionsManager,
-    namespace: str = "cli_args",
-):
-    """
-    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)
-
-    if never_prompt or skip_confirm:
-        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"
-
-
-def rich_text_to_prompt_text(text: Text | str | StyleAndTextTuples) -> StyleAndTextTuples:
-    """
-    Convert a Rich Text object to a list of (style, text) tuples
-    compatible with prompt_toolkit.
-    """
-    if isinstance(text, list):
-        if all(isinstance(pair, tuple) and len(pair) == 2 for pair in text):
-            return text
-        raise TypeError("Expected list of (style, text) tuples")
-
-    if isinstance(text, str):
-        text = Text.from_markup(text)
-
-    if not isinstance(text, Text):
-        raise TypeError("Expected str, rich.text.Text, or list of (style, text) tuples")
-
-    console = Console(color_system=None, file=None, width=999, legacy_windows=False)
-    segments = text.render(console)
-
-    prompt_fragments: StyleAndTextTuples = []
-    for segment in segments:
-        style = segment.style or ""
-        string = segment.text
-        if string:
-            prompt_fragments.append((str(style), string))
-    return prompt_fragments

falyx/protocols.py

@@ -1,32 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines structural protocols for advanced Falyx features.
-
-These runtime-checkable `Protocol` classes specify the expected interfaces for:
-- Factories that asynchronously return actions
-- Argument parsers used in dynamic command execution
-
-Used to support type-safe extensibility and plugin-like behavior without requiring
-explicit base classes.
-
-Protocols:
-- ActionFactoryProtocol: Async callable that returns a coroutine yielding a BaseAction.
-- ArgParserProtocol: Callable that accepts CLI-style args and returns (args, kwargs) tuple.
-"""
-from __future__ import annotations
-
-from typing import Any, Awaitable, Callable, Protocol, runtime_checkable
-
-from falyx.action.base_action import BaseAction
-
-
-@runtime_checkable
-class ActionFactoryProtocol(Protocol):
-    async def __call__(
-        self, *args: Any, **kwargs: Any
-    ) -> Callable[..., Awaitable[BaseAction]]: ...
-
-
-@runtime_checkable
-class ArgParserProtocol(Protocol):
-    def __call__(self, args: list[str]) -> tuple[tuple, dict]: ...

falyx/retry.py

@@ -1,71 +1,18 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""retry.py"""
-"""
-Implements retry logic for Falyx Actions using configurable retry policies.
-
-This module defines:
-- `RetryPolicy`: A configurable model controlling retry behavior (delay, backoff, jitter).
-- `RetryHandler`: A hook-compatible class that manages retry attempts for failed actions.
-
-Used to automatically retry transient failures in leaf-level `Action` objects
-when marked as retryable. Integrates with the Falyx hook lifecycle via `on_error`.
-
-Supports:
-- Exponential backoff with optional jitter
-- Manual or declarative policy control
-- Per-action retry logging and recovery
-
-Example:
-    handler = RetryHandler(RetryPolicy(max_retries=5, delay=1.0))
-    action.hooks.register(HookType.ON_ERROR, handler.retry_on_error)
-"""
-from __future__ import annotations
-
 import asyncio
-import random
 
 from pydantic import BaseModel, Field
 
 from falyx.context import ExecutionContext
-from falyx.logger import logger
+from falyx.utils import logger
 
 
 class RetryPolicy(BaseModel):
-    """
-    Defines a retry strategy for Falyx `Action` objects.
-
-    This model controls whether an action should be retried on failure, and how:
-    - `max_retries`: Maximum number of retry attempts.
-    - `delay`: Initial wait time before the first retry (in seconds).
-    - `backoff`: Multiplier applied to the delay after each failure (≥ 1.0).
-    - `jitter`: Optional random noise added/subtracted from delay to reduce thundering herd issues.
-    - `enabled`: Whether this policy is currently active.
-
-    Retry is only triggered for leaf-level `Action` instances marked with `is_retryable=True`
-    and registered with an appropriate `RetryHandler`.
-
-    Example:
-        RetryPolicy(max_retries=3, delay=1.0, backoff=2.0, jitter=0.2, enabled=True)
-
-    Use `enable_policy()` to activate the policy after construction.
-
-    See Also:
-        - `RetryHandler`: Executes retry logic based on this configuration.
-        - `HookType.ON_ERROR`: The hook type used to trigger retries.
-    """
-
     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)
-    jitter: float = Field(default=0.0, ge=0.0)
     enabled: bool = False
 
-    def enable_policy(self) -> None:
-        """
-        Enable the retry policy.
-        :return: None
-        """
-        self.enabled = True
-
     def is_active(self) -> bool:
         """
         Check if the retry policy is active.
@@ -75,48 +22,18 @@ class RetryPolicy(BaseModel):
 
 
 class RetryHandler:
-    """
+    def __init__(self, policy: RetryPolicy=RetryPolicy()):
-    Executes retry logic for Falyx actions using a provided `RetryPolicy`.
-
-    This class is intended to be registered as an `on_error` hook. It will
-    re-attempt the failed `Action`'s `action` method using the args/kwargs from
-    the failed context, following exponential backoff and optional jitter.
-
-    Only supports retrying leaf `Action` instances (not ChainedAction or ActionGroup)
-    where `is_retryable=True`.
-
-    Attributes:
-        policy (RetryPolicy): The retry configuration controlling timing and limits.
-
-    Example:
-        handler = RetryHandler(RetryPolicy(max_retries=3, delay=1.0, enabled=True))
-        action.hooks.register(HookType.ON_ERROR, handler.retry_on_error)
-
-    Notes:
-        - Retries are not triggered if the policy is disabled or `max_retries=0`.
-        - All retry attempts and final failure are logged automatically.
-    """
-
-    def __init__(self, policy: RetryPolicy = RetryPolicy()):
         self.policy = policy
 
-    def enable_policy(
+    def enable_policy(self, backoff=2, max_retries=3, delay=1):
-        self,
-        max_retries: int = 3,
-        delay: float = 1.0,
-        backoff: float = 2.0,
-        jitter: float = 0.0,
-    ) -> None:
         self.policy.enabled = True
         self.policy.max_retries = max_retries
         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:
+    async def retry_on_error(self, context: ExecutionContext):
         from falyx.action import Action
-
         name = context.name
         error = context.exception
         target = context.action
@@ -126,64 +43,36 @@ class RetryHandler:
         last_error = error
 
         if not target:
-            logger.warning("[%s] No action target. Cannot retry.", name)
+            logger.warning(f"[{name}] ⚠️ No action target. Cannot retry.")
-            return None
+            return
 
         if not isinstance(target, Action):
-            logger.warning(
+            logger.warning(f"[{name}] ❌ RetryHandler only supports only supports Action objects.")
-                "[%s] RetryHandler only supports only supports Action objects.", name
+            return
-            )
-            return None
 
         if not getattr(target, "is_retryable", False):
-            logger.warning("[%s] Not retryable.", name)
+            logger.warning(f"[{name}] ❌ Not retryable.")
-            return None
+            return
 
         if not self.policy.enabled:
-            logger.warning("[%s] Retry policy is disabled.", name)
+            logger.warning(f"[{name}] ❌ Retry policy is disabled.")
-            return None
+            return
 
         while retries_done < self.policy.max_retries:
             retries_done += 1
-
+            logger.info(f"[{name}] 🔄 Retrying ({retries_done}/{self.policy.max_retries}) in {current_delay}s due to '{last_error}'...")
-            sleep_delay = current_delay
-            if self.policy.jitter > 0:
-                sleep_delay += random.uniform(-self.policy.jitter, self.policy.jitter)
-            logger.debug(
-                "[%s] Error: %s",
-                name,
-                last_error,
-            )
-            logger.info(
-                "[%s] Retrying (%s/%s) in %ss due to '%s'...",
-                name,
-                retries_done,
-                self.policy.max_retries,
-                current_delay,
-                last_error.__class__.__name__,
-            )
             await asyncio.sleep(current_delay)
             try:
                 result = await target.action(*context.args, **context.kwargs)
                 context.result = result
                 context.exception = None
-                logger.info("[%s] Retry succeeded on attempt %s.", name, retries_done)
+                logger.info(f"[{name}] ✅ Retry succeeded on attempt {retries_done}.")
-                return None
+                return
             except Exception as retry_error:
                 last_error = retry_error
                 current_delay *= self.policy.backoff
-                logger.debug(
+                logger.warning(f"[{name}] ⚠️ Retry attempt {retries_done}/{self.policy.max_retries} failed due to '{retry_error}'.")
-                    "[%s] Error: %s",
-                    name,
-                    retry_error,
-                )
-                logger.warning(
-                    "[%s] Retry attempt %s/%s failed due to '%s'.",
-                    name,
-                    retries_done,
-                    self.policy.max_retries,
-                    retry_error.__class__.__name__,
-                )
 
         context.exception = last_error
-        logger.error("[%s] All %s retries failed.", name, self.policy.max_retries)
+        logger.error(f"[{name}] ❌ All {self.policy.max_retries} retries failed.")
+        return

falyx/retry_utils.py

@@ -1,28 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Utilities for enabling retry behavior across Falyx actions.
-
-This module provides a helper to recursively apply a `RetryPolicy` to an action and its
-nested children (e.g. `ChainedAction`, `ActionGroup`), and register the appropriate
-`RetryHandler` to hook into error handling.
-
-Includes:
-- `enable_retries_recursively`: Attaches a retry policy and error hook to all eligible actions.
-"""
-from falyx.action.action import Action
-from falyx.action.base_action import BaseAction
-from falyx.hook_manager import HookType
-from falyx.retry import RetryHandler, RetryPolicy
-
-
-def enable_retries_recursively(action: BaseAction, policy: RetryPolicy | None):
-    if not policy:
-        policy = RetryPolicy(enabled=True)
-    if isinstance(action, Action):
-        action.retry_policy = policy
-        action.retry_policy.enabled = True
-        action.hooks.register(HookType.ON_ERROR, RetryHandler(policy).retry_on_error)
-
-    if hasattr(action, "actions"):
-        for sub in action.actions:
-            enable_retries_recursively(sub, policy)

falyx/selection.py

@@ -1,502 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Provides interactive selection utilities for Falyx CLI actions.
-
-This module defines `SelectionOption` objects, selection maps, and rich-powered
-rendering functions to build interactive selection prompts using `prompt_toolkit`.
-It supports:
-- Grid-based and dictionary-based selection menus
-- Index- or key-driven multi-select prompts
-- Formatted Rich tables for CLI visual menus
-- Cancel keys, defaults, and duplication control
-
-Used by `SelectionAction` and other prompt-driven workflows within Falyx.
-"""
-from dataclasses import dataclass
-from typing import Any, Callable, KeysView, Sequence
-
-from prompt_toolkit import PromptSession
-from rich import box
-from rich.markup import escape
-from rich.table import Table
-
-from falyx.console import console
-from falyx.prompt_utils import rich_text_to_prompt_text
-from falyx.themes import OneColors
-from falyx.utils import CaseInsensitiveDict, chunks
-from falyx.validators import MultiIndexValidator, MultiKeyValidator
-
-
-@dataclass
-class SelectionOption:
-    """Represents a single selection option with a description and a value."""
-
-    description: str
-    value: Any
-    style: str = OneColors.WHITE
-
-    def __post_init__(self):
-        if not isinstance(self.description, str):
-            raise TypeError("SelectionOption description must be a string.")
-
-    def render(self, key: str) -> str:
-        """Render the selection option for display."""
-        key = escape(f"[{key}]")
-        return f"[{OneColors.WHITE}]{key}[/] [{self.style}]{self.description}[/]"
-
-
-class SelectionOptionMap(CaseInsensitiveDict):
-    """
-    Manages selection options including validation and reserved key protection.
-    """
-
-    RESERVED_KEYS: set[str] = set()
-
-    def __init__(
-        self,
-        options: dict[str, SelectionOption] | None = None,
-        allow_reserved: bool = False,
-    ):
-        super().__init__()
-        self.allow_reserved = allow_reserved
-        if options:
-            self.update(options)
-
-    def _add_reserved(self, key: str, option: SelectionOption) -> None:
-        """Add a reserved key, bypassing validation."""
-        norm_key = key.upper()
-        super().__setitem__(norm_key, option)
-
-    def __setitem__(self, key: str, option: SelectionOption) -> None:
-        if not isinstance(option, SelectionOption):
-            raise TypeError(f"Value for key '{key}' must be a SelectionOption.")
-        norm_key = key.upper()
-        if norm_key in self.RESERVED_KEYS and not self.allow_reserved:
-            raise ValueError(
-                f"Key '{key}' is reserved and cannot be used in SelectionOptionMap."
-            )
-        super().__setitem__(norm_key, option)
-
-    def __delitem__(self, key: str) -> None:
-        if key.upper() in self.RESERVED_KEYS and not self.allow_reserved:
-            raise ValueError(f"Cannot delete reserved option '{key}'.")
-        super().__delitem__(key)
-
-    def update(self, other=None, **kwargs):
-        """Update the selection options with another dictionary."""
-        if other:
-            for key, option in other.items():
-                if not isinstance(option, SelectionOption):
-                    raise TypeError(f"Value for key '{key}' must be a SelectionOption.")
-                self[key] = option
-        for key, option in kwargs.items():
-            if not isinstance(option, SelectionOption):
-                raise TypeError(f"Value for key '{key}' must be a SelectionOption.")
-            self[key] = option
-
-    def items(self, include_reserved: bool = True):
-        for k, v in super().items():
-            if not include_reserved and k in self.RESERVED_KEYS:
-                continue
-            yield k, v
-
-
-def render_table_base(
-    title: str,
-    *,
-    caption: str = "",
-    columns: int = 4,
-    box_style: box.Box = box.SIMPLE,
-    show_lines: bool = False,
-    show_header: bool = False,
-    show_footer: bool = False,
-    style: str = "",
-    header_style: str = "",
-    footer_style: str = "",
-    title_style: str = "",
-    caption_style: str = "",
-    highlight: bool = True,
-    column_names: Sequence[str] | None = None,
-) -> Table:
-    table = Table(
-        title=title,
-        caption=caption,
-        box=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,
-    )
-    if column_names:
-        for column_name in column_names:
-            table.add_column(column_name)
-    else:
-        for _ in range(columns):
-            table.add_column()
-    return table
-
-
-def render_selection_grid(
-    title: str,
-    selections: Sequence[str],
-    *,
-    columns: int = 4,
-    caption: str = "",
-    box_style: box.Box = box.SIMPLE,
-    show_lines: bool = False,
-    show_header: bool = False,
-    show_footer: bool = False,
-    style: str = "",
-    header_style: str = "",
-    footer_style: str = "",
-    title_style: str = "",
-    caption_style: str = "",
-    highlight: bool = False,
-) -> Table:
-    """Create a selection table with the given parameters."""
-    table = render_table_base(
-        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):
-        table.add_row(*chunk)
-
-    return table
-
-
-def render_selection_indexed_table(
-    title: str,
-    selections: Sequence[str],
-    *,
-    columns: int = 4,
-    caption: str = "",
-    box_style: box.Box = box.SIMPLE,
-    show_lines: bool = False,
-    show_header: bool = False,
-    show_footer: bool = False,
-    style: str = "",
-    header_style: str = "",
-    footer_style: str = "",
-    title_style: str = "",
-    caption_style: str = "",
-    highlight: bool = False,
-    formatter: Callable[[int, str], str] | None = None,
-) -> Table:
-    """Create a selection table with the given parameters."""
-    table = render_table_base(
-        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(
-        chunks(range(len(selections)), columns), chunks(selections, columns)
-    ):
-        row = [
-            formatter(index, selection) if formatter else f"[{index}] {selection}"
-            for index, selection in zip(indexes, chunk)
-        ]
-        table.add_row(*row)
-
-    return table
-
-
-def render_selection_dict_table(
-    title: str,
-    selections: dict[str, SelectionOption],
-    *,
-    columns: int = 2,
-    caption: str = "",
-    box_style: box.Box = box.SIMPLE,
-    show_lines: bool = False,
-    show_header: bool = False,
-    show_footer: bool = False,
-    style: str = "",
-    header_style: str = "",
-    footer_style: str = "",
-    title_style: str = "",
-    caption_style: str = "",
-    highlight: bool = False,
-) -> Table:
-    """Create a selection table with the given parameters."""
-    table = render_table_base(
-        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):
-        row = []
-        for key, option in chunk:
-            row.append(
-                f"[{OneColors.WHITE}][{key.upper()}] "
-                f"[{option.style}]{option.description}[/]"
-            )
-        table.add_row(*row)
-
-    return table
-
-
-async def prompt_for_index(
-    max_index: int,
-    table: Table,
-    *,
-    min_index: int = 0,
-    default_selection: str = "",
-    prompt_session: PromptSession | None = None,
-    prompt_message: str = "Select an option > ",
-    show_table: bool = True,
-    number_selections: int | str = 1,
-    separator: str = ",",
-    allow_duplicates: bool = False,
-    cancel_key: str = "",
-) -> int | list[int]:
-    prompt_session = prompt_session or PromptSession()
-
-    if show_table:
-        console.print(table, justify="center")
-
-    selection = await prompt_session.prompt_async(
-        message=rich_text_to_prompt_text(prompt_message),
-        validator=MultiIndexValidator(
-            min_index,
-            max_index,
-            number_selections,
-            separator,
-            allow_duplicates,
-            cancel_key,
-        ),
-        default=default_selection,
-    )
-
-    if selection.strip() == cancel_key:
-        return int(cancel_key)
-    if isinstance(number_selections, int) and number_selections == 1:
-        return int(selection.strip())
-    return [int(index.strip()) for index in selection.strip().split(separator)]
-
-
-async def prompt_for_selection(
-    keys: Sequence[str] | KeysView[str],
-    table: Table,
-    *,
-    default_selection: str = "",
-    prompt_session: PromptSession | None = None,
-    prompt_message: str = "Select an option > ",
-    show_table: bool = True,
-    number_selections: int | str = 1,
-    separator: str = ",",
-    allow_duplicates: bool = False,
-    cancel_key: str = "",
-) -> str | list[str]:
-    """Prompt the user to select a key from a set of options. Return the selected key."""
-    prompt_session = prompt_session or PromptSession()
-
-    if show_table:
-        console.print(table, justify="center")
-
-    selected = await prompt_session.prompt_async(
-        message=rich_text_to_prompt_text(prompt_message),
-        validator=MultiKeyValidator(
-            keys, number_selections, separator, allow_duplicates, cancel_key
-        ),
-        default=default_selection,
-    )
-
-    if selected.strip() == cancel_key:
-        return cancel_key
-    if isinstance(number_selections, int) and number_selections == 1:
-        return selected.strip()
-    return [key.strip() for key in selected.strip().split(separator)]
-
-
-async def select_value_from_list(
-    title: str,
-    selections: Sequence[str],
-    *,
-    prompt_session: PromptSession | None = None,
-    prompt_message: str = "Select an option > ",
-    default_selection: str = "",
-    number_selections: int | str = 1,
-    separator: str = ",",
-    allow_duplicates: bool = False,
-    cancel_key: str = "",
-    columns: int = 4,
-    caption: str = "",
-    box_style: box.Box = box.SIMPLE,
-    show_lines: bool = False,
-    show_header: bool = False,
-    show_footer: bool = False,
-    style: str = "",
-    header_style: str = "",
-    footer_style: str = "",
-    title_style: str = "",
-    caption_style: str = "",
-    highlight: bool = False,
-) -> str | list[str]:
-    """Prompt for a selection. Return the selected item."""
-    table = render_selection_indexed_table(
-        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()
-
-    selection_index = await prompt_for_index(
-        len(selections) - 1,
-        table,
-        default_selection=default_selection,
-        prompt_session=prompt_session,
-        prompt_message=prompt_message,
-        number_selections=number_selections,
-        separator=separator,
-        allow_duplicates=allow_duplicates,
-        cancel_key=cancel_key,
-    )
-
-    if isinstance(selection_index, list):
-        return [selections[i] for i in selection_index]
-    return selections[selection_index]
-
-
-async def select_key_from_dict(
-    selections: dict[str, SelectionOption],
-    table: Table,
-    *,
-    prompt_session: PromptSession | None = None,
-    prompt_message: str = "Select an option > ",
-    default_selection: str = "",
-    number_selections: int | str = 1,
-    separator: str = ",",
-    allow_duplicates: bool = False,
-    cancel_key: str = "",
-) -> str | list[str]:
-    """Prompt for a key from a dict, returns the key."""
-    prompt_session = prompt_session or PromptSession()
-
-    console.print(table, justify="center")
-
-    return await prompt_for_selection(
-        selections.keys(),
-        table,
-        default_selection=default_selection,
-        prompt_session=prompt_session,
-        prompt_message=prompt_message,
-        number_selections=number_selections,
-        separator=separator,
-        allow_duplicates=allow_duplicates,
-        cancel_key=cancel_key,
-    )
-
-
-async def select_value_from_dict(
-    selections: dict[str, SelectionOption],
-    table: Table,
-    *,
-    prompt_session: PromptSession | None = None,
-    prompt_message: str = "Select an option > ",
-    default_selection: str = "",
-    number_selections: int | str = 1,
-    separator: str = ",",
-    allow_duplicates: bool = False,
-    cancel_key: str = "",
-) -> Any | list[Any]:
-    """Prompt for a key from a dict, but return the value."""
-    prompt_session = prompt_session or PromptSession()
-
-    console.print(table, justify="center")
-
-    selection_key = await prompt_for_selection(
-        selections.keys(),
-        table,
-        default_selection=default_selection,
-        prompt_session=prompt_session,
-        prompt_message=prompt_message,
-        number_selections=number_selections,
-        separator=separator,
-        allow_duplicates=allow_duplicates,
-        cancel_key=cancel_key,
-    )
-
-    if isinstance(selection_key, list):
-        return [selections[key].value for key in selection_key]
-    return selections[selection_key].value
-
-
-async def get_selection_from_dict_menu(
-    title: str,
-    selections: dict[str, SelectionOption],
-    *,
-    prompt_session: PromptSession | None = None,
-    prompt_message: str = "Select an option > ",
-    default_selection: str = "",
-    number_selections: int | str = 1,
-    separator: str = ",",
-    allow_duplicates: bool = False,
-    cancel_key: str = "",
-) -> Any | list[Any]:
-    """Prompt for a key from a dict, but return the value."""
-    table = render_selection_dict_table(
-        title,
-        selections,
-    )
-
-    return await select_value_from_dict(
-        selections=selections,
-        table=table,
-        prompt_session=prompt_session,
-        prompt_message=prompt_message,
-        default_selection=default_selection,
-        number_selections=number_selections,
-        separator=separator,
-        allow_duplicates=allow_duplicates,
-        cancel_key=cancel_key,
-    )

falyx/signals.py

@@ -1,61 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Defines flow control signals used internally by the Falyx CLI framework.
-
-These signals are raised to interrupt or redirect CLI execution flow
-(e.g., returning to a menu, quitting, or displaying help) without
-being treated as traditional exceptions.
-
-All signals inherit from `FlowSignal`, which is a subclass of `BaseException`
-to ensure they bypass standard `except Exception` blocks.
-
-Signals:
-- BreakChainSignal: Exit a chained action early.
-- QuitSignal: Terminate the CLI session.
-- BackSignal: Return to the previous menu or caller.
-- CancelSignal: Cancel the current operation.
-- HelpSignal: Trigger help output in interactive flows.
-"""
-
-
-class FlowSignal(BaseException):
-    """Base class for all flow control signals in Falyx.
-
-    These are not errors. They're used to control flow like quitting,
-    going back, or restarting from user input or nested menus.
-    """
-
-
-class BreakChainSignal(FlowSignal):
-    """Raised to break the current action chain and return to the previous context."""
-
-    def __init__(self, message: str = "Break chain signal received."):
-        super().__init__(message)
-
-
-class QuitSignal(FlowSignal):
-    """Raised to signal an immediate exit from the CLI framework."""
-
-    def __init__(self, message: str = "Quit signal received."):
-        super().__init__(message)
-
-
-class BackSignal(FlowSignal):
-    """Raised to return control to the previous menu or caller."""
-
-    def __init__(self, message: str = "Back signal received."):
-        super().__init__(message)
-
-
-class CancelSignal(FlowSignal):
-    """Raised to cancel the current command or action."""
-
-    def __init__(self, message: str = "Cancel signal received."):
-        super().__init__(message)
-
-
-class HelpSignal(FlowSignal):
-    """Raised to display help information."""
-
-    def __init__(self, message: str = "Help signal received."):
-        super().__init__(message)

falyx/spinner_manager.py

@@ -1,248 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Centralized spinner rendering for Falyx CLI.
-
-This module provides the `SpinnerManager` class, which manages a collection of
-Rich spinners that can be displayed concurrently during long-running tasks.
-
-Key Features:
-    • Automatic lifecycle management:
-        - Starts a single Rich `Live` loop when the first spinner is added.
-        - Stops and clears the display when the last spinner is removed.
-    • Thread/async-safe start logic via a lightweight lock to prevent
-      duplicate Live loops from being launched.
-    • Supports multiple spinners running simultaneously, each with its own
-      text, style, type, and speed.
-    • Integrates with Falyx's OptionsManager so actions and commands can
-      declaratively request spinners without directly managing terminal state.
-
-Classes:
-    SpinnerData:
-        Lightweight container for individual spinner settings (message,
-        type, style, speed) and its underlying Rich `Spinner` object.
-    SpinnerManager:
-        Manages all active spinners, handles Live rendering, and provides
-        methods to add, update, and remove spinners.
-
-Example:
-    ```python
-    >>> manager = SpinnerManager()
-    >>> await manager.add("build", "Building project…", spinner_type="dots")
-    >>> await manager.add("deploy", "Deploying to AWS…", spinner_type="earth")
-    # Both spinners animate in one unified Live panel
-    >>> manager.remove("build")
-    >>> manager.remove("deploy")
-    ```
-
-Design Notes:
-    • SpinnerManager should only create **one** Live loop at a time.
-    • When no spinners remain, the Live panel is cleared (`transient=True`)
-      so the CLI output returns to a clean state.
-    • Hooks in `falyx.hooks` (spinner_before_hook / spinner_teardown_hook)
-      call into this manager automatically when `spinner=True` is set on
-      an Action or Command.
-"""
-
-import asyncio
-
-from rich.console import Group
-from rich.live import Live
-from rich.spinner import Spinner
-
-from falyx.console import console
-from falyx.logger import logger
-from falyx.themes import OneColors
-
-
-class SpinnerData:
-    """
-    Holds the configuration and Rich spinner object for a single task.
-
-    This class is a lightweight container for spinner metadata, storing the
-    message text, spinner type, style, and speed. It also initializes the
-    corresponding Rich `Spinner` instance used by `SpinnerManager` for
-    rendering.
-
-    Attributes:
-        text (str): The message displayed next to the spinner.
-        spinner_type (str): The Rich spinner preset to use (e.g., "dots",
-            "bouncingBall", "earth").
-        spinner_style (str): Rich color/style for the spinner animation.
-        spinner (Spinner): The instantiated Rich spinner object.
-
-    Example:
-        ```
-        >>> data = SpinnerData("Deploying...", spinner_type="earth",
-        ...                    spinner_style="cyan", spinner_speed=1.0)
-        >>> data.spinner
-        <rich.spinner.Spinner object ...>
-        ```
-    """
-
-    def __init__(
-        self, text: str, spinner_type: str, spinner_style: str, spinner_speed: float
-    ):
-        """Initialize a spinner with text, type, style, and speed."""
-        self.text = text
-        self.spinner_type = spinner_type
-        self.spinner_style = spinner_style
-        self.spinner = Spinner(
-            spinner_type, text=text, style=spinner_style, speed=spinner_speed
-        )
-
-
-class SpinnerManager:
-    """
-    Manages multiple Rich spinners and handles their terminal rendering.
-
-    SpinnerManager maintains a registry of active spinners and a single
-    Rich `Live` display loop to render them. When the first spinner is added,
-    the Live loop starts automatically. When the last spinner is removed,
-    the Live loop stops and the panel clears (via `transient=True`).
-
-    This class is designed for integration with Falyx's `OptionsManager`
-    so any Action or Command can declaratively register spinners without
-    directly controlling terminal state.
-
-    Key Behaviors:
-        • Starts exactly one `Live` loop, protected by a start lock to prevent
-          duplicate launches in async/threaded contexts.
-        • Supports multiple simultaneous spinners, each with independent
-          text, style, and type.
-        • Clears the display when all spinners are removed.
-
-    Attributes:
-        console (Console): The Rich console used for rendering.
-        _spinners (dict[str, SpinnerData]): Internal store of active spinners.
-        _task (asyncio.Task | None): The running Live loop task, if any.
-        _running (bool): Indicates if the Live loop is currently active.
-
-    Example:
-        ```
-        >>> manager = SpinnerManager()
-        >>> await manager.add("build", "Building project…")
-        >>> await manager.add("deploy", "Deploying services…", spinner_type="earth")
-        >>> manager.remove("build")
-        >>> manager.remove("deploy")
-        ```
-    """
-
-    def __init__(self) -> None:
-        """Initialize the SpinnerManager with an empty spinner registry."""
-        self.console = console
-        self._spinners: dict[str, SpinnerData] = {}
-        self._task: asyncio.Task | None = None
-        self._running: bool = False
-
-        self._lock = asyncio.Lock()
-
-    async def add(
-        self,
-        name: str,
-        text: str,
-        spinner_type: str = "dots",
-        spinner_style: str = OneColors.CYAN,
-        spinner_speed: float = 1.0,
-    ):
-        """Add a new spinner and start the Live loop if not already running."""
-        self._spinners[name] = SpinnerData(
-            text=text,
-            spinner_type=spinner_type,
-            spinner_style=spinner_style,
-            spinner_speed=spinner_speed,
-        )
-        async with self._lock:
-            if not self._running:
-                logger.debug("[%s] Starting spinner manager Live loop.", name)
-                await self._start_live()
-
-    def update(
-        self,
-        name: str,
-        text: str | None = None,
-        spinner_type: str | None = None,
-        spinner_style: str | None = None,
-    ):
-        """Update an existing spinner's message, style, or type."""
-        if name in self._spinners:
-            data = self._spinners[name]
-            if text:
-                data.text = text
-                data.spinner.text = text
-            if spinner_style:
-                data.spinner_style = spinner_style
-                data.spinner.style = spinner_style
-            if spinner_type:
-                data.spinner_type = spinner_type
-                data.spinner = Spinner(spinner_type, text=data.text)
-
-    async def remove(self, name: str):
-        """Remove a spinner and stop the Live loop if no spinners remain."""
-        self._spinners.pop(name, None)
-        async with self._lock:
-            if not self._spinners:
-                logger.debug("[%s] Stopping spinner manager, no spinners left.", name)
-                if self._task:
-                    self._task.cancel()
-                self._running = False
-
-    async def _start_live(self):
-        """Start the Live rendering loop in the background."""
-        self._running = True
-        self._task = asyncio.create_task(self._live_loop())
-
-    def render_panel(self):
-        """Render all active spinners as a grouped Rich panel."""
-        rows = []
-        for data in self._spinners.values():
-            rows.append(data.spinner)
-        return Group(*rows)
-
-    async def _live_loop(self):
-        """Continuously refresh the spinner display until stopped."""
-        with Live(
-            self.render_panel(),
-            refresh_per_second=12.5,
-            console=self.console,
-            transient=True,
-        ) as live:
-            while self._spinners:
-                live.update(self.render_panel())
-                await asyncio.sleep(0.1)
-
-
-if __name__ == "__main__":
-    spinner_manager = SpinnerManager()
-
-    async def demo():
-        # Add multiple spinners
-        await spinner_manager.add("task1", "Loading configs…")
-        await spinner_manager.add(
-            "task2", "Building containers…", spinner_type="bouncingBall"
-        )
-        await spinner_manager.add("task3", "Deploying services…", spinner_type="earth")
-
-        # Simulate work
-        await asyncio.sleep(2)
-        spinner_manager.update("task1", text="Configs loaded ✅")
-        await asyncio.sleep(1)
-        spinner_manager.remove("task1")
-
-        await spinner_manager.add("task4", "Running Tests...")
-
-        await asyncio.sleep(2)
-        spinner_manager.update("task2", text="Build complete ✅")
-        spinner_manager.remove("task2")
-
-        await asyncio.sleep(1)
-        spinner_manager.update("task3", text="Deployed! 🎉")
-        await asyncio.sleep(1)
-        spinner_manager.remove("task3")
-
-        await asyncio.sleep(5)
-
-        spinner_manager.update("task4", "Tests Complete!")
-        spinner_manager.remove("task4")
-        console.print("Done!")
-
-    asyncio.run(demo())

falyx/tagged_table.py

@@ -1,43 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Generates a Rich table view of Falyx commands grouped by their tags.
-
-This module defines a utility function for rendering a custom CLI command
-table that organizes commands into groups based on their first tag. It is
-used to visually separate commands in interactive menus for better clarity
-and discoverability.
-
-Functions:
-- build_tagged_table(flx): Returns a `rich.Table` of commands grouped by tag.
-"""
-from collections import defaultdict
-
-from rich import box
-from rich.table import Table
-
-from falyx.command import Command
-from falyx.falyx import Falyx
-
-
-def build_tagged_table(flx: Falyx) -> Table:
-    """Custom table builder that groups commands by tags."""
-    table = Table(title=flx.title, show_header=False, box=box.SIMPLE)  # type: ignore[arg-type]
-
-    # Group commands by first tag
-    grouped: dict[str, list[Command]] = defaultdict(list)
-    for cmd in flx.commands.values():
-        first_tag = cmd.tags[0] if cmd.tags else "Other"
-        grouped[first_tag.capitalize()].append(cmd)
-
-    # Add grouped commands to table
-    for group_name, commands in grouped.items():
-        table.add_row(f"[bold underline]{group_name} Commands[/]")
-        for cmd in commands:
-            table.add_row(f"[{cmd.key}] [{cmd.style}]{cmd.description}")
-        table.add_row("")
-
-    # Add bottom row
-    for row in flx.get_bottom_row():
-        table.add_row(row)
-
-    return table

falyx/themes/__init__.py

@@ -1,15 +0,0 @@
-"""
-Falyx CLI Framework
-
-Copyright (c) 2025 rtj.dev LLC.
-Licensed under the MIT License. See LICENSE file for details.
-"""
-
-from .colors import ColorsMeta, NordColors, OneColors, get_nord_theme
-
-__all__ = [
-    "OneColors",
-    "NordColors",
-    "get_nord_theme",
-    "ColorsMeta",
-]

falyx/themes/colors.py

@@ -1,5 +1,6 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 """
+colors.py
+
 A Python module that integrates the Nord color palette with the Rich library.
 It defines a metaclass-based NordColors class allowing dynamic attribute lookups
 (e.g., NORD12bu -> "#D08770 bold underline") and provides a comprehensive Nord-based
@@ -16,7 +17,6 @@ Example dynamic usage:
     console.print("Hello!", style=NordColors.NORD12bu)
     # => Renders "Hello!" in #D08770 (Nord12) plus bold and underline styles
 """
-
 import re
 from difflib import get_close_matches
 
@@ -82,17 +82,14 @@ class ColorsMeta(type):
         except AttributeError:
             error_msg = [f"'{cls.__name__}' has no color named '{base}'."]
             valid_bases = [
-                key
+                key for key, val in cls.__dict__.items() if isinstance(val, str) and
-                for key, val in cls.__dict__.items()
+                not key.startswith("__")
-                if isinstance(val, str) and not key.startswith("__")
             ]
             suggestions = get_close_matches(base, valid_bases, n=1, cutoff=0.5)
             if suggestions:
                 error_msg.append(f"Did you mean '{suggestions[0]}'?")
             if valid_bases:
-                error_msg.append(
+                error_msg.append(f"Valid base color names include: {', '.join(valid_bases)}")
-                    f"Valid base color names include: {', '.join(valid_bases)}"
-                )
             raise AttributeError(" ".join(error_msg)) from None
 
         if not isinstance(color_value, str):
@@ -108,9 +105,7 @@ class ColorsMeta(type):
             if mapped_style:
                 styles.append(mapped_style)
             else:
-                raise AttributeError(
+                raise AttributeError(f"Unknown style flag '{letter}' in attribute '{name}'")
-                    f"Unknown style flag '{letter}' in attribute '{name}'"
-                )
 
         order = {"b": 1, "i": 2, "u": 3, "d": 4, "r": 5, "s": 6}
         styles_sorted = sorted(styles, key=lambda s: order[s[0]])
@@ -138,6 +133,7 @@ class OneColors(metaclass=ColorsMeta):
     BLUE = "#61AFEF"
     MAGENTA = "#C678DD"
 
+
     @classmethod
     def as_dict(cls):
         """
@@ -147,10 +143,10 @@ class OneColors(metaclass=ColorsMeta):
         return {
             attr: getattr(cls, attr)
             for attr in dir(cls)
-            if not callable(getattr(cls, attr)) and not attr.startswith("__")
+            if not callable(getattr(cls, attr)) and
+            not attr.startswith("__")
         }
 
-
 class NordColors(metaclass=ColorsMeta):
     """
     Defines the Nord color palette as class attributes.
@@ -219,7 +215,8 @@ class NordColors(metaclass=ColorsMeta):
         return {
             attr: getattr(cls, attr)
             for attr in dir(cls)
-            if attr.startswith("NORD") and not callable(getattr(cls, attr))
+            if attr.startswith("NORD") and
+            not callable(getattr(cls, attr))
         }
 
     @classmethod
@@ -230,8 +227,7 @@ class NordColors(metaclass=ColorsMeta):
         """
         skip_prefixes = ("NORD", "__")
         alias_names = [
-            attr
+            attr for attr in dir(cls)
-            for attr in dir(cls)
             if not any(attr.startswith(sp) for sp in skip_prefixes)
             and not callable(getattr(cls, attr))
         ]
@@ -268,6 +264,7 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "blink2": Style(blink2=True),
     "reverse": Style(reverse=True),
     "strike": Style(strike=True),
+
     # ---------------------------------------------------------------
     # Basic color names mapped to Nord
     # ---------------------------------------------------------------
@@ -280,6 +277,7 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "cyan": Style(color=NordColors.CYAN),
     "blue": Style(color=NordColors.BLUE),
     "white": Style(color=NordColors.SNOW_STORM_BRIGHTEST),
+
     # ---------------------------------------------------------------
     # Inspect
     # ---------------------------------------------------------------
@@ -294,12 +292,14 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "inspect.help": Style(color=NordColors.FROST_ICE),
     "inspect.doc": Style(dim=True),
     "inspect.value.border": Style(color=NordColors.GREEN),
+
     # ---------------------------------------------------------------
     # Live / Layout
     # ---------------------------------------------------------------
     "live.ellipsis": Style(bold=True, color=NordColors.RED),
     "layout.tree.row": Style(dim=False, color=NordColors.RED),
     "layout.tree.column": Style(dim=False, color=NordColors.FROST_DEEP),
+
     # ---------------------------------------------------------------
     # Logging
     # ---------------------------------------------------------------
@@ -314,6 +314,7 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "log.time": Style(color=NordColors.FROST_ICE, dim=True),
     "log.message": Style.null(),
     "log.path": Style(dim=True),
+
     # ---------------------------------------------------------------
     # Python repr
     # ---------------------------------------------------------------
@@ -339,18 +340,18 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "repr.bool_true": Style(color=NordColors.GREEN, italic=True),
     "repr.bool_false": Style(color=NordColors.RED, italic=True),
     "repr.none": Style(color=NordColors.PURPLE, italic=True),
-    "repr.url": Style(
+    "repr.url": Style(underline=True, color=NordColors.FROST_ICE, italic=False, bold=False),
-        underline=True, color=NordColors.FROST_ICE, italic=False, bold=False
-    ),
     "repr.uuid": Style(color=NordColors.YELLOW, bold=False),
     "repr.call": Style(color=NordColors.PURPLE, bold=True),
     "repr.path": Style(color=NordColors.PURPLE),
     "repr.filename": Style(color=NordColors.PURPLE),
+
     # ---------------------------------------------------------------
     # Rule
     # ---------------------------------------------------------------
     "rule.line": Style(color=NordColors.GREEN),
     "rule.text": Style.null(),
+
     # ---------------------------------------------------------------
     # JSON
     # ---------------------------------------------------------------
@@ -361,6 +362,7 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "json.number": Style(color=NordColors.FROST_ICE, bold=True, italic=False),
     "json.str": Style(color=NordColors.GREEN, italic=False, bold=False),
     "json.key": Style(color=NordColors.FROST_ICE, bold=True),
+
     # ---------------------------------------------------------------
     # Prompt
     # ---------------------------------------------------------------
@@ -369,10 +371,12 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "prompt.default": Style(color=NordColors.FROST_ICE, bold=True),
     "prompt.invalid": Style(color=NordColors.RED),
     "prompt.invalid.choice": Style(color=NordColors.RED),
+
     # ---------------------------------------------------------------
     # Pretty
     # ---------------------------------------------------------------
     "pretty": Style.null(),
+
     # ---------------------------------------------------------------
     # Scope
     # ---------------------------------------------------------------
@@ -380,6 +384,7 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "scope.key": Style(color=NordColors.YELLOW, italic=True),
     "scope.key.special": Style(color=NordColors.YELLOW, italic=True, dim=True),
     "scope.equals": Style(color=NordColors.RED),
+
     # ---------------------------------------------------------------
     # Table
     # ---------------------------------------------------------------
@@ -388,6 +393,7 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "table.cell": Style.null(),
     "table.title": Style(italic=True),
     "table.caption": Style(italic=True, dim=True),
+
     # ---------------------------------------------------------------
     # Traceback
     # ---------------------------------------------------------------
@@ -399,6 +405,7 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "traceback.exc_type": Style(color=NordColors.RED, bold=True),
     "traceback.exc_value": Style.null(),
     "traceback.offset": Style(color=NordColors.RED, bold=True),
+
     # ---------------------------------------------------------------
     # Progress bars
     # ---------------------------------------------------------------
@@ -416,11 +423,13 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "progress.data.speed": Style(color=NordColors.RED),
     "progress.spinner": Style(color=NordColors.GREEN),
     "status.spinner": Style(color=NordColors.GREEN),
+
     # ---------------------------------------------------------------
     # Tree
     # ---------------------------------------------------------------
     "tree": Style(),
     "tree.line": Style(),
+
     # ---------------------------------------------------------------
     # Markdown
     # ---------------------------------------------------------------
@@ -429,12 +438,8 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "markdown.em": Style(italic=True),
     "markdown.emph": Style(italic=True),  # For commonmark compatibility
     "markdown.strong": Style(bold=True),
-    "markdown.code": Style(
+    "markdown.code": Style(bold=True, color=NordColors.FROST_ICE, bgcolor=NordColors.POLAR_NIGHT_ORIGIN),
-        bold=True, color=NordColors.FROST_ICE, bgcolor=NordColors.POLAR_NIGHT_ORIGIN
+    "markdown.code_block": Style(color=NordColors.FROST_ICE, bgcolor=NordColors.POLAR_NIGHT_ORIGIN),
-    ),
-    "markdown.code_block": Style(
-        color=NordColors.FROST_ICE, bgcolor=NordColors.POLAR_NIGHT_ORIGIN
-    ),
     "markdown.block_quote": Style(color=NordColors.PURPLE),
     "markdown.list": Style(color=NordColors.FROST_ICE),
     "markdown.item": Style(),
@@ -452,6 +457,7 @@ NORD_THEME_STYLES: dict[str, Style] = {
     "markdown.link": Style(color=NordColors.FROST_ICE),
     "markdown.link_url": Style(color=NordColors.FROST_SKY, underline=True),
     "markdown.s": Style(strike=True),
+
     # ---------------------------------------------------------------
     # ISO8601
     # ---------------------------------------------------------------
@@ -498,9 +504,7 @@ if __name__ == "__main__":
         console.print(f"Caught error: {error}", style="red")
 
     # Demonstrate a traceback style:
-    console.print(
+    console.print("\n8) Raising and displaying a traceback with Nord styling:\n", style="bold")
-        "\n8) Raising and displaying a traceback with Nord styling:\n", style="bold"
-    )
     try:
         raise ValueError("Nord test exception!")
     except ValueError:

falyx/utils.py

@@ -1,57 +1,26 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""utils.py"""
-"""
-General-purpose utilities and helpers for the Falyx CLI framework.
-
-This module includes asynchronous wrappers, logging setup, formatting utilities,
-and small type-safe enhancements such as `CaseInsensitiveDict` and coroutine enforcement.
-
-Features:
-- `ensure_async`: Wraps sync functions as async coroutines.
-- `chunks`: Splits an iterable into fixed-size chunks.
-- `CaseInsensitiveDict`: Dict subclass with case-insensitive string keys.
-- `setup_logging`: Configures Rich or JSON logging based on environment or container detection.
-- `get_program_invocation`: Returns the recommended CLI command to invoke the program.
-- `running_in_container`: Detects if the process is running inside a container.
-
-These utilities support consistent behavior across CLI rendering, logging,
-command parsing, and compatibility layers.
-"""
-from __future__ import annotations
-
 import functools
 import inspect
 import logging
 import os
-import shutil
-import sys
 from itertools import islice
 from typing import Any, Awaitable, Callable, TypeVar
 
 import pythonjsonlogger.json
+from prompt_toolkit import PromptSession
+from prompt_toolkit.formatted_text import (AnyFormattedText, FormattedText,
+                                           merge_formatted_text)
 from rich.logging import RichHandler
 
-from falyx.console import console
+from falyx.themes.colors import OneColors
+
+logger = logging.getLogger("falyx")
 
 T = TypeVar("T")
 
-
+async def _noop(*args, **kwargs):
-async def _noop(*_, **__):
     pass
 
-
-def get_program_invocation() -> str:
-    """Returns the recommended program invocation prefix."""
-    script = sys.argv[0]
-    program = shutil.which(script)
-    if program:
-        return os.path.basename(program)
-
-    executable = sys.executable
-    if "python" in executable:
-        return f"python {script}"
-    return script
-
-
 def is_coroutine(function: Callable[..., Any]) -> bool:
     return inspect.iscoroutinefunction(function)
 
@@ -63,10 +32,6 @@ def ensure_async(function: Callable[..., T]) -> Callable[..., Awaitable[T]]:
     @functools.wraps(function)
     async def async_wrapper(*args, **kwargs) -> T:
         return function(*args, **kwargs)
-
-    if not callable(function):
-        raise TypeError(f"{function} is not callable")
-
     return async_wrapper
 
 
@@ -80,33 +45,41 @@ def chunks(iterator, size):
         yield chunk
 
 
+async def async_confirm(message: AnyFormattedText = "Are you sure?") -> bool:
+    session: PromptSession = PromptSession()
+    while True:
+        merged_message: AnyFormattedText = merge_formatted_text([message, FormattedText([(OneColors.LIGHT_YELLOW_b, " [Y/n] ")])])
+        answer: str = (await session.prompt_async(merged_message)).strip().lower()
+        if answer in ("y", "yes"):
+            return True
+        if answer in ("n", "no", ""):
+            return False
+        print("Please enter y or n.")
+
+
 class CaseInsensitiveDict(dict):
     """A case-insensitive dictionary that treats all keys as uppercase."""
 
-    def _normalize_key(self, key):
-        return key.upper() if isinstance(key, str) else key
-
     def __setitem__(self, key, value):
-        super().__setitem__(self._normalize_key(key), value)
+        super().__setitem__(key.upper(), value)
 
     def __getitem__(self, key):
-        return super().__getitem__(self._normalize_key(key))
+        return super().__getitem__(key.upper())
 
     def __contains__(self, key):
-        return super().__contains__(self._normalize_key(key))
+        return super().__contains__(key.upper())
 
     def get(self, key, default=None):
-        return super().get(self._normalize_key(key), default)
+        return super().get(key.upper(), default)
 
     def pop(self, key, default=None):
-        return super().pop(self._normalize_key(key), default)
+        return super().pop(key.upper(), default)
 
     def update(self, other=None, **kwargs):
-        items = {}
         if other:
-            items.update({self._normalize_key(k): v for k, v in other.items()})
+            other = {k.upper(): v for k, v in other.items()}
-        items.update({self._normalize_key(k): v for k, v in kwargs.items()})
+        kwargs = {k.upper(): v for k, v in kwargs.items()}
-        super().update(items)
+        super().update(other, **kwargs)
 
 
 def running_in_container() -> bool:
@@ -131,13 +104,11 @@ def setup_logging(
     console_log_level: int = logging.WARNING,
 ):
     """
-    Configure logging for Falyx with support for both CLI-friendly and structured
+    Configure logging for Falyx with support for both CLI-friendly and structured JSON output.
-    JSON output.
 
-    This function sets up separate logging handlers for console and file output,
+    This function sets up separate logging handlers for console and file output, with optional
-    with optional support for JSON formatting. It also auto-detects whether the
+    support for JSON formatting. It also auto-detects whether the application is running inside
-    application is running inside a container to default to machine-readable logs
+    a container to default to machine-readable logs when appropriate.
-    when appropriate.
 
     Args:
         mode (str | None):
@@ -160,8 +131,7 @@ def setup_logging(
         - Clears existing root handlers before setup.
         - Configures console logging using either Rich (for CLI) or JSON formatting.
         - Configures file logging in plain text or JSON based on `json_log_to_file`.
-        - Automatically sets logging levels for noisy third-party modules
+        - Automatically sets logging levels for noisy third-party modules (`urllib3`, `asyncio`).
-          (`urllib3`, `asyncio`, `markdown_it`).
         - Propagates logs from the "falyx" logger to ensure centralized output.
 
     Raises:
@@ -182,7 +152,6 @@ def setup_logging(
 
     if mode == "cli":
         console_handler: RichHandler | logging.StreamHandler = RichHandler(
-            console=console,
             rich_tracebacks=True,
             show_time=True,
             show_level=True,
@@ -193,9 +162,7 @@ def setup_logging(
     elif mode == "json":
         console_handler = logging.StreamHandler()
         console_handler.setFormatter(
-            pythonjsonlogger.json.JsonFormatter(
+            pythonjsonlogger.json.JsonFormatter("%(asctime)s %(name)s %(levelname)s %(message)s")
-                "%(asctime)s %(name)s %(levelname)s %(message)s"
-            )
         )
     else:
         raise ValueError(f"Invalid log mode: {mode}")
@@ -203,21 +170,17 @@ def setup_logging(
     console_handler.setLevel(console_log_level)
     root.addHandler(console_handler)
 
-    file_handler = logging.FileHandler(log_filename, "a", "UTF-8")
+    file_handler = logging.FileHandler(log_filename)
     file_handler.setLevel(file_log_level)
     if json_log_to_file:
         file_handler.setFormatter(
-            pythonjsonlogger.json.JsonFormatter(
+            pythonjsonlogger.json.JsonFormatter("%(asctime)s %(name)s %(levelname)s %(message)s")
-                "%(asctime)s %(name)s %(levelname)s %(message)s"
-            )
         )
     else:
-        file_handler.setFormatter(
+        file_handler.setFormatter(logging.Formatter(
-            logging.Formatter(
             "%(asctime)s [%(name)s] [%(levelname)s] %(message)s",
-                datefmt="%Y-%m-%d %H:%M:%S",
+            datefmt="%Y-%m-%d %H:%M:%S"
-            )
+        ))
-        )
     root.addHandler(file_handler)
 
     logging.getLogger("urllib3").setLevel(logging.WARNING)

falyx/validators.py

@@ -1,219 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""
-Input validators for use with Prompt Toolkit and interactive Falyx CLI workflows.
-
-This module defines reusable `Validator` instances and subclasses that enforce valid
-user input during prompts—especially for selection actions, confirmations, and
-argument parsing.
-
-Included Validators:
-- CommandValidator: Validates if the input matches a known command.
-- int_range_validator: Enforces numeric input within a range.
-- key_validator: Ensures the entered value matches a valid selection key.
-- yes_no_validator: Restricts input to 'Y' or 'N'.
-- word_validator / words_validator: Accepts specific valid words (case-insensitive).
-- MultiIndexValidator: Validates numeric list input (e.g. "1,2,3").
-- MultiKeyValidator: Validates string key list input (e.g. "A,B,C").
-
-These validators integrate directly into `PromptSession.prompt_async()` to
-enforce correctness and provide helpful error messages.
-"""
-from typing import TYPE_CHECKING, KeysView, Sequence
-
-from prompt_toolkit.validation import ValidationError, Validator
-
-if TYPE_CHECKING:
-    from falyx.falyx import Falyx
-
-
-class CommandValidator(Validator):
-    """Validator to check if the input is a valid command."""
-
-    def __init__(self, falyx: "Falyx", error_message: str) -> None:
-        super().__init__()
-        self.falyx = falyx
-        self.error_message = error_message
-
-    def validate(self, document) -> None:
-        if not document.text:
-            raise ValidationError(
-                message=self.error_message,
-                cursor_position=len(document.text),
-            )
-
-    async def validate_async(self, document) -> None:
-        text = document.text
-        if not text:
-            raise ValidationError(
-                message=self.error_message,
-                cursor_position=len(text),
-            )
-        is_preview, choice, _, __ = await self.falyx.get_command(text, from_validate=True)
-        if is_preview:
-            return None
-        if not choice:
-            raise ValidationError(
-                message=self.error_message,
-                cursor_position=len(text),
-            )
-
-
-def int_range_validator(minimum: int, maximum: int) -> Validator:
-    """Validator for integer ranges."""
-
-    def validate(text: str) -> bool:
-        try:
-            value = int(text)
-            if not minimum <= value <= maximum:
-                return False
-            return True
-        except ValueError:
-            return False
-
-    return Validator.from_callable(
-        validate,
-        error_message=f"Invalid input. Enter a number between {minimum} and {maximum}.",
-    )
-
-
-def key_validator(keys: Sequence[str] | KeysView[str]) -> Validator:
-    """Validator for key inputs."""
-
-    def validate(text: str) -> bool:
-        if text.upper() not in [key.upper() for key in keys]:
-            return False
-        return True
-
-    return Validator.from_callable(
-        validate, error_message=f"Invalid input. Available keys: {', '.join(keys)}."
-    )
-
-
-def yes_no_validator() -> Validator:
-    """Validator for yes/no inputs."""
-
-    def validate(text: str) -> bool:
-        if text.upper() not in ["Y", "N"]:
-            return False
-        return True
-
-    return Validator.from_callable(validate, error_message="Enter 'Y', 'y' or 'N', 'n'.")
-
-
-def words_validator(
-    keys: Sequence[str] | KeysView[str], error_message: str | None = None
-) -> Validator:
-    """Validator for specific word inputs."""
-
-    def validate(text: str) -> bool:
-        if text.upper() not in [key.upper() for key in keys]:
-            return False
-        return True
-
-    if error_message is None:
-        error_message = f"Invalid input. Choices: {{{', '.join(keys)}}}."
-
-    return Validator.from_callable(validate, error_message=error_message)
-
-
-def word_validator(word: str) -> Validator:
-    """Validator for specific word inputs."""
-    if word.upper() == "N":
-        raise ValueError(
-            "The word 'N' is reserved for yes/no validation. Use yes_no_validator instead."
-        )
-
-    def validate(text: str) -> bool:
-        if text.upper().strip() == "N":
-            return True
-        return text.upper().strip() == word.upper()
-
-    return Validator.from_callable(validate, error_message=f"Enter '{word}' or 'N', 'n'.")
-
-
-class MultiIndexValidator(Validator):
-    def __init__(
-        self,
-        minimum: int,
-        maximum: int,
-        number_selections: int | str,
-        separator: str,
-        allow_duplicates: bool,
-        cancel_key: str,
-    ) -> None:
-        self.minimum = minimum
-        self.maximum = maximum
-        self.number_selections = number_selections
-        self.separator = separator
-        self.allow_duplicates = allow_duplicates
-        self.cancel_key = cancel_key
-        super().__init__()
-
-    def validate(self, document):
-        selections = [
-            index.strip() for index in document.text.strip().split(self.separator)
-        ]
-        if not selections or selections == [""]:
-            raise ValidationError(message="Select at least 1 item.")
-        if self.cancel_key in selections and len(selections) == 1:
-            return
-        elif self.cancel_key in selections:
-            raise ValidationError(message="Cancel key must be selected alone.")
-        for selection in selections:
-            try:
-                index = int(selection)
-                if not self.minimum <= index <= self.maximum:
-                    raise ValidationError(
-                        message=f"Invalid selection: {selection}. Select a number between {self.minimum} and {self.maximum}."
-                    )
-            except ValueError:
-                raise ValidationError(
-                    message=f"Invalid selection: {selection}. Select a number between {self.minimum} and {self.maximum}."
-                )
-            if not self.allow_duplicates and selections.count(selection) > 1:
-                raise ValidationError(message=f"Duplicate selection: {selection}")
-        if isinstance(self.number_selections, int):
-            if self.number_selections == 1 and len(selections) > 1:
-                raise ValidationError(message="Invalid selection. Select only 1 item.")
-            if len(selections) != self.number_selections:
-                raise ValidationError(
-                    message=f"Select exactly {self.number_selections} items separated by '{self.separator}'"
-                )
-
-
-class MultiKeyValidator(Validator):
-    def __init__(
-        self,
-        keys: Sequence[str] | KeysView[str],
-        number_selections: int | str,
-        separator: str,
-        allow_duplicates: bool,
-        cancel_key: str,
-    ) -> None:
-        self.keys = keys
-        self.separator = separator
-        self.number_selections = number_selections
-        self.allow_duplicates = allow_duplicates
-        self.cancel_key = cancel_key
-        super().__init__()
-
-    def validate(self, document):
-        selections = [key.strip() for key in document.text.strip().split(self.separator)]
-        if not selections or selections == [""]:
-            raise ValidationError(message="Select at least 1 item.")
-        if self.cancel_key in selections and len(selections) == 1:
-            return
-        elif self.cancel_key in selections:
-            raise ValidationError(message="Cancel key must be selected alone.")
-        for selection in selections:
-            if selection.upper() not in [key.upper() for key in self.keys]:
-                raise ValidationError(message=f"Invalid selection: {selection}")
-            if not self.allow_duplicates and selections.count(selection) > 1:
-                raise ValidationError(message=f"Duplicate selection: {selection}")
-        if isinstance(self.number_selections, int):
-            if self.number_selections == 1 and len(selections) > 1:
-                raise ValidationError(message="Invalid selection. Select only 1 item.")
-            if len(selections) != self.number_selections:
-                raise ValidationError(
-                    message=f"Select exactly {self.number_selections} items separated by '{self.separator}'"
-                )

falyx/version.py

@@ -1 +1 @@
-__version__ = "0.1.80"
+__version__ = "0.1.5"

pylintrc

@@ -146,10 +146,7 @@ disable=abstract-method,
         wrong-import-order,
         xrange-builtin,
         zip-builtin-not-iterating,
-        broad-exception-caught,
+        broad-exception-caught
-        too-many-positional-arguments,
-        inconsistent-quotes,
-        import-outside-toplevel
 
 
 [REPORTS]
@@ -263,7 +260,7 @@ generated-members=
 [FORMAT]
 
 # Maximum number of characters on a single line.
-max-line-length=90
+max-line-length=80
 
 # TODO(https://github.com/PyCQA/pylint/issues/3352): Direct pylint to exempt
 # lines made too long by directives to pytype.

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "falyx"
-version = "0.1.80"
+version = "0.1.5"
 description = "Reliable and introspectable async CLI action framework."
 authors = ["Roland Thomas Jr <roland@rtj.dev>"]
 license = "MIT"
@@ -10,30 +10,18 @@ packages = [{ include = "falyx" }]
 [tool.poetry.dependencies]
 python = ">=3.10"
 prompt_toolkit = "^3.0"
-rich = "^14.0"
+rich = "^13.0"
 pydantic = "^2.0"
 python-json-logger = "^3.3.0"
-toml = "^0.10"
-pyyaml = "^6.0"
-aiohttp = "^3.11"
-python-dateutil = "^2.8"
 
 [tool.poetry.group.dev.dependencies]
-pytest = "^8.3.5"
+pytest = "^7.0"
 pytest-asyncio = "^0.20"
 ruff = "^0.3"
-toml = "^0.10"
-black = { version = "^25.0", allow-prereleases = true }
-mypy = { version = "^1.0", allow-prereleases = true }
-isort = { version = "^5.0", allow-prereleases = true }
-pytest-cov = "^4.0"
-mkdocs = "^1.6.1"
-mkdocs-material = "^9.6.14"
-mkdocstrings = {extras = ["python"], version = "^0.29.1"}
-mike = "^2.1.3"
 
 [tool.poetry.scripts]
-falyx = "falyx.__main__:main"
+falyx = "falyx.cli.main:main"
+sync-version = "scripts.sync_version:main"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]
@@ -42,7 +30,7 @@ build-backend = "poetry.core.masonry.api"
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
-#asyncio_default_fixture_loop_scope = "function"
+asyncio_default_fixture_loop_scope = "function"
 
 [tool.pylint."MESSAGES CONTROL"]
 disable = ["broad-exception-caught"]

scripts/sync_version.py

@@ -1,9 +1,7 @@
 """scripts/sync_version.py"""
 
-from pathlib import Path
-
 import toml
-
+from pathlib import Path
 
 def main():
     pyproject_path = Path(__file__).parent.parent / "pyproject.toml"
@@ -15,6 +13,5 @@ def main():
     version_path.write_text(f'__version__ = "{version}"\n')
     print(f"✅ Synced version: {version} → {version_path}")
 
-
 if __name__ == "__main__":
     main()