clidevkit 0.1.0__py3-none-any.whl

clidev/forms.py

@@ -0,0 +1,97 @@
+"""Chainable form builder: app.form("User").text("Name")...run()"""
+
+import uuid
+
+from rich.console import Console
+from rich.panel import Panel
+
+from .inputs import Field
+
+
+class Form:
+    """A chainable form. Each `.text()`, `.email()`, etc. call adds a field.
+
+    form = app.form("User")
+    form.text("Name")
+    form.email("Email")
+    data = form.run()
+    """
+
+    def __init__(self, title: str = "Form", app=None):
+        self.title = title
+        self.app = app
+        self.id = f"form_{uuid.uuid4().hex[:8]}"
+        self.fields: list[Field] = []
+        self._console = Console()
+
+    # --- field builders ---------------------------------------------------
+    def _add(self, name, kind, **kwargs) -> "Form":
+        self.fields.append(Field(name=name, kind=kind, **kwargs))
+        return self
+
+    def text(self, name, **kwargs) -> "Form":
+        return self._add(name, "text", **kwargs)
+
+    def email(self, name, **kwargs) -> "Form":
+        return self._add(name, "email", **kwargs)
+
+    def password(self, name, **kwargs) -> "Form":
+        return self._add(name, "password", **kwargs)
+
+    def number(self, name, **kwargs) -> "Form":
+        return self._add(name, "number", **kwargs)
+
+    def url(self, name, **kwargs) -> "Form":
+        return self._add(name, "url", **kwargs)
+
+    def file(self, name, **kwargs) -> "Form":
+        return self._add(name, "file", **kwargs)
+
+    def folder(self, name, **kwargs) -> "Form":
+        return self._add(name, "folder", **kwargs)
+
+    def date(self, name, **kwargs) -> "Form":
+        return self._add(name, "date", **kwargs)
+
+    def time(self, name, **kwargs) -> "Form":
+        return self._add(name, "time", **kwargs)
+
+    def checkbox(self, name, **kwargs) -> "Form":
+        return self._add(name, "checkbox", **kwargs)
+
+    def toggle(self, name, **kwargs) -> "Form":
+        return self._add(name, "toggle", **kwargs)
+
+    def radio(self, name, choices, **kwargs) -> "Form":
+        return self._add(name, "radio", choices=choices, **kwargs)
+
+    def select(self, name, choices, **kwargs) -> "Form":
+        return self._add(name, "select", choices=choices, **kwargs)
+
+    def dropdown(self, name, choices, **kwargs) -> "Form":
+        return self._add(name, "dropdown", choices=choices, **kwargs)
+
+    def multiselect(self, name, choices, **kwargs) -> "Form":
+        return self._add(name, "multiselect", choices=choices, **kwargs)
+
+    def searchable(self, name, choices, **kwargs) -> "Form":
+        return self._add(name, "searchable", choices=choices, **kwargs)
+
+    # --- execution ----------------------------------------------------------
+    def run(self) -> dict:
+        """Render the form interactively, one field at a time, and return a dict."""
+        self._console.print(Panel(f"[bold]{self.title}[/bold]", expand=False))
+        data = {}
+        try:
+            for f in self.fields:
+                data[f.name] = f.prompt()
+        except (KeyboardInterrupt, EOFError):
+            return {}
+
+        if self.app is not None:
+            self.app.events.emit(f"submit:{self.id}", data)
+            self.app.state.update({f"{self.title}.{k}": v for k, v in data.items()})
+        return data
+
+    def __repr__(self):
+        return f"Form(title={self.title!r}, fields={[f.name for f in self.fields]})"

clidev/generators/__init__.py

@@ -0,0 +1,13 @@
+"""Code generators used by the `clidev` CLI command (project/menu/form/workflow)."""
+
+from .project import create_project
+from .menu import generate_menu_snippet
+from .form import generate_form_snippet
+from .workflow import generate_workflow_snippet
+
+__all__ = [
+    "create_project",
+    "generate_menu_snippet",
+    "generate_form_snippet",
+    "generate_workflow_snippet",
+]

clidev/generators/form.py

