# ⚔️ 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 `Table`s (grouping, theming, etc.)

---

## 🔧 Installation

```bash
pip install falyx
```

> Or install from source:

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

---

## ⚡ Quick Example

```python
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

```bash
[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**

---