falyx 0.1.22__py3-none-any.whl → 0.1.24__py3-none-any.whl

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"],
+}

falyx/context.py

@@ -29,10 +29,10 @@ 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.
+    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.
@@ -47,7 +47,8 @@ class ExecutionContext(BaseModel):
         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.
+        shared_context (SharedContext | None): Optional shared context when running in
+                                               a chain or group.
 
     Properties:
         duration (float | None): The execution duration in seconds.
@@ -95,7 +96,11 @@ class ExecutionContext(BaseModel):
         self.end_wall = datetime.now()
 
     def get_shared_context(self) -> SharedContext:
-        return self.shared_context or SharedContext(name="default")
+        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:
@@ -190,8 +195,10 @@ class SharedContext(BaseModel):
         errors (list[tuple[int, Exception]]): 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
+        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:
@@ -208,6 +215,7 @@ class SharedContext(BaseModel):
     """
 
     name: str
+    action: Any
     results: list[Any] = Field(default_factory=list)
     errors: list[tuple[int, Exception]] = Field(default_factory=list)
     current_index: int = -1

falyx/debug.py

@@ -1,7 +1,8 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""debug.py"""
 from falyx.context import ExecutionContext
 from falyx.hook_manager import HookManager, HookType
-from falyx.utils import logger
+from falyx.logger import logger
 
 
 def log_before(context: ExecutionContext):

falyx/exceptions.py

@@ -1,4 +1,7 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
+"""exceptions.py"""
+
+
 class FalyxError(Exception):
     """Custom exception for the Menu class."""
 

falyx/execution_registry.py

@@ -1,5 +1,32 @@
 # Falyx CLI Framework — (c) 2025 rtj.dev LLC — MIT Licensed
-"""execution_registry.py"""
+"""
+execution_registry.py
+
+This module provides the `ExecutionRegistry`, a global class for tracking and
+introspecting the execution history of Falyx actions.
+
+The registry captures `ExecutionContext` instances from all executed actions, making it
+easy to debug, audit, and visualize workflow behavior over time. It supports retrieval,
+filtering, clearing, and formatted summary display.
+
+Core Features:
+- Stores all action execution contexts globally (with access by name).
+- Provides live execution summaries in a rich table format.
+- Enables creation of a built-in Falyx Action to print history on demand.
+- Integrates with Falyx's introspectable and hook-driven execution model.
+
+Intended for:
+- Debugging and diagnostics
+- Post-run inspection of CLI workflows
+- Interactive tools built with Falyx
+
+Example:
+    from falyx.execution_registry import ExecutionRegistry as er
+    er.record(context)
+    er.summary()
+"""
+from __future__ import annotations
+
 from collections import defaultdict
 from datetime import datetime
 from typing import Dict, List
@@ -9,10 +36,40 @@ from rich.console import Console
 from rich.table import Table
 
 from falyx.context import ExecutionContext
-from falyx.utils import logger
+from falyx.logger import logger
+from falyx.themes.colors import OneColors
 
 
 class ExecutionRegistry:
+    """
+    Global registry for recording and inspecting Falyx action executions.
+
+    This class captures every `ExecutionContext` generated by a Falyx `Action`,
+    `ChainedAction`, or `ActionGroup`, maintaining both full history and
+    name-indexed access for filtered analysis.
+
+    Methods:
+        - record(context): Stores an ExecutionContext, logging a summary line.
+        - get_all(): Returns the list of all recorded executions.
+        - get_by_name(name): Returns all executions with the given action name.
+        - get_latest(): Returns the most recent execution.
+        - clear(): Wipes the registry for a fresh run.
+        - summary(): Renders a formatted Rich table of all execution results.
+
+    Use Cases:
+        - Debugging chained or factory-generated workflows
+        - Viewing results and exceptions from multiple runs
+        - Embedding a diagnostic command into your CLI for user support
+
+    Note:
+        This registry is in-memory and not persistent. It's reset each time the process
+        restarts or `clear()` is called.
+
+    Example:
+        ExecutionRegistry.record(context)
+        ExecutionRegistry.summary()
+    """
+
     _store_by_name: Dict[str, List[ExecutionContext]] = defaultdict(list)
     _store_all: List[ExecutionContext] = []
     _console = Console(color_system="auto")
@@ -66,10 +123,10 @@ class ExecutionRegistry:
             duration = f"{ctx.duration:.3f}s" if ctx.duration else "n/a"
 
             if ctx.exception:
-                status = "[bold red]❌ Error"
+                status = f"[{OneColors.DARK_RED}]❌ Error"
                 result = repr(ctx.exception)
             else:
-                status = "[green]✅ Success"
+                status = f"[{OneColors.GREEN}]✅ Success"
                 result = repr(ctx.result)
                 if len(result) > 1000:
                     result = f"{result[:1000]}..."
@@ -77,13 +134,3 @@ class ExecutionRegistry:
             table.add_row(ctx.name, start, end, duration, status, 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)