@@ -0,0 +1,11 @@
+"""Helper to scaffold a new form snippet."""
+
+FORM_SNIPPET = '''
+{var_name} = app.form("{title}")
+{var_name}.text("Name")
+'''
+
+
+def generate_form_snippet(title: str) -> str:
+    var_name = title.lower().replace(" ", "_")
+    return FORM_SNIPPET.format(var_name=var_name, title=title)

clidev/generators/menu.py

@@ -0,0 +1,11 @@
+"""Helper to scaffold a new menu snippet into menus.py-like files."""
+
+MENU_SNIPPET = '''
+{var_name} = app.menu("{title}")
+{var_name}.option("Exit", app.exit)
+'''
+
+
+def generate_menu_snippet(title: str) -> str:
+    var_name = title.lower().replace(" ", "_")
+    return MENU_SNIPPET.format(var_name=var_name, title=title)

clidev/generators/project.py

@@ -0,0 +1,150 @@
+"""Scaffolds a new clidev project: `clidev new myproject`."""
+
+from pathlib import Path
+
+APP_PY = '''"""Main application entry point for {project_name}."""
+
+from clidev import App
+
+from routes import register_routes
+from menus import build_menus
+
+app = App("{title}")
+
+register_routes(app)
+build_menus(app)
+
+if __name__ == "__main__":
+    app.run()
+'''
+
+ROUTES_PY = '''"""Page routes for {project_name}."""
+
+
+def register_routes(app):
+    @app.page("home")
+    def home():
+        app.info("Welcome to {title}!")
+'''
+
+MENUS_PY = '''"""Menu definitions for {project_name}."""
+
+
+def build_menus(app):
+    main = app.menu("Main Menu")
+    main.option("Say Hello", lambda: app.success("Hello from {title}!"))
+    main.option("Exit", app.exit)
+    return main
+'''
+
+FORMS_PY = '''"""Form definitions for {project_name}."""
+
+
+def build_forms(app):
+    form = app.form("Example")
+    form.text("Name")
+    form.email("Email")
+    return form
+'''
+
+WORKFLOWS_PY = '''"""Workflow definitions for {project_name}."""
+
+
+def build_workflows(app):
+    workflow = app.workflow("example")
+
+    def step_one(context):
+        app.info("Step one running...")
+        return {{"step_one_done": True}}
+
+    workflow.step(step_one)
+    return workflow
+'''
+
+COMMANDS_PY = '''"""Shell command helpers for {project_name}."""
+
+
+def setup_environment(app):
+    app.cmd("python -m venv .venv")
+    app.success("Virtual environment created.")
+'''
+
+STORAGE_PY = '''"""Storage configuration for {project_name}."""
+
+
+def configure_storage(app):
+    # Swap "memory" for "json", "sqlite", "yaml", or "toml" as needed.
+    return app.storage
+'''
+
+SETTINGS_PY = '''"""Settings for {project_name}."""
+
+APP_TITLE = "{title}"
+THEME = "dark"
+STORAGE_BACKEND = "memory"
+'''
+
+GITIGNORE = """__pycache__/
+*.pyc
+.venv/
+.clidev_storage.json
+.clidev_storage.db
+.clidev_storage.yaml
+.clidev_storage.toml
+"""
+
+README = '''# {title}
+
+A CLI application built with [clidev](https://github.com/clidev/clidev).
+
+## Run
+
+```bash
+python app.py
+```
+
+## Structure
+
+- `app.py` - main entry point
+- `routes.py` - page routes
+- `menus.py` - menu definitions
+- `forms.py` - form definitions
+- `workflows.py` - workflow definitions
+- `commands.py` - shell command helpers
+- `storage.py` - storage configuration
+- `settings.py` - app settings
+- `assets/` - static assets
+'''
+
+
+def create_project(name: str, target_dir: str | None = None) -> Path:
+    """Create a new clidev project scaffold named `name`."""
+    base = Path(target_dir) if target_dir else Path.cwd()
+    project_dir = base / name
+    if project_dir.exists():
+        raise FileExistsError(f"Directory '{project_dir}' already exists.")
+
+    project_dir.mkdir(parents=True)
+    (project_dir / "assets").mkdir()
+
+    title = name.replace("_", " ").replace("-", " ").title()
+    ctx = {"project_name": name, "title": title}
+
+    files = {
+        "app.py": APP_PY,
+        "routes.py": ROUTES_PY,
+        "menus.py": MENUS_PY,
+        "forms.py": FORMS_PY,
+        "workflows.py": WORKFLOWS_PY,
+        "commands.py": COMMANDS_PY,
+        "storage.py": STORAGE_PY,
+        "settings.py": SETTINGS_PY,
+        ".gitignore": GITIGNORE,
+        "README.md": README,
+    }
+
+    for filename, template in files.items():
+        content = template.format(**ctx) if "{" in template else template
+        (project_dir / filename).write_text(content)
+
+    return project_dir

