code-muse 0.0.1__py3-none-any.whl

code_muse/command_line/onboarding_slides.py

@@ -0,0 +1,162 @@
+"""Slide content for the onboarding wizard.
+
+Lean, mean, ADHD-friendly slides. 5 slides max!
+"""
+
+
+# ============================================================================
+# Slide Data Constants
+# ============================================================================
+
+# Model subscription options
+MODEL_OPTIONS: list[tuple[str, str, str]] = [
+    ("chatgpt", "ChatGPT Plus/Pro/Max", "OAuth login - no API key needed"),
+    ("claude", "Claude Code Pro/Max", "OAuth login - no API key needed"),
+    ("api_keys", "API Keys", "OpenAI, Anthropic, Google, etc."),
+    ("openrouter", "OpenRouter", "Single key for 100+ models"),
+    ("skip", "Skip for now", "Configure later with /set or /add_model"),
+]
+
+
+# ============================================================================
+# Navigation Footer (shown on ALL slides)
+# ============================================================================
+
+
+def get_nav_footer() -> str:
+    """Navigation hints shown at bottom of every slide."""
+    return (
+        "\n[dim]─────────────────────────────────────[/dim]\n"
+        "[green]→/l[/green] Next  "
+        "[green]←/h[/green] Back  "
+        "[green]↑↓/jk[/green] Options  "
+        "[green]Enter[/green] Select  "
+        "[yellow]ESC[/yellow] Skip"
+    )
+
+
+# ============================================================================
+# Gradient Banner
+# ============================================================================
+
+
+def get_gradient_banner() -> str:
+    """Generate the gradient CODE PUPPY banner."""
+    try:
+        import pyfiglet
+
+        lines = pyfiglet.figlet_format("CODE PUPPY", font="ansi_shadow").split("\n")
+        colors = ["bright_blue", "bright_cyan", "bright_green"]
+        result = []
+        for i, line in enumerate(lines):
+            if line.strip():
+                color = colors[min(i // 2, len(colors) - 1)]
+                result.append(f"[{color}]{line}[/{color}]")
+        return "\n".join(result)
+    except ImportError:
+        return "[bold bright_cyan]═══ CODE PUPPY ═══[/bold bright_cyan]"
+
+
+# ============================================================================
+# Slide Content (5 slides total)
+# ============================================================================
+
+
+def slide_welcome() -> str:
+    """Slide 1: Welcome - quick intro."""
+    content = get_gradient_banner()
+    content += "\n\n"
+    content += "[bold white]Welcome.[/bold white]\n\n"
+    content += "[cyan]Quick setup:[/cyan]\n"
+    content += "  1. Pick your model provider\n"
+    content += "  2. Optional: External tools\n"
+    content += "  3. Learn when to use which agent\n"
+    content += "  4. Start coding!\n\n"
+    content += "[dim]Takes ~1 minute. Let's go![/dim]"
+    content += get_nav_footer()
+    return content
+
+
+def slide_models(selected_option: int, options: list[tuple[str, str]]) -> str:
+    """Slide 2: Model selection."""
+    content = "[bold cyan]📦 Pick Your Models[/bold cyan]\n\n"
+    content += "[white]How do you want to access LLMs?[/white]\n\n"
+
+    for i, (_, label) in enumerate(options):
+        if i == selected_option:
+            content += f"[bold green]▶ {label}[/bold green]\n"
+        else:
+            content += f"[dim]  {label}[/dim]\n"
+
+    content += "\n"
+
+    # Context based on selection
+    opt = options[selected_option][0] if options else None
+    if opt == "chatgpt":
+        content += "[yellow]💡 ChatGPT OAuth[/yellow]\n"
+        content += "  Uses your existing subscription\n"
+        content += "  GPT-5.2, GPT-5.2-codex\n"
+    elif opt == "claude":
+        content += "[yellow]💡 Claude OAuth[/yellow]\n"
+        content += "  Uses your existing subscription\n"
+        content += "  Opus/Sonnet/Haiku 4.5\n"
+    elif opt == "api_keys":
+        content += "[yellow]💡 API Keys[/yellow]\n"
+        content += "  [cyan]/set OPENAI_API_KEY=sk-...[/cyan]\n"
+        content += "  [cyan]/add_model[/cyan] to browse 1500+ models\n"
+    elif opt == "openrouter":
+        content += "[yellow]💡 OpenRouter[/yellow]\n"
+        content += "  One API key, all providers\n"
+        content += "  [cyan]/set OPENROUTER_API_KEY=...[/cyan]\n"
+    else:
+        content += "[dim]No worries! Use /set or /add_model later[/dim]\n"
+
+    content += get_nav_footer()
+    return content
+
+
+def slide_use_cases() -> str:
+    """Slide 4: When to use which agent - THE IMPORTANT ONE."""
+    content = "[bold cyan]🎯 When to Use What[/bold cyan]\n\n"
+
+    content += "[bold yellow]Muse (default)[/bold yellow]\n"
+    content += "  [green]USE FOR:[/green] Direct coding tasks\n"
+    content += "  • Fix this bug\n"
+    content += "  • Add a feature to this file\n"
+    content += "  • Refactor this function\n"
+    content += "  • Write tests for X\n\n"
+
+    content += "[bold yellow]📋 Planning Agent[/bold yellow]\n"
+    content += "  [green]USE FOR:[/green] Complex multi-step projects\n"
+    content += "  • Build me a REST API with auth\n"
+    content += "  • Create a CLI tool from scratch\n"
+    content += "  • Refactor entire codebase\n"
+    content += "  • Multi-file architectural changes\n\n"
+
+    content += "[cyan]Switch: /agent planning-agent[/cyan]\n"
+    content += "[dim]Planning breaks big tasks into steps,[/dim]\n"
+    content += "[dim]then delegates to specialists.[/dim]"
+    content += get_nav_footer()
+    return content
+
+
+def slide_done(trigger_oauth: str | None) -> str:
+    """Slide 5: You're ready!"""
+    content = "[bold green]🎉 Ready to Roll![/bold green]\n\n"
+    content += "[bold cyan]Essential commands:[/bold cyan]\n"
+    content += "  [cyan]/model[/cyan]   Switch models\n"
+    content += "  [cyan]/agent[/cyan]   Switch agents\n"
+    content += "  [cyan]/help[/cyan]    All commands\n\n"
+
+    content += "[bold yellow]Pro tips:[/bold yellow]\n"
+    content += "  • Be specific in prompts\n"
+    content += "  • Use Planning Agent for big tasks\n"
+    content += "  • @ for file path completion\n\n"
+
+    if trigger_oauth:
+        content += f"[bold cyan]→ {trigger_oauth.title()} OAuth next![/bold cyan]\n\n"
+
+    content += "[dim]Re-run anytime: [/dim][cyan]/tutorial[/cyan]\n"
+    content += "\n[bold yellow]Press Enter to start.[/bold yellow]"
+    content += get_nav_footer()
+    return content

code_muse/command_line/onboarding_wizard.py

@@ -0,0 +1,337 @@
+"""Interactive TUI onboarding wizard for first-time Muse users.
+
+Quick 5-slide tutorial. ADHD-friendly!
+
+Usage:
+    from code_muse.command_line.onboarding_wizard import (
+        run_onboarding_wizard,
+        reset_onboarding,
+    )
+
+    result = await run_onboarding_wizard()
+    # result: "chatgpt", "claude", "completed", "skipped", or None
+"""
+
+import asyncio
+import io
+import os
+import sys
+
+from prompt_toolkit import Application
+from prompt_toolkit.formatted_text import ANSI
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.layout import Layout, Window
+from prompt_toolkit.layout.controls import FormattedTextControl
+from prompt_toolkit.widgets import Frame
+from rich.console import Console
+
+from code_muse.config import CONFIG_DIR
+
+from .onboarding_slides import (
+    MODEL_OPTIONS,
+    slide_done,
+    slide_models,
+    slide_use_cases,
+    slide_welcome,
+)
+
+# ============================================================================
+# State Tracking
+# ============================================================================
+
+ONBOARDING_COMPLETE_FILE = CONFIG_DIR / "onboarding_complete"
+
+
+def has_completed_onboarding() -> bool:
+    """Check if the user has already completed onboarding."""
+    return ONBOARDING_COMPLETE_FILE.exists()
+
+
+def mark_onboarding_complete() -> None:
+    """Mark onboarding as complete."""
+    ONBOARDING_COMPLETE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    with open(ONBOARDING_COMPLETE_FILE, "w") as f:
+        f.write("completed\n")
+
+
+def should_show_onboarding() -> bool:
+    """Determine if the onboarding wizard should be shown.
+
+    Returns False if:
+    - User has already completed onboarding
+    - MUSE_SKIP_TUTORIAL env var is set to '1' or 'true'
+    """
+    # Allow skipping tutorial via environment variable (useful for testing)
+    skip_env = os.environ.get("MUSE_SKIP_TUTORIAL", "").lower()
+    if skip_env in ("1", "true", "yes"):
+        return False
+    return not has_completed_onboarding()
+
+
+def reset_onboarding() -> None:
+    """Reset onboarding state (for re-running with /tutorial)."""
+    if ONBOARDING_COMPLETE_FILE.exists():
+        ONBOARDING_COMPLETE_FILE.unlink()
+
+
+# ============================================================================
+# Onboarding Wizard Class
+# ============================================================================
+
+
+class OnboardingWizard:
+    """5-slide interactive tutorial.
+
+    Slides:
+        0: Welcome
+        1: Model selection
+        2: Use cases (Planning vs Coding)
+        3: Done!
+    """
+
+    TOTAL_SLIDES = 4
+
+    def __init__(self):
+        """Initialize wizard state."""
+        self.current_slide = 0
+        self.selected_option = 0
+        self.trigger_oauth: str | None = None
+        self.model_choice: str | None = None
+        self.result: str | None = None
+        self._should_exit = False
+
+    def get_progress_indicator(self) -> str:
+        """Progress dots: ● ○ ○ ○ ○"""
+        return " ".join(
+            "●" if i == self.current_slide else "○" for i in range(self.TOTAL_SLIDES)
+        )
+
+    def get_slide_content(self) -> str:
+        """Get content for current slide."""
+        if self.current_slide == 0:
+            return slide_welcome()
+        elif self.current_slide == 1:
+            options = self.get_options_for_slide()
+            return slide_models(self.selected_option, options)
+        elif self.current_slide == 2:
+            return slide_use_cases()
+        else:  # slide 3
+            return slide_done(self.trigger_oauth)
+
+    def get_options_for_slide(self) -> list[tuple[str, str]]:
+        """Get selectable options for current slide."""
+        if self.current_slide == 1:  # Model selection
+            return [(opt[0], opt[1]) for opt in MODEL_OPTIONS]
+        return []
+
+    def handle_option_select(self) -> None:
+        """Handle option selection."""
+        if self.current_slide == 1:  # Model selection
+            options = self.get_options_for_slide()
+            if 0 <= self.selected_option < len(options):
+                choice_id = options[self.selected_option][0]
+                self.model_choice = choice_id
+                if choice_id == "chatgpt":
+                    self.trigger_oauth = "chatgpt"
+                elif choice_id == "claude":
+                    self.trigger_oauth = "claude"
+
+    def next_slide(self) -> bool:
+        """Move to next slide."""
+        if self.current_slide < self.TOTAL_SLIDES - 1:
+            self.current_slide += 1
+            self.selected_option = 0
+            return True
+        return False
+
+    def prev_slide(self) -> bool:
+        """Move to previous slide."""
+        if self.current_slide > 0:
+            self.current_slide -= 1
+            self.selected_option = 0
+            return True
+        return False
+
+    def next_option(self) -> None:
+        """Move to next option."""
+        options = self.get_options_for_slide()
+        if options:
+            self.selected_option = (self.selected_option + 1) % len(options)
+
+    def prev_option(self) -> None:
+        """Move to previous option."""
+        options = self.get_options_for_slide()
+        if options:
+            self.selected_option = (self.selected_option - 1) % len(options)
+
+
+# ============================================================================
+# TUI Rendering
+# ============================================================================
+
+
+def _get_slide_panel_content(wizard: OnboardingWizard) -> ANSI:
+    """Generate slide content for display."""
+    buffer = io.StringIO()
+    console = Console(
+        file=buffer,
+        force_terminal=True,
+        width=80,
+        legacy_windows=False,
+        color_system="truecolor",
+        no_color=False,
+        force_interactive=True,
+    )
+
+    # Progress indicator
+    progress = wizard.get_progress_indicator()
+    console.print(f"[dim]{progress}[/dim]")
+    console.print(
+        f"[dim]Slide {wizard.current_slide + 1} of {wizard.TOTAL_SLIDES}[/dim]\n"
+    )
+
+    # Slide content (includes nav footer)
+    console.print(wizard.get_slide_content())
+
+    return ANSI(buffer.getvalue())
+
+
+# ============================================================================
+# Main Entry Point
+# ============================================================================
+
+
+async def run_onboarding_wizard() -> str | None:
+    """Run the interactive tutorial.
+
+    Returns:
+        - "chatgpt" if user wants ChatGPT OAuth
+        - "claude" if user wants Claude OAuth
+        - "completed" if finished normally
+        - "skipped" if user pressed ESC
+        - None on error
+    """
+    from code_muse.tools.command_runner import set_awaiting_user_input
+
+    wizard = OnboardingWizard()
+    set_awaiting_user_input(True)
+
+    # Enter alternate screen buffer
+    sys.stdout.write("\033[?1049h")  # Enter alternate buffer
+    sys.stdout.write("\033[2J\033[H")  # Clear and home
+    sys.stdout.flush()
+    await asyncio.sleep(0.1)
+
+    try:
+        kb = KeyBindings()
+
+        @kb.add("right")
+        @kb.add("l")
+        def next_slide(event):
+            if wizard.current_slide == wizard.TOTAL_SLIDES - 1:
+                wizard.result = "completed"
+                wizard._should_exit = True
+                event.app.exit()
+            else:
+                wizard.next_slide()
+            event.app.invalidate()
+
+        @kb.add("left")
+        @kb.add("h")
+        def prev_slide(event):
+            wizard.prev_slide()
+            event.app.invalidate()
+
+        @kb.add("down")
+        @kb.add("j")
+        @kb.add("c-n")  # Ctrl+N = next (Emacs-style)
+        def next_option(event):
+            wizard.next_option()
+            event.app.invalidate()
+
+        @kb.add("up")
+        @kb.add("k")
+        @kb.add("c-p")  # Ctrl+P = previous (Emacs-style)
+        def prev_option(event):
+            wizard.prev_option()
+            event.app.invalidate()
+
+        @kb.add("enter")
+        def select_or_next(event):
+            options = wizard.get_options_for_slide()
+            if options:
+                wizard.handle_option_select()
+
+            if wizard.current_slide == wizard.TOTAL_SLIDES - 1:
+                wizard.result = "completed"
+                wizard._should_exit = True
+                event.app.exit()
+            else:
+                wizard.next_slide()
+            event.app.invalidate()
+
+        @kb.add("escape")
+        def skip_wizard(event):
+            wizard.result = "skipped"
+            wizard._should_exit = True
+            event.app.exit()
+
+        @kb.add("c-c")
+        def cancel_wizard(event):
+            wizard.result = "skipped"
+            wizard._should_exit = True
+            event.app.exit()
+
+        slide_panel = Window(
+            content=FormattedTextControl(lambda: _get_slide_panel_content(wizard))
+        )
+
+        root_container = Frame(slide_panel, title="Muse Tutorial")
+        layout = Layout(root_container)
+
+        app = Application(
+            layout=layout,
+            key_bindings=kb,
+            full_screen=False,
+            mouse_support=False,
+            color_depth="DEPTH_24_BIT",
+        )
+
+        sys.stdout.write("\033[2J\033[H")
+        sys.stdout.flush()
+
+        await app.run_async()
+
+    except KeyboardInterrupt:
+        wizard.result = "skipped"
+    except Exception:
+        wizard.result = None
+    finally:
+        set_awaiting_user_input(False)
+        sys.stdout.write("\033[?1049l")
+        sys.stdout.flush()
+
+    # Clear exit message
+    from code_muse.messaging import emit_info
+
+    if wizard.result == "skipped":
+        emit_info("✓ Tutorial skipped")
+    elif wizard.result == "completed":
+        emit_info("[Done] Tutorial complete. Welcome.")
+    else:
+        emit_info("✓ Exited tutorial")
+
+    if wizard.result in ("completed", "skipped"):
+        mark_onboarding_complete()
+
+    if wizard.trigger_oauth:
+        return wizard.trigger_oauth
+
+    return wizard.result
+
+
+async def run_onboarding_if_needed() -> str | None:
+    """Run tutorial if user hasn't seen it yet."""
+    if should_show_onboarding():
+        return await run_onboarding_wizard()
+    return None

code_muse/command_line/pagination.py

@@ -0,0 +1,41 @@
+"""Shared pagination helpers for command-line TUIs.
+
+These helpers keep page math consistent across menus so selection and
+page navigation behave the same way everywhere.
+"""
+
+
+def get_total_pages(total_items: int, page_size: int) -> int:
+    """Return the total number of pages for a paginated list."""
+    if page_size <= 0:
+        raise ValueError("page_size must be greater than 0")
+    if total_items <= 0:
+        return 1
+    return (total_items + page_size - 1) // page_size
+
+
+def get_page_bounds(page: int, total_items: int, page_size: int) -> tuple[int, int]:
+    """Return the inclusive start and exclusive end index for a page."""
+    start = max(0, page) * page_size
+    end = min(start + page_size, max(0, total_items))
+    return start, end
+
+
+def get_page_for_index(index: int, page_size: int) -> int:
+    """Return the page containing the given absolute index."""
+    if page_size <= 0:
+        raise ValueError("page_size must be greater than 0")
+    return max(0, index) // page_size
+
+
+def ensure_visible_page(
+    selected_index: int,
+    current_page: int,
+    total_items: int,
+    page_size: int,
+) -> int:
+    """Return the page that keeps the selected item visible."""
+    start, end = get_page_bounds(current_page, total_items, page_size)
+    if selected_index < start or selected_index >= end:
+        return get_page_for_index(selected_index, page_size)
+    return current_page