tunacode-cli 0.0.67__py3-none-any.whl → 0.0.68__py3-none-any.whl

tunacode/tools/grep.py

@@ -20,8 +20,6 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
-import defusedxml.ElementTree as ET
-
 from tunacode.configuration.defaults import DEFAULT_USER_CONFIG
 from tunacode.exceptions import TooBroadPatternError, ToolExecutionError
 from tunacode.tools.base import BaseTool
@@ -32,6 +30,7 @@ from tunacode.tools.grep_components import (
     SearchResult,
 )
 from tunacode.tools.grep_components.result_formatter import ResultFormatter
+from tunacode.tools.xml_helper import load_parameters_schema_from_xml, load_prompt_from_xml
 from tunacode.utils.ripgrep import RipgrepExecutor
 from tunacode.utils.ripgrep import metrics as ripgrep_metrics
 
@@ -66,17 +65,10 @@ class ParallelGrep(BaseTool):
         Returns:
             str: The loaded prompt from XML or a default prompt
         """
-        try:
-            # Load prompt from XML file
-            prompt_file = Path(__file__).parent / "prompts" / "grep_prompt.xml"
-            if prompt_file.exists():
-                tree = ET.parse(prompt_file)
-                root = tree.getroot()
-                description = root.find("description")
-                if description is not None:
-                    return description.text.strip()
-        except Exception as e:
-            logger.warning(f"Failed to load XML prompt for grep: {e}")
+        # Try to load from XML helper
+        prompt = load_prompt_from_xml("grep")
+        if prompt:
+            return prompt
 
         # Fallback to default prompt
         return """A powerful search tool built on ripgrep
