falyx 0.1.24__tar.gz → 0.1.26__tar.gz

{falyx-0.1.24 → falyx-0.1.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: falyx
-Version: 0.1.24
+Version: 0.1.26
 Summary: Reliable and introspectable async CLI action framework.
 License: MIT
 Author: Roland Thomas Jr
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiohttp (>=3.11,<4.0)
 Requires-Dist: prompt_toolkit (>=3.0,<4.0)
 Requires-Dist: pydantic (>=2.0,<3.0)
 Requires-Dist: python-json-logger (>=3.3.0,<4.0.0)

{falyx-0.1.24 → falyx-0.1.26}/falyx/__init__.py

@@ -7,7 +7,7 @@ Licensed under the MIT License. See LICENSE file for details.
 
 import logging
 
-from .action import Action, ActionGroup, ChainedAction, ProcessAction
+from .action.action import Action, ActionGroup, ChainedAction, ProcessAction
 from .command import Command
 from .context import ExecutionContext, SharedContext
 from .execution_registry import ExecutionRegistry

falyx-0.1.26/falyx/action/__init__.py

@@ -0,0 +1,41 @@
+"""
+Falyx CLI Framework
+
+Copyright (c) 2025 rtj.dev LLC.
+Licensed under the MIT License. See LICENSE file for details.
+"""
+
+from .action import (
+    Action,
+    ActionGroup,
+    BaseAction,
+    ChainedAction,
+    FallbackAction,
+    LiteralInputAction,
+    ProcessAction,
+)
+from .action_factory import ActionFactoryAction
+from .http_action import HTTPAction
+from .io_action import BaseIOAction, ShellAction
+from .menu_action import MenuAction
+from .select_file_action import SelectFileAction
+from .selection_action import SelectionAction
+from .signal_action import SignalAction
+
+__all__ = [
+    "Action",
+    "ActionGroup",
+    "BaseAction",
+    "ChainedAction",
+    "ProcessAction",
+    "ActionFactoryAction",
+    "HTTPAction",
+    "BaseIOAction",
+    "ShellAction",
+    "SelectionAction",
+    "SelectFileAction",
+    "MenuAction",
+    "SignalAction",
+    "FallbackAction",
+    "LiteralInputAction",
+]

{falyx-0.1.24/falyx → falyx-0.1.26/falyx/action}/action.py

@@ -48,7 +48,7 @@ from falyx.hook_manager import Hook, HookManager, HookType
 from falyx.logger import logger
 from falyx.options_manager import OptionsManager
 from falyx.retry import RetryHandler, RetryPolicy
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 from falyx.utils import ensure_async
 
 

{falyx-0.1.24/falyx → falyx-0.1.26/falyx/action}/action_factory.py

@@ -4,13 +4,13 @@ from typing import Any
 
 from rich.tree import Tree
 
-from falyx.action import BaseAction
+from falyx.action.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.colors import OneColors
+from falyx.themes import OneColors
 
 
 class ActionFactoryAction(BaseAction):

{falyx-0.1.24/falyx → falyx-0.1.26/falyx/action}/http_action.py

@@ -13,11 +13,11 @@ from typing import Any
 import aiohttp
 from rich.tree import Tree
 
-from falyx.action import Action
+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.colors import OneColors
+from falyx.themes import OneColors
 
 
 async def close_shared_http_session(context: ExecutionContext) -> None:

{falyx-0.1.24/falyx → falyx-0.1.26/falyx/action}/io_action.py

@@ -23,13 +23,13 @@ from typing import Any
 
 from rich.tree import Tree
 
-from falyx.action import BaseAction
+from falyx.action.action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.exceptions import FalyxError
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookManager, HookType
 from falyx.logger import logger
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 
 
 class BaseIOAction(BaseAction):

{falyx-0.1.24/falyx → falyx-0.1.26/falyx/action}/menu_action.py

@@ -1,6 +1,5 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
 """menu_action.py"""
-from dataclasses import dataclass
 from typing import Any
 
 from prompt_toolkit import PromptSession
@@ -8,91 +7,16 @@ from rich.console import Console
 from rich.table import Table
 from rich.tree import Tree
 
-from falyx.action import BaseAction
+from falyx.action.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.selection import prompt_for_selection, render_table_base
-from falyx.signal_action import SignalAction
 from falyx.signals import BackSignal, QuitSignal
-from falyx.themes.colors import OneColors
-from falyx.utils import CaseInsensitiveDict, chunks
-
-
-@dataclass
-class MenuOption:
-    """Represents a single menu option with a description and an action to execute."""
-
-    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}[/]"
-
-
-class MenuOptionMap(CaseInsensitiveDict):
-    """
-    Manages menu options including validation, reserved key protection,
-    and special signal entries like Quit and Back.
-    """
-
-    RESERVED_KEYS = {"Q", "B"}
-
-    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):
-        self._add_reserved(
-            "Q",
-            MenuOption("Exit", SignalAction("Quit", QuitSignal()), OneColors.DARK_RED),
-        )
-        self._add_reserved(
-            "B",
-            MenuOption("Back", SignalAction("Back", BackSignal()), OneColors.DARK_YELLOW),
-        )
-
-    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 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
+from falyx.themes import OneColors
+from falyx.utils import chunks
 
 
 class MenuAction(BaseAction):

