falyx 0.1.22__tar.gz → 0.1.24__tar.gz

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

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

{falyx-0.1.22 → falyx-0.1.24}/falyx/__main__.py

@@ -6,6 +6,7 @@ Licensed under the MIT License. See LICENSE file for details.
 """
 
 import asyncio
+import os
 import sys
 from argparse import Namespace
 from pathlib import Path
@@ -14,7 +15,6 @@ from typing import Any
 from falyx.config import loader
 from falyx.falyx import Falyx
 from falyx.parsers import FalyxParsers, get_arg_parsers
-from falyx.themes.colors import OneColors
 
 
 def find_falyx_config() -> Path | None:
@@ -23,6 +23,7 @@ def find_falyx_config() -> Path | None:
         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",
@@ -68,13 +69,7 @@ def run(args: Namespace) -> Any:
         print("No Falyx config file found. Exiting.")
         return None
 
-    flx = Falyx(
-        title="🛠️ Config-Driven CLI",
-        cli_args=args,
-        columns=4,
-        prompt=[(OneColors.BLUE_b, "FALYX > ")],
-    )
-    flx.add_commands(loader(bootstrap_path))
+    flx: Falyx = loader(bootstrap_path)
     return asyncio.run(flx.run())
 
 

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

@@ -4,7 +4,8 @@
 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.
+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)
@@ -14,7 +15,8 @@ Core guarantees:
 - 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.
+- 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.
@@ -43,10 +45,11 @@ from falyx.debug import register_debug_hooks
 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.retry import RetryHandler, RetryPolicy
 from falyx.themes.colors import OneColors
-from falyx.utils import ensure_async, logger
+from falyx.utils import ensure_async
 
 
 class BaseAction(ABC):
@@ -55,7 +58,8 @@ class BaseAction(ABC):
     complex actions like `ChainedAction` or `ActionGroup`. They can also
     be run independently or as part of Falyx.
 
-    inject_last_result (bool): Whether to inject the previous action's result into kwargs.
+    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').
     _requires_injection (bool): Whether the action requires input injection.
@@ -104,7 +108,9 @@ class BaseAction(ABC):
         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."""
+        """
+        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
@@ -288,8 +294,10 @@ class Action(BaseAction):
 
     def __str__(self):
         return (
-            f"Action(name={self.name!r}, action={getattr(self._action, '__name__', repr(self._action))}, "
-            f"args={self.args!r}, kwargs={self.kwargs!r}, retry={self.retry_policy.enabled})"
+            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})"
         )
 
 
@@ -309,7 +317,7 @@ class LiteralInputAction(Action):
     def __init__(self, value: Any):
         self._value = value
 
-        async def literal(*args, **kwargs):
+        async def literal(*_, **__):
             return value
 
         super().__init__("Input", literal)
@@ -333,14 +341,16 @@ class LiteralInputAction(Action):
 
 class FallbackAction(Action):
     """
-    FallbackAction provides a default value if the previous action failed or returned None.
+    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.
+    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.
@@ -413,16 +423,19 @@ class ChainedAction(BaseAction, ActionListMixin):
     - 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.
+    Best used for defining robust, ordered workflows where each step can depend on
+    previous results.
 
     Args:
         name (str): Name of the chain.
         actions (list): List of actions or literals to execute.
         hooks (HookManager, optional): Hooks for lifecycle events.
