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

tunacode/core/setup/config_setup.py

@@ -37,12 +37,16 @@ class ConfigSetup(BaseSetup):
         """Config setup should always run to load and merge configuration."""
         return True
 
-    async def execute(self, force_setup: bool = False) -> None:
+    async def execute(self, force_setup: bool = False, wizard_mode: bool = False) -> None:
         """Setup configuration and run onboarding if needed, with config fingerprint fast path."""
         import hashlib
 
         self.state_manager.session.device_id = system.get_device_id()
         loaded_config = user_configuration.load_config()
+
+        # Initialize first-time user settings if needed
+        user_configuration.initialize_first_time_user(self.state_manager)
+
         # Fast path: if config fingerprint matches last loaded and config is already present, skip reprocessing
         new_fp = None
         if loaded_config:
@@ -52,6 +56,7 @@ class ConfigSetup(BaseSetup):
         if (
             loaded_config
             and not force_setup
+            and not wizard_mode
             and new_fp
             and last_fp == new_fp
             and getattr(self.state_manager, "_config_valid", False)
@@ -68,13 +73,17 @@ class ConfigSetup(BaseSetup):
             await self._handle_cli_config(loaded_config)
             return
 
-        if loaded_config and not force_setup:
+        if loaded_config and not force_setup and not wizard_mode:
             # Silent loading
             # Merge loaded config with defaults to ensure all required keys exist
             self.state_manager.session.user_config = self._merge_with_defaults(loaded_config)
         else:
-            if force_setup:
-                await ui.muted("Running setup process, resetting config")
+            if force_setup or wizard_mode:
+                if wizard_mode:
+                    await ui.muted("Running interactive setup wizard")
+                else:
+                    await ui.muted("Running setup process, resetting config")
+
                 # Ensure user_config is properly initialized
                 if (
                     not hasattr(self.state_manager.session, "user_config")
@@ -89,7 +98,11 @@ class ConfigSetup(BaseSetup):
                 except ConfigurationError as e:
                     await ui.error(str(e))
                     raise
-                await self._onboarding()
+
+                if wizard_mode:
+                    await self._wizard_onboarding()
+                else:
+                    await self._onboarding()
             else:
                 # No config found - show CLI usage instead of onboarding
                 from tunacode.ui.console import console
@@ -107,9 +120,10 @@ class ConfigSetup(BaseSetup):
                     "--key 'your-key' --baseurl 'https://openrouter.ai/api/v1'[/green]"
                 )
                 console.print("\n[yellow]Run 'tunacode --help' for more options[/yellow]\n")
+                console.print("\n[cyan]Or use --wizard for guided setup[/cyan]\n")
 
                 raise ConfigurationError(
-                    "No configuration found. Please use CLI flags to configure."
+                    "No configuration found. Please use CLI flags to configure or --wizard for guided setup."
                 )
 
         if not self.state_manager.session.user_config.get("default_model"):
@@ -339,3 +353,214 @@ class ConfigSetup(BaseSetup):
             await ui.success(f"Configuration saved to: {self.config_file}")
         except ConfigurationError as e:
             await ui.error(str(e))
+
+    async def _wizard_onboarding(self):
+        """Run enhanced wizard-style onboarding process for new users."""
+        initial_config = json.dumps(self.state_manager.session.user_config, sort_keys=True)
+
+        # Welcome message with provider guidance
+        await ui.panel(
+            "Welcome to TunaCode Setup Wizard!",
+            "This guided setup will help you configure TunaCode in under 5 minutes.\n"
+            "We'll help you choose a provider, set up your API keys, and configure your preferred model.",
+            border_style=UI_COLORS["primary"],
+        )
+
+        # Step 1: Provider selection with detailed guidance
+        await self._wizard_step1_provider_selection()
+
+        # Step 2: API key setup with provider-specific guidance
+        await self._wizard_step2_api_key_setup()
+
+        # Step 3: Model selection with smart recommendations
+        await self._wizard_step3_model_selection()
+
+        # Step 4: Optional settings configuration
+        await self._wizard_step4_optional_settings()
+
+        # Save configuration and finish
+        current_config = json.dumps(self.state_manager.session.user_config, sort_keys=True)
+        if initial_config != current_config:
+            try:
+                user_configuration.save_config(self.state_manager)
+                await ui.panel(
+                    "Setup Complete!",
+                    f"Configuration saved to: [bold]{self.config_file}[/bold]\n\n"
+                    "You're ready to start using TunaCode!\n"
+                    "Use [green]/quickstart[/green] anytime for a tutorial.",
+                    border_style=UI_COLORS["success"],
+                )
+            except ConfigurationError as e:
+                await ui.error(str(e))
+
+    async def _wizard_step1_provider_selection(self):
+        """Wizard step 1: Provider selection with detailed explanations."""
+        provider_info = {
+            "1": {
+                "name": "OpenRouter",
+                "description": "Access to multiple models (GPT-4, Claude, Gemini, etc.)",
+                "signup": "https://openrouter.ai/",
+                "key_name": "OPENROUTER_API_KEY",
+            },
+            "2": {
+                "name": "OpenAI",
+                "description": "GPT-4 models",
+                "signup": "https://platform.openai.com/signup",
+                "key_name": "OPENAI_API_KEY",
+            },
+            "3": {
+                "name": "Anthropic",
+                "description": "Claude-3 models",
+                "signup": "https://console.anthropic.com/",
+                "key_name": "ANTHROPIC_API_KEY",
+            },
+            "4": {
+                "name": "Google",
+                "description": "Gemini models",
+                "signup": "https://ai.google.dev/",
+                "key_name": "GEMINI_API_KEY",
+            },
+        }
+
+        message = "Choose your AI provider:\n\n"
+        for key, info in provider_info.items():
+            message += f"  {key} - {info['name']}: {info['description']}\n"
+
+        await ui.panel("Provider Selection", message, border_style=UI_COLORS["primary"])
+
+        while True:
+            choice = await ui.input(
+                "wizard_provider",
+                pretext="  Choose provider (1-4): ",
+                state_manager=self.state_manager,
+            )
+
+            if choice.strip() in provider_info:
+                selected = provider_info[choice.strip()]
+                self._wizard_selected_provider = selected
+
+                await ui.success(f"Selected: {selected['name']}")
+                await ui.info(f"Sign up at: {selected['signup']}")
+                break
+            else:
+                await ui.error("Please enter 1, 2, 3, or 4")
+
+    async def _wizard_step2_api_key_setup(self):
+        """Wizard step 2: API key setup with provider-specific guidance."""
+        provider = self._wizard_selected_provider
+
+        message = f"Enter your {provider['name']} API key:\n\n"
+        message += f"Get your key from: {provider['signup']}\n"
+        message += "Your key will be stored securely in your local config"
+
+        await ui.panel(f"{provider['name']} API Key", message, border_style=UI_COLORS["primary"])
+
+        while True:
+            api_key = await ui.input(
+                "wizard_api_key",
+                pretext=f"  {provider['name']} API Key: ",
+                is_password=True,
+                state_manager=self.state_manager,
+            )
+
+            if api_key.strip():
+                # Ensure env dict exists
+                if "env" not in self.state_manager.session.user_config:
+                    self.state_manager.session.user_config["env"] = {}
+
+                self.state_manager.session.user_config["env"][provider["key_name"]] = (
+                    api_key.strip()
+                )
+                await ui.success("API key saved successfully!")
+                break
+            else:
+                await ui.error("API key cannot be empty")
+
+    async def _wizard_step3_model_selection(self):
+        """Wizard step 3: Model selection with smart recommendations."""
+        provider = self._wizard_selected_provider
+
+        # Provide smart recommendations based on provider
+        recommendations = {
+            "OpenAI": [
+                ("openai:gpt-4o", "GPT-4o flagship multimodal model (recommended)"),
+                ("openai:gpt-4.1", "Latest GPT-4.1 with enhanced coding"),
+                ("openai:o3", "Advanced reasoning model for complex tasks"),
+            ],
+            "Anthropic": [
+                ("anthropic:claude-sonnet-4", "Claude Sonnet 4 latest generation (recommended)"),
+                ("anthropic:claude-opus-4.1", "Most capable Claude with extended thinking"),
+                ("anthropic:claude-3.5-sonnet", "Claude 3.5 Sonnet proven performance"),
+            ],
+            "OpenRouter": [
+                (
+                    "openrouter:anthropic/claude-sonnet-4",
+                    "Claude Sonnet 4 via OpenRouter (recommended)",
+                ),
+                ("openrouter:openai/gpt-4o", "GPT-4o multimodal via OpenRouter"),
+                ("openrouter:google/gemini-2.5-flash", "Google Gemini 2.5 Flash latest"),
+            ],
+            "Google": [
+                (
+                    "google:gemini-2.5-pro",
+                    "Gemini 2.5 Pro with thinking capabilities (recommended)",
+                ),
+                ("google:gemini-2.5-flash", "Gemini 2.5 Flash best price-performance"),
+                ("google:gemini-2.0-flash", "Gemini 2.0 Flash with native tool use"),
+            ],
+        }
+
+        models = recommendations.get(provider["name"], [])
+        message = f"Choose your default {provider['name']} model:\n\n"
+
+        for i, (model_id, description) in enumerate(models, 1):
+            message += f"  {i} - {description}\n"
+
+        message += "\nYou can change this later with [green]/model[/green]"
+
+        await ui.panel("Model Selection", message, border_style=UI_COLORS["primary"])
+
+        while True:
+            choice = await ui.input(
+                "wizard_model",
+                pretext=f"  Choose model (1-{len(models)}): ",
+                state_manager=self.state_manager,
+            )
+
+            try:
+                index = int(choice.strip()) - 1
+                if 0 <= index < len(models):
+                    selected_model = models[index][0]
+                    self.state_manager.session.user_config["default_model"] = selected_model
+                    await ui.success(f"Selected: {selected_model}")
+                    break
+                else:
+                    await ui.error(f"Please enter a number between 1 and {len(models)}")
+            except ValueError:
+                await ui.error("Please enter a valid number")
+
+    async def _wizard_step4_optional_settings(self):
+        """Wizard step 4: Optional settings configuration."""
+        message = "Configure optional settings:\n\n"
+        message += "• Tutorial: Enable interactive tutorial for new users\n"
+        message += "\nSkip this step to use recommended defaults"
+
+        await ui.panel("Optional Settings", message, border_style=UI_COLORS["primary"])
+
+        # Ask about tutorial
+        tutorial_choice = await ui.input(
+            "wizard_tutorial",
+            pretext="  Enable tutorial for new users? [Y/n]: ",
+            state_manager=self.state_manager,
+        )
+
+        enable_tutorial = tutorial_choice.strip().lower() not in ["n", "no", "false"]
+
+        if "settings" not in self.state_manager.session.user_config:
+            self.state_manager.session.user_config["settings"] = {}
+
+        self.state_manager.session.user_config["settings"]["enable_tutorial"] = enable_tutorial
+
+        # Streaming is always enabled - no user choice needed
+
+        await ui.info("Optional settings configured!")

tunacode/core/setup/coordinator.py

@@ -22,8 +22,8 @@ class SetupCoordinator:
         """Register a setup step to be run."""
         self.setup_steps.append(step)
 
-    async def run_setup(self, force_setup: bool = False) -> None:
-        """Run all registered setup steps concurrently if possible."""
+    async def run_setup(self, force_setup: bool = False, wizard_mode: bool = False) -> None:
+        """Run all registered setup steps with proper dependency order."""
         # Run should_run checks sequentially (they may depend on order)
         steps_to_run = []
         for step in self.setup_steps:
@@ -35,11 +35,19 @@ class SetupCoordinator:
                     f"Setup failed at step '{getattr(step, 'name', repr(step))}': {str(e)}"
                 )
                 raise