clidev/generators/workflow.py

@@ -0,0 +1,17 @@
+"""Helper to scaffold a new workflow snippet."""
+
+WORKFLOW_SNIPPET = '''
+{var_name} = app.workflow("{name}")
+
+
+def {var_name}_step_one(context):
+    app.info("Running {name} step one...")
+
+
+{var_name}.step({var_name}_step_one)
+'''
+
+
+def generate_workflow_snippet(name: str) -> str:
+    var_name = name.lower().replace(" ", "_")
+    return WORKFLOW_SNIPPET.format(var_name=var_name, name=name)

clidev/icons.py

@@ -0,0 +1,16 @@
+"""Small set of unicode icons used throughout clidev's UI output."""
+
+ICONS = {
+    "success": "\u2713",   # check mark
+    "error": "\u2717",     # cross mark
+    "warning": "\u26A0",   # warning sign
+    "info": "\u2139",      # info
+    "arrow": "\u2192",     # right arrow
+    "bullet": "\u2022",
+    "star": "\u2605",
+    "spinner": "\u25CF",
+}
+
+
+def icon(name: str, default: str = "") -> str:
+    return ICONS.get(name, default)

clidev/inputs.py

@@ -0,0 +1,90 @@
+"""Individual input widgets used by Form. Rendered via questionary."""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+import questionary
+
+from . import validators as v
+from .exceptions import ValidationError
+
+
+@dataclass
+class Field:
+    """Represents a single form field/input widget."""
+
+    name: str
+    kind: str
+    label: str | None = None
+    choices: list | None = None
+    default: Any = None
+    required: bool = True
+    extra_validators: list[Callable] = field(default_factory=list)
+
+    def _label(self):
+        return self.label or self.name
+
+    def _validate(self, value):
+        validators = []
+        if self.required:
+            validators.append(v.required)
+        if self.kind == "email":
+            validators.append(v.is_email)
+        elif self.kind == "url":
+            validators.append(v.is_url)
+        elif self.kind == "number":
+            validators.append(v.is_number)
+        elif self.kind == "date":
+            validators.append(v.is_date())
+        validators.extend(self.extra_validators)
+        return v.run_validators(value, validators)
+
+    def prompt(self):
+        """Render this field interactively and return the validated value."""
+        label = self._label()
+
+        def _q_validate(raw):
+            try:
+                self._validate(raw)
+                return True
+            except ValidationError as e:
+                return str(e)
+
+        if self.kind == "text":
+            answer = questionary.text(label, default=self.default or "", validate=_q_validate).ask()
+        elif self.kind == "email":
+            answer = questionary.text(label, default=self.default or "", validate=_q_validate).ask()
+        elif self.kind == "url":
+            answer = questionary.text(label, default=self.default or "", validate=_q_validate).ask()
+        elif self.kind == "password":
+            answer = questionary.password(label).ask()
+        elif self.kind == "number":
+            answer = questionary.text(label, default=str(self.default or ""), validate=_q_validate).ask()
+            answer = v.is_number(answer) if answer not in (None, "") else None
+        elif self.kind == "date":
+            answer = questionary.text(label + " (YYYY-MM-DD)", validate=_q_validate).ask()
+        elif self.kind == "time":
+            answer = questionary.text(label + " (HH:MM)").ask()
+        elif self.kind == "file":
+            answer = questionary.path(label).ask()
+        elif self.kind == "folder":
+            answer = questionary.path(label, only_directories=True).ask()
+        elif self.kind == "checkbox":
+            answer = questionary.confirm(label, default=bool(self.default)).ask()
+        elif self.kind == "toggle":
+            answer = questionary.confirm(label, default=bool(self.default)).ask()
+        elif self.kind == "select" or self.kind == "dropdown":
+            answer = questionary.select(label, choices=self.choices or []).ask()
+        elif self.kind == "radio":
+            answer = questionary.select(label, choices=self.choices or []).ask()
+        elif self.kind == "multiselect":
+            answer = questionary.checkbox(label, choices=self.choices or []).ask()
+        elif self.kind == "searchable":
+            answer = questionary.autocomplete(label, choices=self.choices or []).ask()
+        else:
+            answer = questionary.text(label).ask()
+
+        if self.kind not in ("number", "checkbox", "toggle", "multiselect"):
+            if answer is not None:
+                self._validate(answer)
+        return answer