@@ -94,44 +86,10 @@ Usage:
         Returns:
             Dict containing the JSON schema for tool parameters
         """
-        # Try to load from XML first
-        try:
-            prompt_file = Path(__file__).parent / "prompts" / "grep_prompt.xml"
-            if prompt_file.exists():
-                tree = ET.parse(prompt_file)
-                root = tree.getroot()
-                parameters = root.find("parameters")
-                if parameters is not None:
-                    schema: Dict[str, Any] = {"type": "object", "properties": {}, "required": []}
-                    required_fields: List[str] = []
-
-                    for param in parameters.findall("parameter"):
-                        name = param.get("name")
-                        required = param.get("required", "false").lower() == "true"
-                        param_type = param.find("type")
-                        description = param.find("description")
-
-                        if name and param_type is not None:
-                            prop = {
-                                "type": param_type.text.strip(),
-                                "description": description.text.strip()
-                                if description is not None
-                                else "",
-                            }
-
-                            # Add enum values if present
-                            enums = param.findall("enum")
-                            if enums:
-                                prop["enum"] = [e.text.strip() for e in enums]
-
-                            schema["properties"][name] = prop
-                            if required:
-                                required_fields.append(name)
-
-                    schema["required"] = required_fields
-                    return schema
-        except Exception as e:
-            logger.warning(f"Failed to load parameters from XML for grep: {e}")
+        # Try to load from XML helper
+        schema = load_parameters_schema_from_xml("grep")
+        if schema:
+            return schema
 
         # Fallback to hardcoded schema
         return {

tunacode/tools/xml_helper.py

@@ -0,0 +1,83 @@
+"""Helper module for loading prompts and schemas from XML files."""
+
+import logging
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import defusedxml.ElementTree as ET
+
+logger = logging.getLogger(__name__)
+
+
+@lru_cache(maxsize=32)
+def load_prompt_from_xml(tool_name: str) -> Optional[str]:
+    """Load and return the base prompt from XML file.
+
+    Args:
+        tool_name: Name of the tool (e.g., 'grep', 'glob')
+
+    Returns:
+        str: The loaded prompt from XML or None if not found
+    """
+    try:
+        prompt_file = Path(__file__).parent / "prompts" / f"{tool_name}_prompt.xml"
+        if prompt_file.exists():
+            tree = ET.parse(prompt_file)
+            root = tree.getroot()
+            description = root.find("description")
+            if description is not None:
+                return description.text.strip()
+    except Exception as e:
+        logger.warning(f"Failed to load XML prompt for {tool_name}: {e}")
+    return None
+
+
+@lru_cache(maxsize=32)
+def load_parameters_schema_from_xml(tool_name: str) -> Optional[Dict[str, Any]]:
+    """Load and return the parameters schema from XML file.
+
+    Args:
+        tool_name: Name of the tool (e.g., 'grep', 'glob')
+
+    Returns:
+        Dict containing the JSON schema for tool parameters or None if not found
+    """
+    try:
+        prompt_file = Path(__file__).parent / "prompts" / f"{tool_name}_prompt.xml"
+        if prompt_file.exists():
+            tree = ET.parse(prompt_file)
+            root = tree.getroot()
+            parameters = root.find("parameters")
+            if parameters is not None:
+                schema: Dict[str, Any] = {"type": "object", "properties": {}, "required": []}
+                required_fields: List[str] = []
+
+                for param in parameters.findall("parameter"):
+                    name = param.get("name")
+                    required = param.get("required", "false").lower() == "true"
+                    param_type = param.find("type")
+                    description = param.find("description")
+
+                    if name and param_type is not None:
+                        prop = {
+                            "type": param_type.text.strip(),
+                            "description": description.text.strip()
+                            if description is not None
+                            else "",
+                        }
+
+                        # Add enum values if present
+                        enums = param.findall("enum")
+                        if enums:
+                            prop["enum"] = [e.text.strip() for e in enums]
+
+                        schema["properties"][name] = prop
+                        if required:
+                            required_fields.append(name)
+
+                schema["required"] = required_fields
+                return schema
+    except Exception as e:
+        logger.warning(f"Failed to load parameters from XML for {tool_name}: {e}")
+    return None

tunacode/tutorial/__init__.py

@@ -0,0 +1,9 @@
+"""
+Module: tunacode.tutorial
+
+Tutorial system for TunaCode onboarding and user guidance.
+"""
+
+from .manager import TutorialManager
+
+__all__ = ["TutorialManager"]

tunacode/tutorial/content.py

@@ -0,0 +1,98 @@
+"""
+Module: tunacode.tutorial.content
+
+Tutorial content definitions and step configurations.
+"""
+
+from typing import Dict, List
+
+# Tutorial step content library
+TUTORIAL_CONTENT: Dict[str, Dict[str, str]] = {
+    "welcome": {
+        "title": "🎯 Welcome to TunaCode!",
+        "content": """TunaCode is your AI-powered development assistant.
+
+In this quick tutorial, you'll learn how to:
+• Chat with AI about your code
+• Use commands to control TunaCode
+• Work with files and projects
+• Get help when you need it
+
+This tutorial takes about 2-3 minutes. Ready to start?""",
+        "action": "Press Enter to continue...",
+    },
+    "basic_chat": {
+        "title": "💬 Basic AI Chat",
+        "content": """The core of TunaCode is natural conversation with AI.
+
+You can ask questions like:
+• "How do I implement a binary search in Python?"
+• "Review this function and suggest improvements"
+• "Help me debug this error message"
+• "Explain what this code does"
+
+Just type your question naturally - no special syntax needed!""",
+        "action": "Try asking: 'What can you help me with?'",
+    },
+    "file_operations": {
+        "title": "📁 Working with Files",
+        "content": """TunaCode can read, create, and modify files in your project.
+
+Useful commands:
+• Reference files with @filename.py
+• Use /read to explicitly read files
+• Ask to create or modify files
+• Get help with /help
+
+TunaCode understands your project structure and can work across multiple files.""",
+        "action": "Try: 'Read the current directory structure'",
+    },
+    "commands": {
+        "title": "⚙️ TunaCode Commands",
+        "content": """Commands start with / and give you control over TunaCode:
+
+Essential commands:
+• /help - Show all available commands
+• /model - Switch AI models
+• /clear - Clear conversation history
+• /exit - Exit TunaCode
+
+System commands:
+• !command - Run shell commands
+• /streaming - Toggle streaming responses""",
+        "action": "Try typing: /help",
+    },
+    "best_practices": {
+        "title": "✨ Best Practices",
+        "content": """To get the most out of TunaCode:
+
+🎯 Be specific: "Fix the bug in login.py line 42" vs "fix my code"
+📁 Use file references: "@app.py" to include files in context
+🔄 Break down large tasks: Ask for step-by-step guidance
+💬 Ask follow-up questions: TunaCode remembers your conversation
+🚀 Experiment: Try different prompts to see what works best
+
+Remember: TunaCode is here to help you code faster and better!""",
+        "action": "Press Enter to complete the tutorial...",
+    },
+    "completion": {
+        "title": "🎉 Tutorial Complete!",
+        "content": """Congratulations! You're ready to use TunaCode.
+
+Quick recap:
+✅ Chat naturally with AI about code
+✅ Use @ to reference files
+✅ Try /help for commands
+✅ Ask specific questions for better results
+
+🚀 Ready to start coding? Just ask TunaCode anything!
+
+Need help later? Use /quickstart to review this tutorial anytime.""",
+        "action": "Press Enter to start using TunaCode...",
+    },
+}
+
+
+def get_tutorial_steps() -> List[str]:
+    """Get the ordered list of tutorial step IDs."""
+    return ["welcome", "basic_chat", "file_operations", "commands", "best_practices", "completion"]

tunacode/tutorial/manager.py

@@ -0,0 +1,182 @@
+"""
+Module: tunacode.tutorial.manager
+
+Tutorial manager for orchestrating the TunaCode onboarding experience.
+"""
+
+import logging
+
+from ..types import StateManager
+from ..ui import console as ui
+from .steps import (
+    create_tutorial_steps,
+    is_first_time_user,
+    is_tutorial_completed,
+    is_tutorial_declined,
+    load_tutorial_progress,
+    mark_tutorial_completed,
+    mark_tutorial_declined,
+    save_tutorial_progress,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class TutorialManager:
+    """Manages the tutorial experience for TunaCode users."""
+
+    def __init__(self, state_manager: StateManager):
+        self.state_manager = state_manager
+        self.steps = [
+            "welcome",
+            "basic_chat",
+            "file_operations",
+            "commands",
+            "best_practices",
+            "completion",
+        ]
+
+    async def should_offer_tutorial(self) -> bool:
+        """Determine if we should offer the tutorial to the user."""
+        # Don't offer if already completed or declined
+        if is_tutorial_completed(self.state_manager):
+            return False
+
+        if is_tutorial_declined(self.state_manager):
+            return False
+
+        # Check if tutorial is enabled in settings
+        settings = self.state_manager.session.user_config.get("settings", {})
+        tutorial_enabled = settings.get("enable_tutorial", True)
+
+        if not tutorial_enabled:
+            return False
+
+        # Only offer to first-time users (installed within last 7 days)
+        if not is_first_time_user(self.state_manager):
+            return False
+
+        # Check if this is a fresh session (no significant interaction yet)
+        message_count = len(self.state_manager.session.messages)
+
+        # Offer tutorial if user has minimal interaction history
+        return message_count < 3
+
+    async def offer_tutorial(self) -> bool:
+        """Offer the tutorial to the user and return whether they accepted."""
+        await ui.panel(
+            "🎯 Welcome to TunaCode!",
+            "Would you like a quick 2-minute tutorial to get started?\n"
+            "This will help you learn the basics and start coding faster.",
+            border_style="cyan",
+        )
+
+        choice = await ui.input(
+            "tutorial_offer",
+            pretext="  → Start tutorial? [Y/n]: ",
+            state_manager=self.state_manager,
+        )
+
+        choice = choice.strip().lower()
+
+        if choice in ["n", "no", "false"]:
+            await ui.muted("Tutorial skipped. Use [green]/quickstart[/green] anytime to start it!")
+            # Mark as declined so we don't ask again
+            mark_tutorial_declined(self.state_manager)
+
+            # Save the configuration to persist the declined status
+            try:
+                from ..utils import user_configuration
+
+                user_configuration.save_config(self.state_manager)
+            except Exception as e:
+                logger.warning(f"Failed to save tutorial declined status: {e}")
+
+            return False
+
+        return True
+
+    async def run_tutorial(self, resume: bool = False) -> bool:
+        """
+        Run the complete tutorial experience.
+
+        Args:
+            resume: If True, resume from saved progress
+
+        Returns:
+            True if tutorial completed successfully, False if cancelled
+        """
+        try:
+            from .content import TUTORIAL_CONTENT
+
+            # Load progress or start from beginning
+            current_step = load_tutorial_progress(self.state_manager) if resume else 0
+            steps = create_tutorial_steps()
+
+            await ui.line()
+            await ui.info(f"🎯 Starting TunaCode Tutorial ({len(steps)} steps)")
+            await ui.line()
+
+            while current_step < len(steps):
+                step_id = steps[current_step]
+                step_content = TUTORIAL_CONTENT.get(step_id, {})
+
+                if not step_content:
+                    logger.warning(f"Missing content for tutorial step: {step_id}")
+                    current_step += 1
+                    continue
+
+                # Display step content
+                await ui.panel(
+                    f"Step {current_step + 1}/{len(steps)}: {step_content.get('title', step_id)}",
+                    step_content.get("content", ""),
+                    border_style="cyan",
+                )
+
+                # Get user input for progression
+                action_text = step_content.get("action", "Press Enter to continue...")
+                try:
+                    user_input = await ui.input(
+                        f"tutorial_step_{current_step}",
+                        pretext=f"  → {action_text} ",
+                        state_manager=self.state_manager,
+                    )
+
+                    # Allow users to exit tutorial early
+                    if user_input.lower() in ["quit", "exit", "skip"]:
+                        await ui.info(
+                            "Tutorial cancelled. Use [green]/quickstart[/green] to restart anytime!"
+                        )
+                        return False
+
+                except Exception as e:
+                    logger.warning(f"Tutorial interrupted: {e}")
+                    # Save progress before exiting
+                    save_tutorial_progress(self.state_manager, current_step)
+                    await ui.info("Tutorial paused. Use [green]/quickstart[/green] to resume!")
+                    return False
+
+                current_step += 1
+                save_tutorial_progress(self.state_manager, current_step)
+
+            # Tutorial completed successfully
+            mark_tutorial_completed(self.state_manager)
+
+            # Save the completion status
+            try:
+                from ..utils import user_configuration
+
+                user_configuration.save_config(self.state_manager)
+            except Exception as e:
+                logger.warning(f"Failed to save tutorial completion status: {e}")
+
+            await ui.line()
+            await ui.success("🎉 Tutorial completed! You're ready to use TunaCode.")
+            await ui.line()
+
+            return True
+
+        except Exception as e:
+            logger.error(f"Tutorial failed: {e}")
+            await ui.error(f"Tutorial encountered an error: {e}")
+            return False

tunacode/tutorial/steps.py

@@ -0,0 +1,124 @@
+"""
+Module: tunacode.tutorial.steps
+
+Tutorial step management and progress tracking functionality.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import List, Optional
+
+from ..types import StateManager
+from .content import get_tutorial_steps
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TutorialStepResult:
+    """Result of executing a tutorial step."""
+
+    completed: bool
+    should_continue: bool
+    user_input: Optional[str] = None
+
+
+def create_tutorial_steps() -> List[str]:
+    """Create and return the list of tutorial steps."""
+    return get_tutorial_steps()
+
+
+def get_tutorial_completion_key() -> str:
+    """Get the config key for storing tutorial completion status."""
+    return "tutorial_completed"
+
+
+def get_tutorial_progress_key() -> str:
+    """Get the config key for storing tutorial progress."""
+    return "tutorial_progress"
+
+
+def mark_tutorial_completed(state_manager: StateManager) -> None:
+    """Mark the tutorial as completed in user config."""
+    if "settings" not in state_manager.session.user_config:
+        state_manager.session.user_config["settings"] = {}
+
+    state_manager.session.user_config["settings"][get_tutorial_completion_key()] = True
+
+    # Clear any existing progress since it's now completed
+    if get_tutorial_progress_key() in state_manager.session.user_config["settings"]:
+        del state_manager.session.user_config["settings"][get_tutorial_progress_key()]
+
+
+def save_tutorial_progress(state_manager: StateManager, current_step: int) -> None:
+    """Save tutorial progress to user config."""
+    if "settings" not in state_manager.session.user_config:
+        state_manager.session.user_config["settings"] = {}
+
+    state_manager.session.user_config["settings"][get_tutorial_progress_key()] = current_step
+
+
+def load_tutorial_progress(state_manager: StateManager) -> int:
+    """Load tutorial progress from user config."""
+    settings = state_manager.session.user_config.get("settings", {})
+    return settings.get(get_tutorial_progress_key(), 0)
+
+
+def clear_tutorial_progress(state_manager: StateManager) -> None:
+    """Clear tutorial progress from user config."""
+    if "settings" not in state_manager.session.user_config:
+        return
+
+    if get_tutorial_progress_key() in state_manager.session.user_config["settings"]:
+        del state_manager.session.user_config["settings"][get_tutorial_progress_key()]
+
+
+def is_tutorial_completed(state_manager: StateManager) -> bool:
+    """Check if the tutorial has been completed."""
+    settings = state_manager.session.user_config.get("settings", {})
+    return settings.get(get_tutorial_completion_key(), False)
+
+
+def get_tutorial_declined_key() -> str:
+    """Get the config key for storing tutorial declined status."""
+    return "tutorial_declined"
+
+
+def mark_tutorial_declined(state_manager: StateManager) -> None:
+    """Mark the tutorial as declined in user config."""
+    if "settings" not in state_manager.session.user_config:
+        state_manager.session.user_config["settings"] = {}
+
+    state_manager.session.user_config["settings"][get_tutorial_declined_key()] = True
+
+    # Clear any existing progress since it was declined
+    if get_tutorial_progress_key() in state_manager.session.user_config["settings"]:
+        del state_manager.session.user_config["settings"][get_tutorial_progress_key()]
+
+
+def is_tutorial_declined(state_manager: StateManager) -> bool:
+    """Check if the tutorial has been declined."""
+    settings = state_manager.session.user_config.get("settings", {})
+    return settings.get(get_tutorial_declined_key(), False)
+
+
+def is_first_time_user(state_manager: StateManager) -> bool:
+    """Check if this is a first-time user based on installation date."""
+    from datetime import datetime, timedelta
+
+    settings = state_manager.session.user_config.get("settings", {})
+    installation_date_str = settings.get("first_installation_date")
+
+    if not installation_date_str:
+        # No installation date means legacy user, treat as experienced
+        return False
+
+    try:
+        installation_date = datetime.fromisoformat(installation_date_str)
+        now = datetime.now()
+
+        # Consider first-time if installed within last 7 days
+        return (now - installation_date) <= timedelta(days=7)
+    except (ValueError, TypeError):
+        # Invalid date format, treat as experienced user
+        return False

