falyx 0.1.0

Reliable and introspectable async CLI action framework.

⚔️ Falyx

Falyx is a resilient, introspectable CLI framework for building robust, asynchronous command-line workflows with:

• ✅ Modular action chaining and rollback
• 🔁 Built-in retry handling
• ⚙️ Full lifecycle hooks (before, after, success, error, teardown)
• 📊 Execution tracing, logging, and introspection
• 🧙‍♂️ Async-first design with Process support
• 🧩 Extensible CLI menus and customizable output

Built for developers who value clarity, resilience, and visibility in their terminal workflows.

---

✨ Why Falyx?

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)
• Handle flaky operations with retries and exponential backoff
• Roll back safely on failure with structured undo logic
• Add observability with execution timing, result tracking, and hooks
• Run in both interactive or headless (scriptable) modes
• Customize output with Rich Tables (grouping, theming, etc.)

---

🔧 Installation

pip install falyx

Or install from source:

git clone https://github.com/yourname/falyx.git
cd falyx
poetry install

---

⚡ Quick Example

from falyx import Action, ChainedAction, Menu
from falyx.hooks import RetryHandler, log_success

async def flaky_step():
    import random, asyncio
    await asyncio.sleep(0.2)
    if random.random() < 0.8:
        raise RuntimeError("Random failure!")
    return "ok"

retry = RetryHandler()

step1 = Action("Step 1", flaky_step)
step1.hooks.register("on_error", retry.retry_on_error)

step2 = Action("Step 2", flaky_step)
step2.hooks.register("on_error", retry.retry_on_error)

chain = ChainedAction("My Pipeline", [step1, step2])
chain.hooks.register("on_success", log_success)

menu = Menu(title="🚀 Falyx Demo")
menu.add_command("R", "Run My Pipeline", chain)

if __name__ == "__main__":
    import asyncio
    asyncio.run(menu.run())

---

📦 Core Features

• ✅ Async-native Action, ChainedAction, ActionGroup
• 🔁 Retry policies + exponential backoff
• ⛓ Rollbacks on chained failures
• 🎛️ Headless or interactive CLI with argparse and prompt_toolkit
• 📊 Built-in execution registry, result tracking, and timing
• 🧠 Supports ProcessAction for CPU-bound workloads
• 🧩 Custom Table rendering for CLI menu views
• 🔍 Hook lifecycle: before, on_success, on_error, after, on_teardown

---

🔍 Execution Trace

[2025-04-14 10:33:22] DEBUG    [Step 1] ⚙ flaky_step()
[2025-04-14 10:33:22] INFO     [Step 1] 🔁 Retrying (1/3) in 1.0s...
[2025-04-14 10:33:23] DEBUG    [Step 1] ✅ Success | Result: ok
[2025-04-14 10:33:23] DEBUG    [My Pipeline] ✅ Result: ['ok', 'ok']

---

🧩 Components

Component	Purpose
Action	Single async task with hook + result injection support
ChainedAction	Sequential task runner with rollback
ActionGroup	Parallel runner for independent tasks
ProcessAction	CPU-bound task in a separate process (multiprocessing)
Menu	CLI runner with toggleable prompt or headless mode
ExecutionContext	Captures metadata per execution
HookManager	Lifecycle hook registration engine

---

🧠 Design Philosophy

“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 gracefully, and log clearly.

---

🛣️ Roadmap

• Retry policy DSL (e.g., max_retries=3, backoff="exponential")
• Metrics export (Prometheus-style)
• Plugin system for menu extensions
• Native support for structured logs + log forwarding
• Web UI for interactive execution history (maybe!)

---

🧑‍💼 License

MIT — use it, fork it, improve it. Attribution appreciated!

---

🌐 falyx.dev — reliable actions, resilient flows

---