-        inject_last_result (bool, optional): Whether to inject last results into kwargs by default.
+        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.
+        return_list (bool, optional): Whether to return a list of all results. False
+                                      returns the last result.
     """
 
     def __init__(
@@ -468,7 +481,7 @@ class ChainedAction(BaseAction, ActionListMixin):
         if not self.actions:
             raise EmptyChainError(f"[{self.name}] No actions to execute.")
 
-        shared_context = SharedContext(name=self.name)
+        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(kwargs)
@@ -503,7 +516,8 @@ class ChainedAction(BaseAction, ActionListMixin):
                         self.actions[index + 1], FallbackAction
                     ):
                         logger.warning(
-                            "[%s] ⚠️ Fallback triggered: %s, recovering with fallback '%s'.",
+                            "[%s] ⚠️ Fallback triggered: %s, recovering with fallback "
+                            "'%s'.",
                             self.name,
                             error,
                             self.actions[index + 1].name,
@@ -579,7 +593,8 @@ class ChainedAction(BaseAction, ActionListMixin):
 
     def __str__(self):
         return (
-            f"ChainedAction(name={self.name!r}, actions={[a.name for a in self.actions]!r}, "
+            f"ChainedAction(name={self.name!r}, "
+            f"actions={[a.name for a in self.actions]!r}, "
             f"auto_inject={self.auto_inject}, return_list={self.return_list})"
         )
 
@@ -613,7 +628,8 @@ class ActionGroup(BaseAction, ActionListMixin):
         name (str): Name of the chain.
         actions (list): List of actions or literals to execute.
         hooks (HookManager, optional): Hooks for lifecycle events.
-        inject_last_result (bool, optional): Whether to inject last results into kwargs by default.
+        inject_last_result (bool, optional): Whether to inject last results into kwargs
+                                             by default.
         inject_into (str, optional): Key name for injection.
     """
 
@@ -643,7 +659,8 @@ class ActionGroup(BaseAction, ActionListMixin):
             return Action(name=action.__name__, action=action)
         else:
             raise TypeError(
-                f"ActionGroup only accepts BaseAction or callable, got {type(action).__name__}"
+                "ActionGroup only accepts BaseAction or callable, got "
+                f"{type(action).__name__}"
             )
 
     def add_action(self, action: BaseAction | Any) -> None:
@@ -653,7 +670,7 @@ class ActionGroup(BaseAction, ActionListMixin):
             action.register_teardown(self.hooks)
 
     async def _run(self, *args, **kwargs) -> list[tuple[str, Any]]:
-        shared_context = SharedContext(name=self.name, is_parallel=True)
+        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(kwargs)
@@ -721,8 +738,8 @@ class ActionGroup(BaseAction, ActionListMixin):
 
     def __str__(self):
         return (
-            f"ActionGroup(name={self.name!r}, actions={[a.name for a in self.actions]!r}, "
-            f"inject_last_result={self.inject_last_result})"
+            f"ActionGroup(name={self.name!r}, actions={[a.name for a in self.actions]!r},"
+            f" inject_last_result={self.inject_last_result})"
         )
 
 
@@ -831,6 +848,7 @@ class ProcessAction(BaseAction):
 
     def __str__(self) -> str:
         return (
-            f"ProcessAction(name={self.name!r}, action={getattr(self.action, '__name__', repr(self.action))}, "
+            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-0.1.22 → falyx-0.1.24}/falyx/action_factory.py