-        # Run all .execute(force_setup) in parallel where possible (independent steps)
-        from asyncio import gather
 
         try:
-            await gather(*(step.execute(force_setup) for step in steps_to_run))
+            # Run steps sequentially to respect dependencies (ConfigSetup must complete before EnvironmentSetup)
+            for step in steps_to_run:
+                # Check if the step's execute method supports wizard_mode
+                import inspect
+
+                sig = inspect.signature(step.execute)
+                if "wizard_mode" in sig.parameters:
+                    await step.execute(force_setup, wizard_mode=wizard_mode)
+                else:
+                    await step.execute(force_setup)
+
             # Now validate all sequentially: if any fail, raise error
             for step in steps_to_run:
                 if not await step.validate():

tunacode/core/setup/git_safety_setup.py

@@ -37,8 +37,12 @@ class GitSafetySetup(BaseSetup):
         # Always run unless user has explicitly disabled it
         return not self.state_manager.session.user_config.get("skip_git_safety", False)
 
-    async def execute(self, _force: bool = False) -> None:
+    async def execute(self, _force: bool = False, wizard_mode: bool = False) -> None:
         """Create a safety branch for TunaCode operations."""
+        # Skip git safety during wizard mode to avoid UI interference
+        if wizard_mode:
+            return
+
         try:
             # Check if git is installed
             result = subprocess.run(

tunacode/exceptions.py

@@ -18,7 +18,18 @@ class TunaCodeError(Exception):
 class ConfigurationError(TunaCodeError):
     """Raised when there's a configuration issue."""
 
-    pass
+    def __init__(self, message: str, suggested_fix: str = None, help_url: str = None):
+        self.suggested_fix = suggested_fix
+        self.help_url = help_url
+
+        # Build enhanced error message with actionable guidance
+        full_message = message
+        if suggested_fix:
+            full_message += f"\n\n💡 Suggested fix: {suggested_fix}"
+        if help_url:
+            full_message += f"\n📖 More help: {help_url}"
+
+        super().__init__(full_message)
 
 
 # User Interaction Exceptions
@@ -31,7 +42,19 @@ class UserAbortError(TunaCodeError):
 class ValidationError(TunaCodeError):
     """Raised when input validation fails."""
 
-    pass
+    def __init__(self, message: str, suggested_fix: str = None, valid_examples: list = None):
+        self.suggested_fix = suggested_fix
+        self.valid_examples = valid_examples or []
+
+        # Build enhanced error message with actionable guidance
+        full_message = f"Validation failed: {message}"
+        if suggested_fix:
+            full_message += f"\n\n💡 Suggested fix: {suggested_fix}"
+        if valid_examples:
+            examples_text = "\n".join(f"  • {example}" for example in valid_examples)
+            full_message += f"\n\n✅ Valid examples:\n{examples_text}"
+
+        super().__init__(full_message)
 
 
 # Tool and Agent Exceptions
@@ -39,17 +62,47 @@ class ToolExecutionError(TunaCodeError):
     """Raised when a tool fails to execute."""
 
     def __init__(
-        self, tool_name: ToolName, message: ErrorMessage, original_error: OriginalError = None
+        self,
+        tool_name: ToolName,
+        message: ErrorMessage,
+        original_error: OriginalError = None,
+        suggested_fix: str = None,
+        recovery_commands: list = None,
     ):
         self.tool_name = tool_name
         self.original_error = original_error
-        super().__init__(f"Tool '{tool_name}' failed: {message}")
+        self.suggested_fix = suggested_fix
+        self.recovery_commands = recovery_commands or []
+
+        # Build enhanced error message
+        full_message = f"Tool '{tool_name}' failed: {message}"
+        if suggested_fix:
+            full_message += f"\n\n💡 Suggested fix: {suggested_fix}"
+        if recovery_commands:
+            commands_text = "\n".join(f"  • {cmd}" for cmd in recovery_commands)
+            full_message += f"\n\n🔧 Recovery commands:\n{commands_text}"
+
+        super().__init__(full_message)
 
 
 class AgentError(TunaCodeError):
     """Raised when agent operations fail."""
 
-    pass
+    def __init__(self, message: str, suggested_fix: str = None, troubleshooting_steps: list = None):
+        self.suggested_fix = suggested_fix
+        self.troubleshooting_steps = troubleshooting_steps or []
+
+        # Build enhanced error message
+        full_message = f"Agent error: {message}"
+        if suggested_fix:
+            full_message += f"\n\n💡 Suggested fix: {suggested_fix}"
+        if troubleshooting_steps:
+            steps_text = "\n".join(
+                f"  {i + 1}. {step}" for i, step in enumerate(troubleshooting_steps)
+            )
+            full_message += f"\n\n🔍 Troubleshooting steps:\n{steps_text}"
+
+        super().__init__(full_message)
 
 
 # State Management Exceptions
@@ -103,6 +156,67 @@ class FileOperationError(TunaCodeError):
         super().__init__(f"File {operation} failed for '{path}': {message}")
 
 
+# Additional specialized exception classes for onboarding scenarios
+class OnboardingError(TunaCodeError):
+    """Raised when onboarding process encounters issues."""
+
+    def __init__(
+        self, message: str, step: str = None, suggested_fix: str = None, help_command: str = None
+    ):
+        self.step = step
+        self.suggested_fix = suggested_fix
+        self.help_command = help_command
+
+        # Build enhanced error message
+        full_message = f"Onboarding failed: {message}"
+        if step:
+            full_message = f"Onboarding failed at step '{step}': {message}"
+        if suggested_fix:
+            full_message += f"\n\n💡 Suggested fix: {suggested_fix}"
+        if help_command:
+            full_message += f"\n🆘 For help: {help_command}"
+
+        super().__init__(full_message)
+
+
+class ModelConfigurationError(ConfigurationError):
+    """Raised when model configuration is invalid."""
+
+    def __init__(self, model: str, issue: str, valid_models: list = None):
+        self.model = model
+        self.issue = issue
+        self.valid_models = valid_models or []
+
+        suggested_fix = "Use --wizard for guided setup or --model with a valid model name"
+        help_url = "https://docs.anthropic.com/en/docs/claude-code"
+
+        message = f"Model '{model}' configuration error: {issue}"
+        if valid_models:
+            examples = valid_models[:3]  # Show first 3 examples
+            suggested_fix += f"\n\nValid examples: {', '.join(examples)}"
+
+        super().__init__(message, suggested_fix=suggested_fix, help_url=help_url)
+
+
+class SetupValidationError(ValidationError):
+    """Raised when setup validation fails."""
+
+    def __init__(self, validation_type: str, details: str, quick_fixes: list = None):
+        self.validation_type = validation_type
+        self.details = details
+        self.quick_fixes = quick_fixes or []
+
+        suggested_fix = "Run 'tunacode --wizard' for guided setup"
+        if quick_fixes:
+            suggested_fix = f"Try these quick fixes: {', '.join(quick_fixes)}"
+
+        super().__init__(
+            f"{validation_type} validation failed: {details}",
+            suggested_fix=suggested_fix,
+            valid_examples=["tunacode --wizard", "tunacode --setup", "tunacode --help"],
+        )
+
+
 class TooBroadPatternError(ToolExecutionError):
     """Raised when a search pattern is too broad and times out."""
 

tunacode/setup.py

@@ -18,7 +18,9 @@ from tunacode.core.setup import (
 from tunacode.core.state import StateManager
 
 
-async def setup(run_setup: bool, state_manager: StateManager, cli_config: dict = None) -> None:
+async def setup(
+    run_setup: bool, state_manager: StateManager, cli_config: dict = None, wizard_mode: bool = False
+) -> None:
     """
     Setup TunaCode on startup using the new setup coordinator.
 
@@ -26,6 +28,7 @@ async def setup(run_setup: bool, state_manager: StateManager, cli_config: dict =
         run_setup (bool): If True, force run the setup process, resetting current config.
         state_manager (StateManager): The state manager instance.
         cli_config (dict): Optional CLI configuration with baseurl, model, and key.
+        wizard_mode (bool): If True, run interactive setup wizard.
     """
     coordinator = SetupCoordinator(state_manager)
 
@@ -39,7 +42,7 @@ async def setup(run_setup: bool, state_manager: StateManager, cli_config: dict =
     coordinator.register_step(GitSafetySetup(state_manager))
 
     # Run all setup steps
-    await coordinator.run_setup(force_setup=run_setup)
+    await coordinator.run_setup(force_setup=run_setup, wizard_mode=wizard_mode)
 
 
 async def setup_agent(agent: Optional[Any], state_manager: StateManager) -> None:

tunacode/tools/glob.py

@@ -14,11 +14,10 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set, Union
 
-import defusedxml.ElementTree as ET
-
 from tunacode.core.code_index import CodeIndex
 from tunacode.exceptions import ToolExecutionError
 from tunacode.tools.base import BaseTool
+from tunacode.tools.xml_helper import load_parameters_schema_from_xml, load_prompt_from_xml
 
 # Configuration
 MAX_RESULTS = 5000  # Maximum files to return
@@ -70,17 +69,10 @@ class GlobTool(BaseTool):
         Returns:
             str: The loaded prompt from XML or a default prompt
         """
-        try:
-            # Load prompt from XML file
-            prompt_file = Path(__file__).parent / "prompts" / "glob_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:
-            pass  # Fall through to default
+        # Try to load from XML helper
+        prompt = load_prompt_from_xml("glob")
+        if prompt:
+            return prompt
 
         # Fallback to default prompt
         return """Fast file pattern matching tool
@@ -92,39 +84,10 @@ class GlobTool(BaseTool):
     @lru_cache(maxsize=1)
     def _get_parameters_schema(self) -> Dict[str, Any]:
         """Get the parameters schema for the glob tool."""
-        # Try to load from XML first
-        try:
-            prompt_file = Path(__file__).parent / "prompts" / "glob_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 "",
-                            }
-
-                            schema["properties"][name] = prop
-                            if required:
-                                required_fields.append(name)
-
-                    schema["required"] = required_fields
-                    return schema
-        except Exception:
-            pass  # Fall through to hardcoded schema
+        # Try to load from XML helper
+        schema = load_parameters_schema_from_xml("glob")
+        if schema:
+            return schema
 
         # Fallback to hardcoded schema
         return {