{falyx-0.1.24/falyx → falyx-0.1.26/falyx/action}/select_file_action.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import csv
 import json
 import xml.etree.ElementTree as ET
-from enum import Enum
 from pathlib import Path
 from typing import Any
 
@@ -15,7 +14,8 @@ from prompt_toolkit import PromptSession
 from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action import BaseAction
+from falyx.action.action import BaseAction
+from falyx.action.types import FileReturnType
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
@@ -25,41 +25,7 @@ from falyx.selection import (
     prompt_for_selection,
     render_selection_dict_table,
 )
-from falyx.themes.colors import OneColors
-
-
-class FileReturnType(Enum):
-    """Enum for file return types."""
-
-    TEXT = "text"
-    PATH = "path"
-    JSON = "json"
-    TOML = "toml"
-    YAML = "yaml"
-    CSV = "csv"
-    TSV = "tsv"
-    XML = "xml"
-
-    @classmethod
-    def _get_alias(cls, value: str) -> str:
-        aliases = {
-            "yml": "yaml",
-            "txt": "text",
-            "file": "path",
-            "filepath": "path",
-        }
-        return aliases.get(value, value)
-
-    @classmethod
-    def _missing_(cls, value: object) -> FileReturnType:
-        if isinstance(value, str):
-            normalized = value.lower()
-            alias = cls._get_alias(normalized)
-            for member in cls:
-                if member.value == alias:
-                    return member
-        valid = ", ".join(member.value for member in cls)
-        raise ValueError(f"Invalid FileReturnType: '{value}'. Must be one of: {valid}")
+from falyx.themes import OneColors
 
 
 class SelectFileAction(BaseAction):

{falyx-0.1.24/falyx → falyx-0.1.26/falyx/action}/selection_action.py

@@ -6,7 +6,7 @@ from prompt_toolkit import PromptSession
 from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action import BaseAction
+from falyx.action.action import BaseAction
 from falyx.context import ExecutionContext
 from falyx.execution_registry import ExecutionRegistry as er
 from falyx.hook_manager import HookType
@@ -18,7 +18,7 @@ from falyx.selection import (
     render_selection_dict_table,
     render_selection_indexed_table,
 )
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 from falyx.utils import CaseInsensitiveDict
 
 

falyx-0.1.26/falyx/action/signal_action.py