@@ -1,3 +1,5 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""action_factory.py"""
 from typing import Any
 
 from rich.tree import Tree
@@ -6,6 +8,7 @@ from falyx.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
 
@@ -32,7 +35,7 @@ class ActionFactoryAction(BaseAction):
         inject_last_result: bool = False,
         inject_into: str = "last_result",
         preview_args: tuple[Any, ...] = (),
-        preview_kwargs: dict[str, Any] = {},
+        preview_kwargs: dict[str, Any] | None = None,
     ):
         super().__init__(
             name=name,
@@ -41,7 +44,7 @@ class ActionFactoryAction(BaseAction):
         )
         self.factory = factory
         self.preview_args = preview_args
-        self.preview_kwargs = preview_kwargs
+        self.preview_kwargs = preview_kwargs or {}
 
     async def _run(self, *args, **kwargs) -> Any:
         updated_kwargs = self._maybe_inject_last_result(kwargs)
@@ -57,10 +60,20 @@ class ActionFactoryAction(BaseAction):
             generated_action = self.factory(*args, **updated_kwargs)
             if not isinstance(generated_action, BaseAction):
                 raise TypeError(
-                    f"[{self.name}] Factory must return a BaseAction, got {type(generated_action).__name__}"
+                    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(*args, **kwargs)

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

@@ -146,7 +146,7 @@ class BottomBar:
         for k in (key.upper(), key.lower()):
 
             @self.key_bindings.add(k)
-            def _(event):
+            def _(_):
                 toggle_state()
 
     def add_toggle_from_option(
@@ -204,6 +204,6 @@ class BottomBar:
         """Render the bottom bar."""
         lines = []
         for chunk in chunks(self._named_items.values(), self.columns):
-            lines.extend([fn for fn in chunk])
+            lines.extend(list(chunk))
             lines.append(lambda: HTML("\n"))
         return merge_formatted_text([fn() for fn in lines[:-1]])

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

@@ -33,12 +33,13 @@ 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 should_prompt_user
+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.utils import _noop, confirm_async, ensure_async, logger
+from falyx.utils import _noop, ensure_async
 
 console = Console(color_system="auto")
 
@@ -134,7 +135,7 @@ class Command(BaseModel):
             return ensure_async(action)
         raise TypeError("Action must be a callable or an instance of BaseAction")
 
-    def model_post_init(self, __context: Any) -> None:
+    def model_post_init(self, _: Any) -> None:
         """Post-initialization to set up the action and hooks."""
         if self.retry and isinstance(self.action, Action):
             self.action.enable_retry()
@@ -142,14 +143,16 @@ class Command(BaseModel):
             self.action.set_retry_policy(self.retry_policy)
         elif self.retry:
             logger.warning(
-                f"[Command:{self.key}] Retry requested, but action is not an Action instance."
+                "[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(
-                f"[Command:{self.key}] Retry all requested, but action is not a BaseAction instance."
+                "[Command:%s] Retry all requested, but action is not a BaseAction.",
+                self.key,
             )
 
         if self.logging_hooks and isinstance(self.action, BaseAction):
@@ -201,7 +204,7 @@ class Command(BaseModel):
             if self.preview_before_confirm:
                 await self.preview()
             if not await confirm_async(self.confirmation_prompt):
-                logger.info(f"[Command:{self.key}] ❌ Cancelled by user.")
+                logger.info("[Command:%s] ❌ Cancelled by user.", self.key)
                 raise FalyxError(f"[Command:{self.key}] Cancelled by confirmation.")
 
         context.start_timer()
@@ -288,7 +291,7 @@ class Command(BaseModel):
             if self.help_text:
                 console.print(f"[dim]💡 {self.help_text}[/dim]")
             console.print(
-                f"[{OneColors.DARK_RED}]⚠️ Action is not callable or lacks a preview method.[/]"
+                f"[{OneColors.DARK_RED}]⚠️ No preview available for this action.[/]"
             )
 
     def __str__(self) -> str:

falyx-0.1.24/falyx/config.py

@@ -0,0 +1,222 @@
+# Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""config.py
+Configuration loader for Falyx CLI commands."""
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+import toml
+import yaml
+from pydantic import BaseModel, Field, field_validator, model_validator
+from rich.console import Console
+
+from falyx.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
+
+console = Console(color_system="auto")
+
+
+def wrap_if_needed(obj: Any, name=None) -> BaseAction | Command:
+    if isinstance(obj, (BaseAction, Command)):
+        return obj
+    elif callable(obj):
+        return Action(name=name or getattr(obj, "__name__", "unnamed"), action=obj)
+    else:
+        raise TypeError(
+            f"Cannot wrap object of type '{type(obj).__name__}'. "
+            "Expected a function or BaseAction."
+        )
+
+
+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}")
+        sys.exit(1)
+    try:
+        module = importlib.import_module(module_path)
+    except ModuleNotFoundError as error:
+        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):
+    """Raw command model for Falyx CLI configuration."""
+
+    key: str
+    description: str
+    action: str
+
+    args: tuple[Any, ...] = ()
+    kwargs: dict[str, Any] = {}
+    aliases: list[str] = []
+    tags: list[str] = []
+    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_kwargs: dict[str, Any] = {}
+
+    before_hooks: list[Callable] = []
+    success_hooks: list[Callable] = []
+    error_hooks: list[Callable] = []
+    after_hooks: list[Callable] = []
+    teardown_hooks: list[Callable] = []
+
+    logging_hooks: bool = False
+    retry: bool = False
+    retry_all: bool = False
+    retry_policy: RetryPolicy = Field(default_factory=RetryPolicy)
+    requires_input: bool | None = None
+    hidden: bool = False
+    help_text: 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
+
+
+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] = []
+
+    @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)
+        return flx
+
+
+def loader(file_path: Path | str) -> Falyx:
+    """
+    Load Falyx CLI configuration 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
+    - description: short description
+    - action: dotted import path to the action function/class
+
+    Args:
+        file_path (str): Path to the config file (YAML or TOML).
+
+    Returns:
+        Falyx: An instance of the Falyx CLI with loaded commands.
+
+    Raises:
+        ValueError: If the file format is unsupported or file cannot be parsed.
+    """
+    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}")
+
+    suffix = path.suffix
+    with path.open("r", encoding="UTF-8") as config_file:
+        if suffix in (".yaml", ".yml"):
+            raw_config = yaml.safe_load(config_file)
+        elif suffix == ".toml":
+            raw_config = toml.load(config_file)
+        else:
+            raise ValueError(f"Unsupported config format: {suffix}")
+
+    if not isinstance(raw_config, dict):
+        raise ValueError(
+            "Configuration file must contain a dictionary with a list of commands.\n"
+            "Example:\n"
+            "title: 'My CLI'\n"
+            "commands:\n"
+            "  - key: 'a'\n"
+            "    description: 'Example command'\n"
+            "    action: 'my_module.my_function'"
+        )
+
+    commands = convert_commands(raw_config["commands"])
+    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,
+    ).to_falyx()