clidev/logger.py

@@ -0,0 +1,50 @@
+"""Themed logger used as app.logger."""
+
+import datetime as _dt
+
+from rich.console import Console
+
+
+class Logger:
+    """Simple themed logger.
+
+    app.logger.info("Started")
+    app.logger.warning("Careful")
+    app.logger.error("Failed")
+    """
+
+    def __init__(self, theme=None, console: Console | None = None, timestamps: bool = True):
+        self.theme = theme
+        self.console = console or Console()
+        self.timestamps = timestamps
+        self._history = []
+
+    def _ts(self):
+        return _dt.datetime.now().strftime("%H:%M:%S")
+
+    def _emit(self, level, style_key, symbol, message):
+        color = self.theme.get(style_key) if self.theme else None
+        prefix = f"[dim]{self._ts()}[/dim] " if self.timestamps else ""
+        style = f"bold {color}" if color else "bold"
+        line = f"{prefix}[{style}]{symbol} {level.upper()}[/{style}] {message}"
+        self._history.append((level, message))
+        self.console.print(line)
+
+    def info(self, message):
+        self._emit("info", "info", "\u2139", message)
+
+    def success(self, message):
+        self._emit("success", "success", "\u2713", message)
+
+    def warning(self, message):
+        self._emit("warning", "warning", "\u26A0", message)
+
+    def error(self, message):
+        self._emit("error", "error", "\u2717", message)
+
+    def debug(self, message):
+        self._emit("debug", "muted", "\u2022", message)
+
+    @property
+    def history(self):
+        return list(self._history)

clidev/menus.py

@@ -0,0 +1,69 @@
+"""Menu + nested menu engine."""
+
+import questionary
+from rich.console import Console
+from rich.panel import Panel
+
+
+class MenuOption:
+    def __init__(self, label: str, target):
+        self.label = label
+        self.target = target  # callable, page name string, or Menu instance
+
+
+class Menu:
+    """A single-level (optionally nested) menu.
+
+    menu = app.menu("Main Menu")
+    menu.option("Create Project", create_project)
+    menu.option("Deploy", deploy)
+    menu.option("Exit", app.exit)
+
+    Nested:
+        main.link("Settings", settings_menu)
+    """
+
+    def __init__(self, title: str = "Menu", app=None):
+        self.title = title
+        self.app = app
+        self.options: list[MenuOption] = []
+        self._console = Console()
+
+    def option(self, label: str, target) -> "Menu":
+        """Add a menu entry. `target` can be a callable, a page-name string,
+        or another Menu (equivalent to .link)."""
+        self.options.append(MenuOption(label, target))
+        return self
+
+    def link(self, label: str, submenu: "Menu") -> "Menu":
+        """Add a nested submenu entry."""
+        self.options.append(MenuOption(label, submenu))
+        return self
+
+    def _resolve(self, target):
+        if isinstance(target, Menu):
+            target.run()
+        elif isinstance(target, str):
+            if self.app is not None:
+                self.app.goto(target)
+        elif callable(target):
+            target()
+
+    def run(self):
+        """Render the menu in a loop until the user exits or a handler navigates away."""
+        while True:
+            self._console.print(Panel(f"[bold]{self.title}[/bold]", expand=False))
+            choice = questionary.select(
+                "Select an option:",
+                choices=[opt.label for opt in self.options],
+            ).ask()
+            if choice is None:
+                return
+            selected = next(o for o in self.options if o.label == choice)
+            self._resolve(selected.target)
+            # If app signalled exit, stop looping.
+            if self.app is not None and getattr(self.app, "_should_exit", False):
+                return
+
+    def __repr__(self):
+        return f"Menu(title={self.title!r}, options={[o.label for o in self.options]})"