@@ -0,0 +1,43 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""signal_action.py"""
+from rich.tree import Tree
+
+from falyx.action.action import Action
+from falyx.signals import FlowSignal
+from falyx.themes import OneColors
+
+
+class SignalAction(Action):
+    """
+    An action that raises a control flow signal when executed.
+
+    Useful for exiting a menu, going back, or halting execution gracefully.
+    """
+
+    def __init__(self, name: str, signal: Exception):
+        self.signal = signal
+        super().__init__(name, action=self.raise_signal)
+
+    async def raise_signal(self, *args, **kwargs):
+        raise self.signal
+
+    @property
+    def signal(self):
+        return self._signal
+
+    @signal.setter
+    def signal(self, value: 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-0.1.26/falyx/action/types.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class FileReturnType(Enum):
+    """Enum for file return types."""
+
+    TEXT = "text"
+    PATH = "path"
+    JSON = "json"
+    TOML = "toml"
+    YAML = "yaml"
+    CSV = "csv"
+    TSV = "tsv"
+    XML = "xml"
+
+    @classmethod
+    def _get_alias(cls, value: str) -> str:
+        aliases = {
+            "yml": "yaml",
+            "txt": "text",
+            "file": "path",
+            "filepath": "path",
+        }
+        return aliases.get(value, value)
+
+    @classmethod
+    def _missing_(cls, value: object) -> FileReturnType:
+        if isinstance(value, str):
+            normalized = value.lower()
+            alias = cls._get_alias(normalized)
+            for member in cls:
+                if member.value == alias:
+                    return member
+        valid = ", ".join(member.value for member in cls)
+        raise ValueError(f"Invalid FileReturnType: '{value}'. Must be one of: {valid}")

{falyx-0.1.24 → falyx-0.1.26}/falyx/bottom_bar.py

@@ -8,7 +8,7 @@ from prompt_toolkit.key_binding import KeyBindings
 from rich.console import Console
 
 from falyx.options_manager import OptionsManager
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 from falyx.utils import CaseInsensitiveDict, chunks
 
 

{falyx-0.1.24 → falyx-0.1.26}/falyx/command.py

@@ -26,19 +26,19 @@ from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator
 from rich.console import Console
 from rich.tree import Tree
 
-from falyx.action import Action, ActionGroup, BaseAction, ChainedAction
+from falyx.action.action import Action, ActionGroup, BaseAction, ChainedAction
+from falyx.action.io_action import BaseIOAction
 from falyx.context import ExecutionContext
 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 HookManager, HookType
-from falyx.io_action import BaseIOAction
 from falyx.logger import logger
 from falyx.options_manager import OptionsManager
 from falyx.prompt_utils import confirm_async, should_prompt_user
 from falyx.retry import RetryPolicy
 from falyx.retry_utils import enable_retries_recursively
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 from falyx.utils import _noop, ensure_async
 
 console = Console(color_system="auto")

{falyx-0.1.24 → falyx-0.1.26}/falyx/config.py

@@ -13,12 +13,12 @@ import yaml
 from pydantic import BaseModel, Field, field_validator, model_validator
 from rich.console import Console
 
-from falyx.action import Action, BaseAction
+from falyx.action.action import Action, BaseAction
 from falyx.command import Command
 from falyx.falyx import Falyx
 from falyx.logger import logger
 from falyx.retry import RetryPolicy
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 
 console = Console(color_system="auto")
 
@@ -72,10 +72,10 @@ class RawCommand(BaseModel):
     description: str
     action: str
 
-    args: tuple[Any, ...] = ()
-    kwargs: dict[str, Any] = {}
-    aliases: list[str] = []
-    tags: list[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
@@ -86,13 +86,13 @@ class RawCommand(BaseModel):
     spinner_message: str = "Processing..."
     spinner_type: str = "dots"
     spinner_style: str = OneColors.CYAN
-    spinner_kwargs: dict[str, Any] = {}
+    spinner_kwargs: dict[str, Any] = Field(default_factory=dict)
 
-    before_hooks: list[Callable] = []
-    success_hooks: list[Callable] = []
-    error_hooks: list[Callable] = []
-    after_hooks: list[Callable] = []
-    teardown_hooks: list[Callable] = []
+    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
@@ -129,6 +129,60 @@ def convert_commands(raw_commands: list[dict[str, Any]]) -> list[Command]:
     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."""
 
@@ -140,6 +194,7 @@ class FalyxConfig(BaseModel):
     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:
@@ -160,10 +215,12 @@ class FalyxConfig(BaseModel):
             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) -> Falyx:
+def loader(file_path: Path | str, _depth: int = 0) -> Falyx:
     """
     Load Falyx CLI configuration from a YAML or TOML file.
 
@@ -183,6 +240,9 @@ def loader(file_path: Path | str) -> Falyx:
     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:
@@ -212,6 +272,7 @@ def loader(file_path: Path | str) -> Falyx:
         )
 
     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 > ")]),
@@ -219,4 +280,5 @@ def loader(file_path: Path | str) -> Falyx:
         welcome_message=raw_config.get("welcome_message", ""),
         exit_message=raw_config.get("exit_message", ""),
         commands=commands,
+        submenus=submenus,
     ).to_falyx()

{falyx-0.1.24 → falyx-0.1.26}/falyx/execution_registry.py

@@ -37,7 +37,7 @@ from rich.table import Table
 
 from falyx.context import ExecutionContext
 from falyx.logger import logger
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 
 
 class ExecutionRegistry:

{falyx-0.1.24 → falyx-0.1.26}/falyx/falyx.py

@@ -19,6 +19,8 @@ for running commands, actions, and workflows. It supports:
 Falyx enables building flexible, robust, and user-friendly
 terminal applications with minimal boilerplate.
 """
+from __future__ import annotations
+
 import asyncio
 import logging
 import sys
@@ -38,7 +40,7 @@ from rich.console import Console
 from rich.markdown import Markdown
 from rich.table import Table
 
-from falyx.action import Action, BaseAction
+from falyx.action.action import Action, BaseAction
 from falyx.bottom_bar import BottomBar
 from falyx.command import Command
 from falyx.context import ExecutionContext
@@ -56,7 +58,7 @@ from falyx.options_manager import OptionsManager
 from falyx.parsers import get_arg_parsers
 from falyx.retry import RetryPolicy
 from falyx.signals import BackSignal, QuitSignal