falyx-0.1.24/falyx/config_schema.py

@@ -0,0 +1,76 @@
+FALYX_CONFIG_SCHEMA = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Falyx CLI Config",
+    "type": "object",
+    "properties": {
+        "title": {"type": "string", "description": "Title shown at top of menu"},
+        "prompt": {
+            "oneOf": [
+                {"type": "string"},
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "prefixItems": [
+                            {
+                                "type": "string",
+                                "description": "Style string (e.g., 'bold #ff0000 italic')",
+                            },
+                            {"type": "string", "description": "Text content"},
+                        ],
+                        "minItems": 2,
+                        "maxItems": 2,
+                    },
+                },
+            ]
+        },
+        "columns": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Number of menu columns",
+        },
+        "welcome_message": {"type": "string"},
+        "exit_message": {"type": "string"},
+        "commands": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["key", "description", "action"],
+                "properties": {
+                    "key": {"type": "string", "minLength": 1},
+                    "description": {"type": "string"},
+                    "action": {
+                        "type": "string",
+                        "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*(\\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+                        "description": "Dotted import path (e.g., mymodule.task)",
+                    },
+                    "args": {"type": "array"},
+                    "kwargs": {"type": "object"},
+                    "aliases": {"type": "array", "items": {"type": "string"}},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                    "style": {"type": "string"},
+                    "confirm": {"type": "boolean"},
+                    "confirm_message": {"type": "string"},
+                    "preview_before_confirm": {"type": "boolean"},
+                    "spinner": {"type": "boolean"},
+                    "spinner_message": {"type": "string"},
+                    "spinner_type": {"type": "string"},
+                    "spinner_style": {"type": "string"},
+                    "logging_hooks": {"type": "boolean"},
+                    "retry": {"type": "boolean"},
+                    "retry_all": {"type": "boolean"},
+                    "retry_policy": {
+                        "type": "object",
+                        "properties": {
+                            "enabled": {"type": "boolean"},
+                            "max_retries": {"type": "integer"},
+                            "delay": {"type": "number"},
+                            "backoff": {"type": "number"},
+                        },
+                    },
+                },
+            },
+        },
+    },
+    "required": ["commands"],
+}