clidevkit 0.1.0__py3-none-any.whl

clidev/__init__.py

@@ -0,0 +1,67 @@
+"""
+clidev
+======
+
+A framework for building production-ready CLI applications and Terminal
+User Interfaces (TUIs) with minimal code.
+
+    from clidev import App
+
+    app = App("My App")
+    home = app.menu("Home")
+    home.option("Exit", app.exit)
+    app.run()
+"""
+
+from .app import App
+from .cards import Card
+from .dashboard import Dashboard
+from .dialogs import Dialog
+from .events import EventDispatcher
+from .exceptions import (
+    ClidevError,
+    CommandError,
+    NavigationError,
+    PluginError,
+    StorageError,
+    ValidationError,
+    WorkflowError,
+)
+from .forms import Form
+from .menus import Menu
+from .plugins import Plugin
+from .router import Router
+from .state import State
+from .storage import Storage
+from .table import Table
+from .themes import Theme
+from .tree import Tree
+from .workflow import Workflow
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "App",
+    "Card",
+    "Dashboard",
+    "Dialog",
+    "EventDispatcher",
+    "ClidevError",
+    "CommandError",
+    "NavigationError",
+    "PluginError",
+    "StorageError",
+    "ValidationError",
+    "WorkflowError",
+    "Form",
+    "Menu",
+    "Plugin",
+    "Router",
+    "State",
+    "Storage",
+    "Table",
+    "Theme",
+    "Tree",
+    "Workflow",
+    "__version__",
+]

clidev/actions.py

@@ -0,0 +1,73 @@
+"""Conditional-navigation helpers: app.if_value(...).goto(...) and @app.when(...)."""
+
+
+class ConditionBuilder:
+    """Returned by app.if_value(key, **comparisons).
+
+    Usage:
+        app.if_value("Role", equals="Admin").goto("admin_menu")
+        app.if_value("Age", greater_than=18).goto("adult_menu")
+
+    Supported comparisons: equals, not_equals, greater_than, less_than,
+    greater_equal, less_equal, contains, in_list.
+    """
+
+    def __init__(self, app, data: dict, key: str, **comparisons):
+        self.app = app
+        self.data = data
+        self.key = key
+        self.comparisons = comparisons
+
+    def _value(self):
+        return self.data.get(self.key)
+
+    def matches(self) -> bool:
+        value = self._value()
+        for op, target in self.comparisons.items():
+            if op == "equals" and not (value == target):
+                return False
+            if op == "not_equals" and not (value != target):
+                return False
+            if op == "greater_than" and not (value is not None and value > target):
+                return False
+            if op == "less_than" and not (value is not None and value < target):
+                return False
+            if op == "greater_equal" and not (value is not None and value >= target):
+                return False
+            if op == "less_equal" and not (value is not None and value <= target):
+                return False
+            if op == "contains" and not (value is not None and target in value):
+                return False
+            if op == "in_list" and not (value in target):
+                return False
+        return True
+
+    def goto(self, page_name: str):
+        if self.matches():
+            return self.app.goto(page_name)
+        return None
+
+    def then(self, fn):
+        if self.matches():
+            return fn()
+        return None
+
+
+def when(condition_fn):
+    """Decorator factory: @app.when(lambda data: data["Role"] == "Admin")
+
+    Wraps `fn` so that calling wrapped(data) only invokes the original
+    function if condition_fn(data) is truthy.
+    """
+
+    def decorator(fn):
+        def wrapper(data=None, *args, **kwargs):
+            if condition_fn(data):
+                return fn(data, *args, **kwargs) if data is not None else fn(*args, **kwargs)
+            return None
+
+        wrapper.__wrapped__ = fn
+        wrapper.__condition__ = condition_fn
+        return wrapper
+
+    return decorator

clidev/app.py