-from falyx.themes.colors import OneColors, get_nord_theme
+from falyx.themes import OneColors, get_nord_theme
 from falyx.utils import CaseInsensitiveDict, chunks, get_program_invocation
 from falyx.version import __version__
 
@@ -528,14 +530,15 @@ class Falyx:
         )
 
     def add_submenu(
-        self, key: str, description: str, submenu: "Falyx", *, style: str = OneColors.CYAN
+        self, key: str, description: str, submenu: Falyx, *, style: str = OneColors.CYAN
     ) -> None:
         """Adds a submenu to the menu."""
         if not isinstance(submenu, Falyx):
             raise NotAFalyxError("submenu must be an instance of Falyx.")
         self._validate_command_key(key)
         self.add_command(key, description, submenu.menu, style=style)
-        submenu.update_exit_command(key="B", description="Back", aliases=["BACK"])
+        if submenu.exit_command.key == "Q":
+            submenu.update_exit_command(key="B", description="Back", aliases=["BACK"])
 
     def add_commands(self, commands: list[Command] | list[dict]) -> None:
         """Adds a list of Command instances or config dicts."""

{falyx-0.1.24 → falyx-0.1.26}/falyx/hooks.py

@@ -6,7 +6,7 @@ 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
 
 
 class ResultReporter:

falyx-0.1.26/falyx/menu.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from falyx.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 option with a description and an action to execute."""
+
+    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}[/]"
+
+
+class MenuOptionMap(CaseInsensitiveDict):
+    """
+    Manages menu options including validation, reserved key protection,
+    and special signal entries like Quit and Back.
+    """
+
+    RESERVED_KEYS = {"Q", "B"}
+
+    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(
+            "Q",
+            MenuOption("Exit", SignalAction("Quit", QuitSignal()), OneColors.DARK_RED),
+        )
+        self._add_reserved(
+            "B",
+            MenuOption("Back", SignalAction("Back", BackSignal()), OneColors.DARK_YELLOW),
+        )
+
+    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 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

{falyx-0.1.24 → falyx-0.1.26}/falyx/prompt_utils.py

@@ -8,7 +8,7 @@ from prompt_toolkit.formatted_text import (
 )
 
 from falyx.options_manager import OptionsManager
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 from falyx.validators import yes_no_validator
 
 

{falyx-0.1.24 → falyx-0.1.26}/falyx/protocols.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Any, Protocol
 
-from falyx.action import BaseAction
+from falyx.action.action import BaseAction
 
 
 class ActionFactoryProtocol(Protocol):

{falyx-0.1.24 → falyx-0.1.26}/falyx/retry_utils.py

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

{falyx-0.1.24 → falyx-0.1.26}/falyx/selection.py

@@ -9,7 +9,7 @@ from rich.console import Console
 from rich.markup import escape
 from rich.table import Table
 
-from falyx.themes.colors import OneColors
+from falyx.themes import OneColors
 from falyx.utils import chunks
 from falyx.validators import int_range_validator, key_validator
 

falyx-0.1.26/falyx/themes/__init__.py

@@ -0,0 +1,15 @@
+"""
+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-0.1.26/falyx/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.26"

{falyx-0.1.24 → falyx-0.1.26}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "falyx"
-version = "0.1.24"
+version = "0.1.26"
 description = "Reliable and introspectable async CLI action framework."
 authors = ["Roland Thomas Jr <roland@rtj.dev>"]
 license = "MIT"
@@ -15,6 +15,7 @@ pydantic = "^2.0"
 python-json-logger = "^3.3.0"
 toml = "^0.10"
 pyyaml = "^6.0"
+aiohttp = "^3.11"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.5"

falyx-0.1.24/falyx/signal_action.py

@@ -1,31 +0,0 @@
-# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""signal_action.py"""
-from falyx.action import Action
-from falyx.signals import FlowSignal
-
-
-class SignalAction(Action):
-    """
-    An action that raises a control flow signal when executed.
-
-    Useful for exiting a menu, going back, or halting execution gracefully.
-    """
-
-    def __init__(self, name: str, signal: Exception):
-        if not isinstance(signal, FlowSignal):
-            raise TypeError(
-                f"Signal must be an FlowSignal instance, got {type(signal).__name__}"
-            )
-
-        async def raise_signal(*args, **kwargs):
-            raise signal
-
-        super().__init__(name=name, action=raise_signal)
-        self._signal = signal
-
-    @property
-    def signal(self):
-        return self._signal
-
-    def __str__(self):
-        return f"SignalAction(name={self.name}, signal={self._signal.__class__.__name__})"

falyx-0.1.24/falyx/version.py

@@ -1 +0,0 @@
-__version__ = "0.1.24"