tunacode/ui/output.py

@@ -23,7 +23,7 @@ from .decorators import create_sync_wrapper
 from .logging_compat import ui_logger
 
 # Create console with explicit settings to ensure ANSI codes work properly
-console = Console(force_terminal=True, legacy_windows=False)
+console = Console()
 colors = DotDict(UI_COLORS)
 
 BANNER = """[bold cyan]

tunacode/utils/user_configuration.py

@@ -45,6 +45,10 @@ def load_config() -> Optional[UserConfig]:
             # else, update fast path
             _config_fingerprint = new_fp
             _config_cache = loaded
+
+            # Initialize onboarding defaults for new configurations
+            _ensure_onboarding_defaults(loaded)
+
             return loaded
     except FileNotFoundError:
         return None
@@ -91,3 +95,44 @@ def set_default_model(model_name: ModelName, state_manager: "StateManager") -> b
     except ConfigurationError:
         # Re-raise ConfigurationError to be handled by caller
         raise
+
+
+def _ensure_onboarding_defaults(config: UserConfig) -> None:
+    """Ensure onboarding-related default settings are present in config."""
+    from datetime import datetime
+
+    if "settings" not in config:
+        config["settings"] = {}
+
+    settings = config["settings"]
+
+    # Set tutorial enabled by default for new users
+    if "enable_tutorial" not in settings:
+        settings["enable_tutorial"] = True
+
+    # Set first installation date if not present (for new installs)
+    if "first_installation_date" not in settings:
+        settings["first_installation_date"] = datetime.now().isoformat()
+
+
+def initialize_first_time_user(state_manager: "StateManager") -> None:
+    """Initialize first-time user settings and save configuration."""
+    from datetime import datetime
+
+    # Ensure settings section exists
+    if "settings" not in state_manager.session.user_config:
+        state_manager.session.user_config["settings"] = {}
+
+    settings = state_manager.session.user_config["settings"]
+
+    # Only set installation date if it doesn't exist (true first-time)
+    if "first_installation_date" not in settings:
+        settings["first_installation_date"] = datetime.now().isoformat()
+        settings["enable_tutorial"] = True
+
+        # Save the updated configuration
+        try:
+            save_config(state_manager)
+        except ConfigurationError:
+            # Non-critical error, continue without failing
+            pass