@@ -0,0 +1,210 @@
+"""The core App class -- the main entry point for every clidev application."""
+
+import sys
+
+from rich.console import Console
+
+from .actions import ConditionBuilder, when as _when
+from .cards import Card
+from .config import Config
+from .dashboard import Dashboard
+from .dialogs import Dialog
+from .events import EventDispatcher
+from .exceptions import ClidevError
+from .forms import Form
+from .logger import Logger
+from .menus import Menu
+from .notifications import Notifications
+from .plugins import PluginManager
+from .progress import ProgressContext
+from .router import Router
+from .scheduler import Scheduler
+from .shell import Shell
+from .spinner import Spinner
+from .state import State
+from .statusbar import StatusBar
+from .storage import Storage
+from .table import Table
+from .tasks import TaskRegistry
+from .themes import Theme
+from .tree import Tree
+from .workflow import Workflow
+
+
+class App:
+    """The main application object.
+
+    app = App("My App")
+    home = app.menu("Home")
+    home.option("Exit", app.exit)
+    app.run()
+    """
+
+    def __init__(self, title: str = "clidev App", theme: str | Theme = "dark",
+                 storage_backend: str = "memory", **config_kwargs):
+        self.title = title
+        self.console = Console()
+        self.config = Config(theme=theme if isinstance(theme, str) else "custom", **config_kwargs)
+
+        self.theme = theme if isinstance(theme, Theme) else Theme.preset(theme)
+        self.logger = Logger(theme=self.theme, console=self.console,
+                              timestamps=self.config.log_timestamps)
+        self.state = State()
+        self.storage = Storage(backend=storage_backend)
+        self.events = EventDispatcher()
+        self.router = Router(app=self)
+        self.tasks = TaskRegistry()
+        self.scheduler = Scheduler()
+        self.plugins = PluginManager(app=self)
+        self.shell = Shell()
+        self.notify = Notifications(theme=self.theme, console=self.console)
+        self.dialog = Dialog(theme=self.theme)
+        self.statusbar = StatusBar(theme=self.theme, console=self.console)
+
+        self._should_exit = False
+        self._last_form_data: dict = {}
+        self._main_menu: Menu | None = None
+
+    # ------------------------------------------------------------------
+    # UI factories
+    # ------------------------------------------------------------------
+    def menu(self, title: str = "Menu") -> Menu:
+        m = Menu(title=title, app=self)
+        if self._main_menu is None:
+            self._main_menu = m
+        return m
+
+    def form(self, title: str = "Form") -> Form:
+        return Form(title=title, app=self)
+
+    def table(self, title: str = "", columns: list[str] | None = None) -> Table:
+        return Table(title=title, columns=columns, theme=self.theme)
+
+    def tree(self, label: str) -> Tree:
+        return Tree(label)
+
+    def card(self, title: str, content: str = "") -> Card:
+        return Card(title, content, theme=self.theme)
+
+    def dashboard(self, title: str = "Dashboard") -> Dashboard:
+        return Dashboard(title, theme=self.theme)
+
+    def workflow(self, name: str = "workflow") -> Workflow:
+        return Workflow(app=self, name=name)
+
+    def progress(self, label: str = "Working", total: int | None = None) -> ProgressContext:
+        return ProgressContext(label=label, total=total)
+
+    def spinner(self, label: str = "Loading...") -> Spinner:
+        return Spinner(label=label, console=self.console)
+
+    # ------------------------------------------------------------------
+    # Navigation / pages
+    # ------------------------------------------------------------------
+    def page(self, name: str, handler=None):
+        return self.router.page(name, handler)
+
+    def goto(self, name: str, *args, **kwargs):
+        return self.router.goto(name, *args, **kwargs)
+
+    def back(self):
+        return self.router.back()
+
+    # ------------------------------------------------------------------
+    # Conditional navigation
+    # ------------------------------------------------------------------
+    def if_value(self, key: str, **comparisons) -> ConditionBuilder:
+        return ConditionBuilder(self, self._last_form_data, key, **comparisons)
+
+    def when(self, condition_fn):
+        return _when(condition_fn)
+
+    # ------------------------------------------------------------------
+    # Events
+    # ------------------------------------------------------------------
+    def on_start(self, fn):
+        return self.events.on("start", fn)
+
+    def on_exit(self, fn):
+        return self.events.on("exit", fn)
+
+    def on_error(self, fn):
+        return self.events.on("error", fn)
+
+    def on_submit(self, form: Form):
+        """Decorator: @app.on_submit(some_form) def handler(data): ..."""
+
+        def decorator(fn):
+            def wrapped(data):
+                self._last_form_data = data
+                return fn(data)
+
+            self.events.on(f"submit:{form.id}", wrapped)
+            return fn
+
+        return decorator
+
+    # ------------------------------------------------------------------
+    # Shell / tasks / plugins
+    # ------------------------------------------------------------------
+    def cmd(self, command: str, capture: bool = False, background: bool = False,
+            check: bool = False, cwd: str | None = None):
+        return self.shell.run(command, capture=capture, background=background,
+                               check=check, cwd=cwd)
+
+    def task(self, fn=None, *, name: str | None = None):
+        return self.tasks.register(fn, name=name)
+
+    def run_task(self, name: str, *args, **kwargs):
+        return self.tasks.run(name, *args, **kwargs)
+
+    def use(self, plugin):
+        return self.plugins.use(plugin)
+
+    # ------------------------------------------------------------------
+    # Notifications shortcuts
+    # ------------------------------------------------------------------
+    def success(self, message: str):
+        self.notify.success(message)
+
+    def error(self, message: str):
+        self.notify.error(message)
+
+    def warning(self, message: str):
+        self.notify.warning(message)
+
+    def info(self, message: str):
+        self.notify.info(message)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+    def exit(self, *args, **kwargs):
+        """Register as a menu handler or call directly to stop the app loop."""
+        if self.config.confirm_exit:
+            if not self.dialog.confirm_exit():
+                return
+        self._should_exit = True
+        self.events.emit("exit")
+        self.plugins.exit_all()
+
+    def run(self):
+        try:
+            self.events.emit("start")
+            self.plugins.start_all()
+            if self._main_menu is not None:
+                self._main_menu.run()
+        except (KeyboardInterrupt, EOFError):
+            self.console.print()
+            self.info("Interrupted. Exiting.")
+        except ClidevError as e:
+            self.events.emit("error", e)
+            self.error(str(e))
+            sys.exit(1)
+        finally:
+            if not self._should_exit:
+                self.events.emit("exit")
+                self.plugins.exit_all()
+
+    def __repr__(self):
+        return f"App(title={self.title!r})"

