bead 0.1.0__py3-none-any.whl

bead/cli/deployment_ui.py

@@ -0,0 +1,332 @@
+"""UI customization commands for jsPsych deployment.
+
+This module provides commands for customizing the appearance of jsPsych
+experiments using Material Design themes and custom CSS.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+from bead.cli.utils import print_error, print_info, print_success
+from bead.deployment.jspsych.ui.styles import MaterialDesignStylesheet
+
+console = Console()
+
+
+@click.group(name="ui")
+def deployment_ui() -> None:
+    r"""UI customization commands for jsPsych experiments.
+
+    Commands for applying themes, generating CSS, and customizing the
+    appearance of jsPsych experiments.
+
+    \b
+    Examples:
+        $ bead deployment ui generate-css experiment/css/custom.css \\
+            --theme dark --primary-color "#1976D2"
+        $ bead deployment ui customize experiment/ \\
+            --theme dark --primary-color "#1976D2"
+    """
+
+
+@click.command()
+@click.argument("output_file", type=click.Path(path_type=Path))
+@click.option(
+    "--theme",
+    type=click.Choice(["light", "dark", "auto"], case_sensitive=False),
+    default="light",
+    help="Color theme (light, dark, or auto for system preference)",
+)
+@click.option(
+    "--primary-color",
+    default="#6200EE",
+    help="Primary color as hex code (default: Material Purple)",
+)
+@click.option(
+    "--secondary-color",
+    default="#03DAC6",
+    help="Secondary color as hex code (default: Material Teal)",
+)
+@click.pass_context
+def generate_css(
+    ctx: click.Context,
+    output_file: Path,
+    theme: Literal["light", "dark", "auto"],
+    primary_color: str,
+    secondary_color: str,
+) -> None:
+    r"""Generate Material Design CSS for jsPsych experiment.
+
+    Parameters
+    ----------
+    ctx : click.Context
+        Click context object.
+    output_file : Path
+        Output path for generated CSS file.
+    theme : Literal["light", "dark", "auto"]
+        Color theme.
+    primary_color : str
+        Primary color as hex code.
+    secondary_color : str
+        Secondary color as hex code.
+
+    Examples
+    --------
+    $ bead deployment ui generate-css experiment/css/custom.css
+
+    $ bead deployment ui generate-css experiment/css/dark.css \\
+        --theme dark --primary-color "#1976D2"
+
+    $ bead deployment ui generate-css experiment/css/material.css \\
+        --theme auto --primary-color "#6200EE" --secondary-color "#03DAC6"
+    """
+    try:
+        print_info(f"Generating Material Design CSS (theme: {theme})")
+
+        # Validate color codes
+        if not _is_valid_hex_color(primary_color):
+            print_error(f"Invalid primary color: {primary_color}")
+            print_info("Color must be a valid hex code (e.g., #1976D2)")
+            ctx.exit(1)
+
+        if not _is_valid_hex_color(secondary_color):
+            print_error(f"Invalid secondary color: {secondary_color}")
+            print_info("Color must be a valid hex code (e.g., #03DAC6)")
+            ctx.exit(1)
+
+        # Create output directory if needed
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Generate CSS
+        stylesheet = MaterialDesignStylesheet()
+        css = stylesheet.generate_css(
+            theme=theme,
+            primary_color=primary_color,
+            secondary_color=secondary_color,
+        )
+
+        # Write to file
+        output_file.write_text(css, encoding="utf-8")
+
+        print_success(f"Generated CSS: {output_file}")
+
+        # Show preview
+        preview_panel = Panel(
+            f"[cyan]Theme:[/cyan] {theme}\n"
+            f"[cyan]Primary:[/cyan] {primary_color}\n"
+            f"[cyan]Secondary:[/cyan] {secondary_color}\n"
+            f"[cyan]Lines:[/cyan] {len(css.splitlines())}",
+            title="[bold]CSS Preview[/bold]",
+            border_style="green",
+        )
+        console.print(preview_panel)
+
+    except Exception as e:
+        print_error(f"Failed to generate CSS: {e}")
+        ctx.exit(1)
+
+
+@click.command()
+@click.argument("experiment_dir", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--theme",
+    type=click.Choice(["light", "dark", "auto"], case_sensitive=False),
+    default="light",
+    help="Color theme (light, dark, or auto for system preference)",
+)
+@click.option(
+    "--primary-color",
+    default="#6200EE",
+    help="Primary color as hex code (default: Material Purple)",
+)
+@click.option(
+    "--secondary-color",
+    default="#03DAC6",
+    help="Secondary color as hex code (default: Material Teal)",
+)
+@click.option(
+    "--css-file",
+    type=click.Path(exists=True, path_type=Path),
+    help="Path to custom CSS file to include (optional)",
+)
+@click.option(
+    "--output-name",
+    default="experiment.css",
+    help="Output CSS filename (default: experiment.css)",
+)
+@click.pass_context
+def customize(
+    ctx: click.Context,
+    experiment_dir: Path,
+    theme: Literal["light", "dark", "auto"],
+    primary_color: str,
+    secondary_color: str,
+    css_file: Path | None,
+    output_name: str,
+) -> None:
+    r"""Apply UI customization to jsPsych experiment directory.
+
+    Generates Material Design CSS and optionally merges with custom CSS.
+    Writes the final CSS to the experiment's css/ directory.
+
+    Parameters
+    ----------
+    ctx : click.Context
+        Click context object.
+    experiment_dir : Path
+        Path to experiment directory.
+    theme : Literal["light", "dark", "auto"]
+        Color theme.
+    primary_color : str
+        Primary color as hex code.
+    secondary_color : str
+        Secondary color as hex code.
+    css_file : Path | None
+        Optional path to custom CSS file.
+    output_name : str
+        Output CSS filename.
+
+    Examples
+    --------
+    $ bead deployment ui customize experiment/
+
+    $ bead deployment ui customize experiment/ \\
+        --theme dark --primary-color "#1976D2"
+
+    $ bead deployment ui customize experiment/ \\
+        --theme auto --css-file custom.css --output-name styles.css
+    """
+    try:
+        print_info(f"Customizing UI for experiment: {experiment_dir}")
+
+        # Validate color codes
+        if not _is_valid_hex_color(primary_color):
+            print_error(f"Invalid primary color: {primary_color}")
+            print_info("Color must be a valid hex code (e.g., #1976D2)")
+            ctx.exit(1)
+
+        if not _is_valid_hex_color(secondary_color):
+            print_error(f"Invalid secondary color: {secondary_color}")
+            print_info("Color must be a valid hex code (e.g., #03DAC6)")
+            ctx.exit(1)
+
+        # Create css directory if needed
+        css_dir = experiment_dir / "css"
+        css_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate Material Design CSS
+        stylesheet = MaterialDesignStylesheet()
+        material_css = stylesheet.generate_css(
+            theme=theme,
+            primary_color=primary_color,
+            secondary_color=secondary_color,
+        )
+
+        # Merge with custom CSS if provided
+        final_css = material_css
+        if css_file:
+            print_info(f"Merging with custom CSS: {css_file}")
+            custom_css = css_file.read_text(encoding="utf-8")
+            final_css = material_css + "\n\n/* Custom CSS */\n\n" + custom_css
+
+        # Write to output file
+        output_path = css_dir / output_name
+        output_path.write_text(final_css, encoding="utf-8")
+
+        print_success(f"CSS written to: {output_path}")
+
+        # Show summary
+        summary_panel = Panel(
+            f"[cyan]Theme:[/cyan] {theme}\n"
+            f"[cyan]Primary:[/cyan] {primary_color}\n"
+            f"[cyan]Secondary:[/cyan] {secondary_color}\n"
+            f"[cyan]Custom CSS:[/cyan] {'Yes' if css_file else 'No'}\n"
+            f"[cyan]Output:[/cyan] {output_path.relative_to(experiment_dir)}\n"
+            f"[cyan]Lines:[/cyan] {len(final_css.splitlines())}",
+            title="[bold]UI Customization Summary[/bold]",
+            border_style="green",
+        )
+        console.print(summary_panel)
+
+        # Update index.html to reference the CSS file
+        index_html = experiment_dir / "index.html"
+        if index_html.exists():
+            _update_index_html_css_reference(index_html, output_name)
+            print_success("Updated index.html CSS reference")
+        else:
+            print_info("index.html not found - skipping CSS reference update")
+
+    except Exception as e:
+        print_error(f"Failed to customize UI: {e}")
+        ctx.exit(1)
+
+
+def _is_valid_hex_color(color: str) -> bool:
+    """Validate hex color code.
+
+    Parameters
+    ----------
+    color : str
+        Color string to validate.
+
+    Returns
+    -------
+    bool
+        True if valid hex color, False otherwise.
+
+    Examples
+    --------
+    >>> _is_valid_hex_color("#1976D2")
+    True
+    >>> _is_valid_hex_color("1976D2")
+    False
+    >>> _is_valid_hex_color("#GGG")
+    False
+    """
+    if not color.startswith("#"):
+        return False
+    hex_part = color[1:]
+    if len(hex_part) not in (3, 6):
+        return False
+    try:
+        int(hex_part, 16)
+        return True
+    except ValueError:
+        return False
+
+
+def _update_index_html_css_reference(index_html: Path, css_filename: str) -> None:
+    """Update index.html to reference the CSS file.
+
+    Parameters
+    ----------
+    index_html : Path
+        Path to index.html file.
+    css_filename : str
+        CSS filename to reference.
+    """
+    html_content = index_html.read_text(encoding="utf-8")
+
+    # Check if CSS link already exists
+    css_link = f'<link rel="stylesheet" href="css/{css_filename}">'
+    if css_link in html_content:
+        return  # Already has the correct reference
+
+    # Find </head> tag and insert CSS link before it
+    if "</head>" in html_content:
+        html_content = html_content.replace(
+            "</head>",
+            f"  {css_link}\n</head>",
+        )
+        index_html.write_text(html_content, encoding="utf-8")
+
+
+# Register commands
+deployment_ui.add_command(generate_css)
+deployment_ui.add_command(customize)

bead/cli/display.py

@@ -0,0 +1,378 @@
+"""Rich display utilities for CLI commands.
+
+This module provides centralized Rich display utilities for beautiful terminal output
+across all bead CLI commands. All CLI modules should import from this module for
+consistent formatting.
+
+Examples
+--------
+>>> from bead.cli.display import print_header, print_success, create_summary_table
+>>> print_header("Stage 1: Resources")
+>>> print_success("Loaded 1,234 items")
+>>> table = create_summary_table({"Items": "1,234", "Time": "2.3s"})
+>>> console.print(table)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.spinner import Spinner
+from rich.table import Table
+from rich.traceback import install
+
+# Install rich traceback globally for CLI
+install(show_locals=True, width=100, word_wrap=True)
+
+# Shared console instance
+console = Console()
+
+
+def print_header(text: str) -> None:
+    """Print command header with horizontal rule.
+
+    Parameters
+    ----------
+    text : str
+        Header text to display.
+
+    Examples
+    --------
+    >>> print_header("Stage 1: Resources")
+    ═══════════════════════════════════════
+                 Stage 1: Resources
+    ═══════════════════════════════════════
+    """
+    console.rule(f"[bold]{text}[/bold]")
+
+
+def print_success(text: str) -> None:
+    """Print success message with green checkmark.
+
+    Parameters
+    ----------
+    text : str
+        Success message to display.
+
+    Examples
+    --------
+    >>> print_success("Loaded 1,234 items")
+    ✓ Loaded 1,234 items
+    """
+    console.print(f"[green]✓[/green] {text}")
+
+
+def print_error(text: str) -> None:
+    """Print error message with red X.
+
+    Parameters
+    ----------
+    text : str
+        Error message to display.
+
+    Examples
+    --------
+    >>> print_error("Failed to load config")
+    ✗ Failed to load config
+    """
+    console.print(f"[red]✗[/red] {text}")
+
+
+def print_warning(text: str) -> None:
+    """Print warning message with yellow warning sign.
+
+    Parameters
+    ----------
+    text : str
+        Warning message to display.
+
+    Examples
+    --------
+    >>> print_warning("Using default strategy")
+    ⚠ Warning: Using default strategy
+    """
+    console.print(f"[yellow]⚠[/yellow] {text}")
+
+
+def print_info(text: str) -> None:
+    """Print info message with blue info icon.
+
+    Parameters
+    ----------
+    text : str
+        Info message to display.
+
+    Examples
+    --------
+    >>> print_info("Next step: Run partition command")
+    ℹ Next step: Run partition command
+    """
+    console.print(f"[blue]ℹ[/blue] {text}")
+
+
+def create_summary_table(
+    data: dict[str, str],
+    title: str | None = None,
+    show_header: bool = False,
+) -> Table:
+    """Create formatted summary table.
+
+    Parameters
+    ----------
+    data : dict[str, str]
+        Dictionary mapping metric names to values.
+    title : str | None, optional
+        Table title. Default is None.
+    show_header : bool, optional
+        Whether to show table header. Default is False.
+
+    Returns
+    -------
+    Table
+        Formatted Rich Table object.
+
+    Examples
+    --------
+    >>> table = create_summary_table({
+    ...     "Items processed": "1,234",
+    ...     "Success rate": "98.5%",
+    ...     "Time": "45.2s"
+    ... }, title="Summary")
+    >>> console.print(table)
+    """
+    table = Table(show_header=show_header, title=title)
+    table.add_column("Metric", style="cyan", no_wrap=True)
+    table.add_column("Value", justify="right", style="green")
+
+    for key, value in data.items():
+        table.add_row(key, value)
+
+    return table
+
+
+def create_progress() -> Progress:
+    """Create standard progress bar for CLI operations.
+
+    Returns
+    -------
+    Progress
+        Configured Rich Progress instance.
+
+    Examples
+    --------
+    >>> with create_progress() as progress:
+    ...     task = progress.add_task("Loading items...", total=1000)
+    ...     for i in range(1000):
+    ...         progress.advance(task)
+    """
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        TimeElapsedColumn(),
+        console=console,
+    )
+
+
+def create_spinner_progress() -> Progress:
+    """Create spinner-only progress (for indeterminate operations).
+
+    Returns
+    -------
+    Progress
+        Configured Rich Progress instance with spinner only.
+
+    Examples
+    --------
+    >>> with create_spinner_progress() as progress:
+    ...     progress.add_task("Loading model weights...", total=None)
+    """
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+    )
+
+
+def create_live_status(message: str) -> Live:
+    """Create live status display with spinner.
+
+    Parameters
+    ----------
+    message : str
+        Status message to display.
+
+    Returns
+    -------
+    Live
+        Rich Live instance for status updates.
+
+    Examples
+    --------
+    >>> with create_live_status("Training model..."):
+    ...     model.train()
+    """
+    return Live(Spinner("dots", text=message), console=console)
+
+
+def create_panel(
+    content: str,
+    title: str | None = None,
+    style: str = "cyan",
+) -> Panel:
+    """Create formatted panel for important messages.
+
+    Parameters
+    ----------
+    content : str
+        Panel content.
+    title : str | None, optional
+        Panel title. Default is None.
+    style : str, optional
+        Panel border style color. Default is "cyan".
+
+    Returns
+    -------
+    Panel
+        Rich Panel object.
+
+    Examples
+    --------
+    >>> panel = create_panel(
+    ...     "Generating lexicons from VerbNet...",
+    ...     title="In Progress"
+    ... )
+    >>> console.print(panel)
+    """
+    return Panel(content, title=f"[{style}]{title}[/{style}]" if title else None)
+
+
+def display_file_stats(file_path: Path, count: int, item_type: str = "items") -> None:
+    """Display statistics for a saved file.
+
+    Parameters
+    ----------
+    file_path : Path
+        Path to saved file.
+    count : int
+        Number of items in file.
+    item_type : str, optional
+        Type of items (for display). Default is "items".
+
+    Examples
+    --------
+    >>> display_file_stats(Path("items.jsonl"), 1234, "items")
+    ✓ Saved 1,234 items to items.jsonl
+    """
+    print_success(f"Saved {count:,} {item_type} to {file_path}")
+
+
+def display_validation_errors(
+    errors: list[str],
+    max_display: int = 10,
+) -> None:
+    """Display validation errors with truncation.
+
+    Parameters
+    ----------
+    errors : list[str]
+        List of error messages.
+    max_display : int, optional
+        Maximum number of errors to display. Default is 10.
+
+    Examples
+    --------
+    >>> errors = ["Line 1: Invalid JSON", "Line 5: Missing field"]
+    >>> display_validation_errors(errors)
+    """
+    print_error(f"Validation failed with {len(errors)} error(s):")
+    for error in errors[:max_display]:
+        console.print(f"  [red]✗[/red] {error}")
+    if len(errors) > max_display:
+        console.print(f"  ... and {len(errors) - max_display} more error(s)")
+
+
+def confirm(
+    message: str,
+    default: bool = False,
+) -> bool:
+    """Prompt user for yes/no confirmation.
+
+    Parameters
+    ----------
+    message : str
+        Confirmation message.
+    default : bool, optional
+        Default value if user presses Enter. Default is False.
+
+    Returns
+    -------
+    bool
+        True if user confirmed, False otherwise.
+
+    Examples
+    --------
+    >>> if confirm("Delete all files?", default=False):
+    ...     delete_files()
+    """
+    suffix = " [Y/n]: " if default else " [y/N]: "
+    response = console.input(f"[yellow]?[/yellow] {message}{suffix}")
+
+    if not response:
+        return default
+
+    return response.lower() in ("y", "yes")
+
+
+def display_dry_run_summary(data: dict[str, Any]) -> None:
+    """Display dry run summary.
+
+    Parameters
+    ----------
+    data : dict[str, Any]
+        Dictionary of dry run information.
+
+    Examples
+    --------
+    >>> display_dry_run_summary({
+    ...     "Templates": 26,
+    ...     "Filled Templates": 1234,
+    ...     "Output": "items.jsonl"
+    ... })
+    """
+    print_info("[DRY RUN] Preview of operation:")
+    for key, value in data.items():
+        console.print(f"  {key}: {value}")
+    print_warning("[DRY RUN] No changes will be made")
+
+
+# Export commonly used items
+__all__ = [
+    "console",
+    "print_header",
+    "print_success",
+    "print_error",
+    "print_warning",
+    "print_info",
+    "create_summary_table",
+    "create_progress",
+    "create_spinner_progress",
+    "create_live_status",
+    "create_panel",
+    "display_file_stats",
+    "display_validation_errors",
+    "confirm",
+    "display_dry_run_summary",
+]