clidev/notifications.py

@@ -0,0 +1,26 @@
+"""Inline notification / toast-style messages (success, error, info, warning)."""
+
+from rich.console import Console
+
+
+class Notifications:
+    def __init__(self, theme=None, console: Console | None = None):
+        self.theme = theme
+        self.console = console or Console()
+
+    def _print(self, symbol: str, style_key: str, message: str):
+        color = self.theme.get(style_key) if self.theme else None
+        style = f"bold {color}" if color else "bold"
+        self.console.print(f"[{style}]{symbol}[/{style}] {message}")
+
+    def success(self, message: str):
+        self._print("\u2713", "success", message)
+
+    def error(self, message: str):
+        self._print("\u2717", "error", message)
+
+    def warning(self, message: str):
+        self._print("\u26A0", "warning", message)
+
+    def info(self, message: str):
+        self._print("\u2139", "info", message)

clidev/pages.py

@@ -0,0 +1,42 @@
+"""Page registration. Pages are named callables the router can navigate to."""
+
+
+class Page:
+    def __init__(self, name: str, handler=None):
+        self.name = name
+        self.handler = handler
+
+    def render(self, *args, **kwargs):
+        if self.handler is not None:
+            return self.handler(*args, **kwargs)
+
+
+class PageRegistry:
+    """Holds all registered pages by name."""
+
+    def __init__(self):
+        self._pages: dict[str, Page] = {}
+
+    def register(self, name: str, handler=None):
+        """Register a page. Can be used directly or as a decorator:
+
+        app.page("home")  -> returns a decorator when handler is None
+        """
+        if handler is not None:
+            self._pages[name] = Page(name, handler)
+            return self._pages[name]
+
+        def decorator(fn):
+            self._pages[name] = Page(name, fn)
+            return fn
+
+        return decorator
+
+    def get(self, name: str) -> Page | None:
+        return self._pages.get(name)
+
+    def exists(self, name: str) -> bool:
+        return name in self._pages
+
+    def names(self):
+        return list(self._pages.keys())

clidev/plugins.py

@@ -0,0 +1,51 @@
+"""Plugin system: app.use(SomePlugin())."""
+
+from .exceptions import PluginError
+
+
+class Plugin:
+    """Base class for clidev plugins.
+
+    Subclass and override the lifecycle hooks you need:
+
+    class GitPlugin(Plugin):
+        name = "git"
+
+        def on_install(self, app):
+            app.state["git_enabled"] = True
+
+        def on_start(self, app):
+            ...
+    """
+
+    name: str = "plugin"
+
+    def on_install(self, app):
+        """Called once, immediately when app.use(plugin) runs."""
+
+    def on_start(self, app):
+        """Called when the app starts (app.run())."""
+
+    def on_exit(self, app):
+        """Called when the app exits."""
+
+
+class PluginManager:
+    def __init__(self, app=None):
+        self.app = app
+        self.plugins: list[Plugin] = []
+
+    def use(self, plugin: Plugin):
+        if not isinstance(plugin, Plugin):
+            raise PluginError(f"{plugin!r} must be a Plugin instance.")
+        self.plugins.append(plugin)
+        plugin.on_install(self.app)
+        return plugin
+
+    def start_all(self):
+        for p in self.plugins:
+            p.on_start(self.app)
+
+    def exit_all(self):
+        for p in self.plugins:
+            p.on_exit(self.app)