clidev/builtins/__init__.py

@@ -0,0 +1 @@
+"""Built-in reusable pieces (sample plugins, sample themes) shipped with clidev."""

clidev/builtins/plugins.py

@@ -0,0 +1,26 @@
+"""A couple of small example plugins shipped with clidev for reference."""
+
+from ..plugins import Plugin
+
+
+class GitPlugin(Plugin):
+    """Adds basic git-awareness to an app: checks if the cwd is a repo."""
+
+    name = "git"
+
+    def on_install(self, app):
+        result = app.cmd("git rev-parse --is-inside-work-tree", capture=True)
+        app.state["git_repo"] = result.ok
+
+    def on_start(self, app):
+        if app.state.get("git_repo"):
+            app.logger.debug("Git repository detected.")
+
+
+class DatabasePlugin(Plugin):
+    """Example plugin that ensures a storage backend is ready on start."""
+
+    name = "database"
+
+    def on_start(self, app):
+        app.logger.debug(f"Storage backend ready: {app.storage.all().keys()}")

clidev/cards.py

@@ -0,0 +1,19 @@
+"""Card widget: a titled panel of content, wraps rich.panel.Panel."""
+
+from rich.console import Console
+from rich.panel import Panel
+
+
+class Card:
+    def __init__(self, title: str, content: str = "", theme=None):
+        self.title = title
+        self.content = content
+        self.theme = theme
+        self._console = Console()
+
+    def show(self):
+        color = self.theme.get("primary") if self.theme else None
+        border_style = color or "white"
+        self._console.print(
+            Panel(self.content, title=self.title, border_style=border_style, expand=False)
+        )

clidev/cli.py

@@ -0,0 +1,42 @@
+"""The `clidev` terminal command: project scaffolding utilities."""
+
+import click
+from rich.console import Console
+
+from .generators.project import create_project
+from . import __version__
+
+console = Console()
+
+
+@click.group()
+@click.version_option(__version__, prog_name="clidev")
+def main():
+    """clidev: build production-ready CLI apps and TUIs with minimal code."""
+
+
+@main.command("new")
+@click.argument("name")
+@click.option("--dir", "target_dir", default=None, help="Parent directory to create the project in.")
+def new(name, target_dir):
+    """Scaffold a new clidev project called NAME."""
+    try:
+        project_dir = create_project(name, target_dir)
+    except FileExistsError as e:
+        console.print(f"[bold red]\u2717[/bold red] {e}")
+        raise SystemExit(1)
+
+    console.print(f"[bold green]\u2713[/bold green] Created new clidev project at [bold]{project_dir}[/bold]")
+    console.print("\nNext steps:")
+    console.print(f"  cd {project_dir.name}")
+    console.print("  python app.py")
+
+
+@main.command("version")
+def version():
+    """Print the installed clidev version."""
+    console.print(f"clidev {__version__}")
+
+
+if __name__ == "__main__":
+    main()

clidev/colors.py

@@ -0,0 +1,27 @@
+"""Color name constants and helpers, mapped to rich-compatible color strings."""
+
+PALETTE = {
+    "blue": "#3B82F6",
+    "green": "#22C55E",
+    "red": "#EF4444",
+    "yellow": "#EAB308",
+    "orange": "#F97316",
+    "purple": "#A855F7",
+    "cyan": "#06B6D4",
+    "magenta": "#D946EF",
+    "white": "#FFFFFF",
+    "black": "#000000",
+    "gray": "#6B7280",
+    "grey": "#6B7280",
+}
+
+
+def resolve(color: str) -> str:
+    """Resolve a friendly color name to a rich-compatible color string.
+
+    If the color isn't in the palette, it's passed through unchanged
+    (so hex codes and rich color names still work).
+    """
+    if not color:
+        return color
+    return PALETTE.get(color.lower(), color)

clidev/config.py

@@ -0,0 +1,36 @@
+"""Simple application configuration container."""
+
+
+class Config:
+    """Holds app-level configuration with attribute and dict-style access."""
+
+    def __init__(self, **kwargs):
+        self._data = {
+            "theme": "dark",
+            "storage_backend": "memory",
+            "storage_path": None,
+            "log_timestamps": True,
+            "confirm_exit": False,
+        }
+        self._data.update(kwargs)
+
+    def __getattr__(self, key):
+        try:
+            return self._data[key]
+        except KeyError as e:
+            raise AttributeError(key) from e
+
+    def __setattr__(self, key, value):
+        if key == "_data":
+            super().__setattr__(key, value)
+        else:
+            self._data[key] = value
+
+    def __getitem__(self, key):
+        return self._data[key]
+
+    def __setitem__(self, key, value):
+        self._data[key] = value
+
+    def as_dict(self):
+        return dict(self._data)

clidev/dashboard.py

@@ -0,0 +1,28 @@
+"""Dashboard: a simple grid layout of panels for at-a-glance views."""
+
+from rich.console import Console
+from rich.columns import Columns
+from rich.panel import Panel
+
+
+class Dashboard:
+    """app.dashboard("Overview").panel("Users", "1,204").panel("Errors", "3").show()"""
+
+    def __init__(self, title: str = "Dashboard", theme=None):
+        self.title = title
+        self.theme = theme
+        self._panels: list[tuple[str, str]] = []
+        self._console = Console()
+
+    def panel(self, title: str, content: str) -> "Dashboard":
+        self._panels.append((title, content))
+        return self
+
+    def show(self):
+        color = self.theme.get("primary") if self.theme else "white"
+        self._console.rule(f"[bold {color}]{self.title}[/bold {color}]")
+        rendered = [
+            Panel(str(content), title=title, border_style=color, expand=True)
+            for title, content in self._panels
+        ]
+        self._console.print(Columns(rendered, equal=True, expand=True))

clidev/dialogs.py

@@ -0,0 +1,24 @@
+"""Dialog helpers: confirm / prompt / alert boxes."""
+
+import questionary
+from rich.console import Console
+from rich.panel import Panel
+
+
+class Dialog:
+    def __init__(self, theme=None):
+        self.theme = theme
+        self._console = Console()
+
+    def confirm(self, message: str, default: bool = True) -> bool:
+        return questionary.confirm(message, default=default).ask()
+
+    def prompt(self, message: str, default: str = "") -> str:
+        return questionary.text(message, default=default).ask()
+
+    def alert(self, message: str, title: str = "Alert"):
+        color = self.theme.get("warning") if self.theme else "yellow"
+        self._console.print(Panel(message, title=title, border_style=color, expand=False))
+
+    def confirm_exit(self, message: str = "Are you sure you want to exit?") -> bool:
+        return self.confirm(message, default=False)

clidev/events.py

@@ -0,0 +1,39 @@
+"""Event dispatcher powering @app.on_start / on_exit / on_submit / on_error."""
+
+from collections import defaultdict
+
+
+class EventDispatcher:
+    """A minimal pub/sub dispatcher.
+
+    Named events: "start", "exit", "error" plus per-form "submit:<form_id>".
+    """
+
+    def __init__(self):
+        self._handlers = defaultdict(list)
+
+    def on(self, event: str, handler=None):
+        """Register a handler for `event`. Can be used as a decorator too."""
+        if handler is not None:
+            self._handlers[event].append(handler)
+            return handler
+
+        def decorator(fn):
+            self._handlers[event].append(fn)
+            return fn
+
+        return decorator
+
+    def off(self, event: str, handler):
+        if handler in self._handlers[event]:
+            self._handlers[event].remove(handler)
+
+    def emit(self, event: str, *args, **kwargs):
+        """Call every handler registered for `event`, returning their results."""
+        results = []
+        for handler in self._handlers.get(event, []):
+            results.append(handler(*args, **kwargs))
+        return results
+
+    def has(self, event: str) -> bool:
+        return bool(self._handlers.get(event))

clidev/exceptions.py

@@ -0,0 +1,35 @@
+"""Custom exceptions used across clidev."""
+
+
+class ClidevError(Exception):
+    """Base exception for all clidev errors."""
+
+
+class NavigationError(ClidevError):
+    """Raised when navigation (goto/back) fails, e.g. unknown page."""
+
+
+class ValidationError(ClidevError):
+    """Raised when a form field fails validation."""
+
+
+class StorageError(ClidevError):
+    """Raised when a storage backend operation fails."""
+
+
+class WorkflowError(ClidevError):
+    """Raised when a workflow step fails or is misconfigured."""
+
+
+class PluginError(ClidevError):
+    """Raised when a plugin fails to load or run."""
+
+
+class CommandError(ClidevError):
+    """Raised when a shell command fails (non-zero exit) and check=True."""
+
+    def __init__(self, message, returncode=None, stdout=None, stderr=None):
+        super().__init__(message)
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr