glaip-sdk 0.0.15__py3-none-any.whl → 0.0.17__py3-none-any.whl

glaip_sdk/cli/commands/tools.py

@@ -11,7 +11,6 @@ from typing import Any
 
 import click
 from rich.console import Console
-from rich.text import Text
 
 from glaip_sdk.cli.context import detect_export_format, get_ctx_value, output_flags
 from glaip_sdk.cli.display import (
@@ -33,6 +32,7 @@ from glaip_sdk.cli.io import (
     load_resource_from_file_with_validation as load_resource_from_file,
 )
 from glaip_sdk.cli.resolution import resolve_resource_reference
+from glaip_sdk.cli.rich_helpers import markup_text, print_markup
 from glaip_sdk.cli.utils import (
     coerce_to_row,
     get_client,
@@ -349,11 +349,13 @@ def get(ctx: Any, tool_ref: str, select: int | None, export: str | None) -> None
                 ):
                     tool = client.get_tool_by_id(tool.id)
             except Exception as e:
-                console.print(
-                    Text(f"[yellow]⚠️  Could not fetch full tool details: {e}[/yellow]")
+                print_markup(
+                    f"[yellow]⚠️  Could not fetch full tool details: {e}[/yellow]",
+                    console=console,
                 )
-                console.print(
-                    Text("[yellow]⚠️  Proceeding with available data[/yellow]")
+                print_markup(
+                    "[yellow]⚠️  Proceeding with available data[/yellow]",
+                    console=console,
                 )
 
             with spinner_context(
@@ -362,10 +364,9 @@ def get(ctx: Any, tool_ref: str, select: int | None, export: str | None) -> None
                 console_override=console,
             ):
                 export_resource_to_file(tool, export_path, detected_format)
-            console.print(
-                Text(
-                    f"[green]✅ Complete tool configuration exported to: {export_path} (format: {detected_format})[/green]"
-                )
+            print_markup(
+                f"[green]✅ Complete tool configuration exported to: {export_path} (format: {detected_format})[/green]",
+                console=console,
             )
 
         # Try to fetch raw API data first to preserve ALL fields
@@ -473,7 +474,8 @@ def update(
                     tool.id, file, framework=tool.framework
                 )
             handle_rich_output(
-                ctx, Text(f"[green]✓[/green] Tool code updated from {file}")
+                ctx,
+                markup_text(f"[green]✓[/green] Tool code updated from {file}"),
             )
         elif update_data:
             # Update metadata only (native tools only)
@@ -487,9 +489,13 @@ def update(
                 console_override=console,
             ):
                 updated_tool = tool.update(**update_data)
-            handle_rich_output(ctx, Text("[green]✓[/green] Tool metadata updated"))
+            handle_rich_output(
+                ctx, markup_text("[green]✓[/green] Tool metadata updated")
+            )
         else:
-            handle_rich_output(ctx, Text("[yellow]No updates specified[/yellow]"))
+            handle_rich_output(
+                ctx, markup_text("[yellow]No updates specified[/yellow]")
+            )
             return
 
         handle_json_output(ctx, updated_tool.model_dump())
@@ -574,5 +580,5 @@ def script(ctx: Any, tool_id: str) -> None:
     except Exception as e:
         handle_json_output(ctx, error=e)
         if get_ctx_value(ctx, "view") != "json":
-            console.print(Text(f"[red]Error getting tool script: {e}[/red]"))
+            print_markup(f"[red]Error getting tool script: {e}[/red]", console=console)
         raise click.ClickException(str(e))

glaip_sdk/cli/config.py

@@ -0,0 +1,42 @@
+"""Configuration management utilities.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+CONFIG_DIR = Path.home() / ".aip"
+CONFIG_FILE = CONFIG_DIR / "config.yaml"
+
+
+def load_config() -> dict[str, Any]:
+    """Load configuration from file."""
+    if not CONFIG_FILE.exists():
+        return {}
+
+    try:
+        with open(CONFIG_FILE) as f:
+            return yaml.safe_load(f) or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def save_config(config: dict[str, Any]) -> None:
+    """Save configuration to file."""
+    CONFIG_DIR.mkdir(exist_ok=True)
+
+    with open(CONFIG_FILE, "w") as f:
+        yaml.dump(config, f, default_flow_style=False)
+
+    # Set secure file permissions
+    try:
+        os.chmod(CONFIG_FILE, 0o600)
+    except (
+        OSError
+    ):  # pragma: no cover - permission errors are expected in some environments
+        pass

glaip_sdk/cli/display.py

@@ -15,6 +15,8 @@ from rich.console import Console
 from rich.panel import Panel
 from rich.text import Text
 
+from glaip_sdk.cli.rich_helpers import markup_text, print_markup
+from glaip_sdk.cli.utils import command_hint
 from glaip_sdk.rich_components import AIPPanel
 
 console = Console()
@@ -60,7 +62,7 @@ def display_update_success(resource_type: str, resource_name: str) -> Text:
     Returns:
         Rich Text object for display
     """
-    return Text(
+    return markup_text(
         f"[green]✅ {resource_type} '{resource_name}' updated successfully[/green]"
     )
 
@@ -75,7 +77,7 @@ def display_deletion_success(resource_type: str, resource_name: str) -> Text:
     Returns:
         Rich Text object for display
     """
-    return Text(
+    return markup_text(
         f"[green]✅ {resource_type} '{resource_name}' deleted successfully[/green]"
     )
 
@@ -88,8 +90,8 @@ def display_api_error(error: Exception, operation: str = "operation") -> None:
         operation: Description of the operation that failed
     """
     error_type = type(error).__name__
-    console.print(Text(f"[red]Error during {operation}: {error}[/red]"))
-    console.print(Text(f"[dim]Error type: {error_type}[/dim]"))
+    print_markup(f"[red]Error during {operation}: {error}[/red]", console=console)
+    print_markup(f"[dim]Error type: {error_type}[/dim]", console=console)
 
 
 def print_api_error(e: Exception) -> None:
@@ -102,30 +104,80 @@ def print_api_error(e: Exception) -> None:
         - Extracts status_code, error_type, and payload from APIError exceptions
         - Provides consistent error reporting across CLI commands
         - Handles both JSON and Rich output formats
+        - Special handling for validation errors with detailed field-level errors
     """
-    if hasattr(e, "__dict__"):  # Check if it's an APIError-like object
-        error_info = {
-            "error": str(e),
-            "status_code": getattr(e, "status_code", None),
-            "error_type": getattr(e, "error_type", None),
-            "details": getattr(e, "payload", None),
-        }
-
-        # Filter out None values
-        error_info = {k: v for k, v in error_info.items() if v is not None}
-
-        # For JSON view, just return the structured error
-        # (CLI commands handle the JSON formatting)
-        if hasattr(e, "status_code"):
-            console.print(f"[red]API Error: {e}[/red]")
-            if hasattr(e, "status_code"):
-                console.print(f"[yellow]Status: {e.status_code}[/yellow]")
-            if hasattr(e, "payload"):
-                console.print(f"[yellow]Details: {e.payload}[/yellow]")
+    if not hasattr(e, "__dict__"):
+        console.print(f"[red]Error: {e}[/red]")
+        return
+
+    if not hasattr(e, "status_code"):
+        console.print(f"[red]Error: {e}[/red]")
+        return
+
+    console.print(f"[red]API Error: {e}[/red]")
+    status_code = getattr(e, "status_code", None)
+    if status_code is not None:
+        console.print(f"[yellow]Status: {status_code}[/yellow]")
+
+    payload = getattr(e, "payload", _MISSING)
+    if payload is _MISSING:
+        return
+
+    if payload:
+        if not _print_structured_payload(payload):
+            console.print(f"[yellow]Details: {payload}[/yellow]")
+    else:
+        console.print(f"[yellow]Details: {payload}[/yellow]")
+
+
+def _print_structured_payload(payload: Any) -> bool:
+    """Print structured payloads with enhanced formatting. Returns True if handled."""
+    if not isinstance(payload, dict):
+        return False
+
+    if "detail" in payload and _print_validation_details(payload["detail"]):
+        return True
+
+    if "details" in payload and _print_details_field(payload["details"]):
+        return True
+
+    return False
+
+
+def _print_validation_details(detail: Any) -> bool:
+    """Render FastAPI-style validation errors."""
+    if not isinstance(detail, list) or not detail:
+        return False
+
+    console.print("[red]Validation Errors:[/red]")
+    for error in detail:
+        if isinstance(error, dict):
+            loc = " -> ".join(str(x) for x in error.get("loc", []))
+            msg = error.get("msg", "Unknown error")
+            error_type = error.get("type", "unknown")
+            location = loc if loc else "field"
+            console.print(f"  [yellow]• {location}:[/yellow] {msg}")
+            if error_type != "unknown":
+                console.print(f"    [dim]({error_type})[/dim]")
         else:
-            console.print(f"[red]Error: {e}[/red]")
+            console.print(f"  [yellow]•[/yellow] {error}")
+    return True
+
+
+def _print_details_field(details: Any) -> bool:
+    """Render custom error details from API payloads."""
+    if not details:
+        return False
+
+    console.print("[red]Error Details:[/red]")
+    if isinstance(details, str):
+        console.print(f"  [yellow]•[/yellow] {details}")
+    elif isinstance(details, list):
+        for detail in details:
+            console.print(f"  [yellow]•[/yellow] {detail}")
     else:
-        console.print(f"[red]Error: {e}[/red]")
+        console.print(f"  [yellow]•[/yellow] {details}")
+    return True
 
 
 _MISSING = object()
@@ -133,7 +185,6 @@ _MISSING = object()
 
 def build_resource_result_data(resource: Any, fields: list[str]) -> dict[str, Any]:
     """Return a normalized mapping of ``fields`` extracted from ``resource``."""
-
     result: dict[str, Any] = {}
     for field in fields:
         try:
@@ -244,14 +295,30 @@ def display_confirmation_prompt(resource_type: str, resource_name: str) -> bool:
 
 def display_agent_run_suggestions(agent: Any) -> Panel:
     """Return a panel with post-creation suggestions for an agent."""
+    agent_id = getattr(agent, "id", "")
+    agent_name = getattr(agent, "name", "")
+    run_hint_id = command_hint(
+        f'agents run {agent_id} "Your message here"',
+        slash_command=None,
+    )
+    run_hint_name = command_hint(
+        f'agents run "{agent_name}" "Your message here"',
+        slash_command=None,
+    )
+
+    cli_section = ""
+    if run_hint_id and run_hint_name:
+        cli_section = (
+            "📋 Prefer the CLI instead?\n"
+            f"   [green]{run_hint_id}[/green]\n"
+            f"   [green]{run_hint_name}[/green]\n\n"
+        )
 
     return AIPPanel(
         f"[bold blue]💡 Next Steps:[/bold blue]\n\n"
-        f"🚀 Start chatting with [bold]{agent.name}[/bold] right here:\n"
+        f"🚀 Start chatting with [bold]{agent_name}[/bold] right here:\n"
         f"   Type your message below and press Enter to run it immediately.\n\n"
-        f"📋 Prefer the CLI instead?\n"
-        f'   [green]aip agents run {agent.id} "Your message here"[/green]\n'
-        f'   [green]aip agents run "{agent.name}" "Your message here"[/green]\n\n'
+        f"{cli_section}"
         f"🔧 Available options:\n"
         f"   [dim]--chat-history[/dim]  Include previous conversation\n"
         f"   [dim]--file[/dim]          Attach files\n"

glaip_sdk/cli/main.py

@@ -19,11 +19,11 @@ from glaip_sdk.cli.commands.agents import agents_group
 from glaip_sdk.cli.commands.configure import (
     config_group,
     configure_command,
-    load_config,
 )
 from glaip_sdk.cli.commands.mcps import mcps_group
 from glaip_sdk.cli.commands.models import models_group
 from glaip_sdk.cli.commands.tools import tools_group
+from glaip_sdk.cli.config import load_config
 from glaip_sdk.cli.update_notifier import maybe_notify_update
 from glaip_sdk.cli.utils import spinner_context, update_spinner
 from glaip_sdk.config.constants import (
@@ -73,7 +73,6 @@ def main(
         aip tools create my_tool.py      # Create a new tool
         aip agents run my-agent "Hello world"  # Run an agent
     """
-
     # Store configuration in context
     ctx.ensure_object(dict)
     ctx.obj["api_url"] = api_url
@@ -116,7 +115,6 @@ main.add_command(configure_command)
 
 def _should_launch_slash(ctx: click.Context) -> bool:
     """Determine whether to open the command palette automatically."""
-
     ctx_obj = ctx.obj or {}
     if not bool(ctx_obj.get("tty", True)):
         return False
@@ -127,6 +125,137 @@ def _should_launch_slash(ctx: click.Context) -> bool:
     return True
 
 
+def _load_and_merge_config(ctx: click.Context) -> dict:
+    """Load configuration from multiple sources and merge them."""
+    # Load config from file and merge with context
+    file_config = load_config()
+    context_config = ctx.obj or {}
+
+    # Load environment variables (middle priority)
+    env_config = {}
+    if os.getenv("AIP_API_URL"):
+        env_config["api_url"] = os.getenv("AIP_API_URL")
+    if os.getenv("AIP_API_KEY"):
+        env_config["api_key"] = os.getenv("AIP_API_KEY")
+
+    # Filter out None values from context config to avoid overriding other configs
+    filtered_context = {k: v for k, v in context_config.items() if v is not None}
+
+    # Merge configs: file (low) -> env (mid) -> CLI args (high)
+    return {**file_config, **env_config, **filtered_context}
+
+
+def _validate_config_and_show_error(config: dict, console: Console) -> None:
+    """Validate configuration and show error if incomplete."""
+    if not config.get("api_url") or not config.get("api_key"):
+        console.print(
+            AIPPanel(
+                "[bold red]❌ Configuration incomplete[/bold red]\n\n"
+                f"🔍 Current config:\n"
+                f"   • API URL: {config.get('api_url', 'Not set')}\n"
+                f"   • API Key: {'***' + config.get('api_key', '')[-4:] if config.get('api_key') else 'Not set'}\n\n"
+                f"💡 To fix this:\n"
+                f"   • Run 'aip configure' to set up credentials\n"
+                f"   • Or run 'aip config list' to see current config",
+                title="❌ Configuration Error",
+                border_style="red",
+            )
+        )
+        console.print(
+            f"\n[bold green]✅ AIP - Ready[/bold green] (SDK v{_SDK_VERSION}) - Configure to connect"
+        )
+        sys.exit(1)
+
+
+def _create_and_test_client(config: dict, console: Console) -> Client:
+    """Create client and test connection by fetching resources."""
+    # Try to create client
+    client = Client(
+        api_url=config["api_url"],
+        api_key=config["api_key"],
+        timeout=config.get("timeout", 30.0),
+    )
+
+    # Test connection by listing resources
+    try:
+        with spinner_context(
+            None,  # We'll pass ctx later
+            "[bold blue]Checking GL AIP status…[/bold blue]",
+            console_override=console,
+            spinner_style="cyan",
+        ) as status_indicator:
+            update_spinner(status_indicator, "[bold blue]Fetching agents…[/bold blue]")
+            agents = client.list_agents()
+
+            update_spinner(status_indicator, "[bold blue]Fetching tools…[/bold blue]")
+            tools = client.list_tools()
+
+            update_spinner(status_indicator, "[bold blue]Fetching MCPs…[/bold blue]")
+            mcps = client.list_mcps()
+
+        # Create status table
+        table = AIPTable(title="🔗 GL AIP Status")
+        table.add_column("Resource", style="cyan", width=15)
+        table.add_column("Count", style="green", width=10)
+        table.add_column("Status", style="green", width=15)
+
+        table.add_row("Agents", str(len(agents)), "✅ Available")
+        table.add_row("Tools", str(len(tools)), "✅ Available")
+        table.add_row("MCPs", str(len(mcps)), "✅ Available")
+
+        console.print(
+            AIPPanel(
+                f"[bold green]✅ Connected to GL AIP[/bold green]\n"
+                f"🔗 API URL: {client.api_url}\n"
+                f"🤖 Agent Run Timeout: {DEFAULT_AGENT_RUN_TIMEOUT}s",
+                title="🚀 Connection Status",
+                border_style="green",
+            )
+        )
+
+        console.print(table)
+
+    except Exception as e:
+        # Show AIP Ready status even if connection fails
+        console.print(
+            f"\n[bold green]✅ AIP - Ready[/bold green] (SDK v{_SDK_VERSION})"
+        )
+
+        console.print(
+            AIPPanel(
+                f"[bold yellow]⚠️  Connection established but API call failed[/bold yellow]\n"
+                f"🔗 API URL: {client.api_url}\n"
+                f"❌ Error: {e}\n\n"
+                f"💡 This usually means:\n"
+                f"   • Network connectivity issues\n"
+                f"   • API permissions problems\n"
+                f"   • Backend service issues",
+                title="⚠️  Partial Connection",
+                border_style="yellow",
+            )
+        )
+
+    return client
+
+
+def _handle_connection_error(config: dict, console: Console, error: Exception) -> None:
+    """Handle connection errors and show troubleshooting information."""
+    console.print(
+        AIPPanel(
+            f"[bold red]❌ Connection failed[/bold red]\n\n"
+            f"🔍 Error: {error}\n\n"
+            f"💡 Troubleshooting steps:\n"
+            f"   • Verify your API URL and key are correct\n"
+            f"   • Check network connectivity to {config.get('api_url', 'your API')}\n"
+            f"   • Run 'aip configure' to update credentials\n"
+            f"   • Run 'aip config list' to check configuration",
+            title="❌ Connection Error",
+            border_style="red",
+        )
+    )
+    sys.exit(1)
+
+
 @main.command()
 @click.pass_context
 def status(ctx: Any) -> None:
@@ -146,132 +275,20 @@ def status(ctx: Any) -> None:
             f"\n[bold green]✅ AIP - Ready[/bold green] (SDK v{_SDK_VERSION})"
         )
 
-        # Load config from file and merge with context
-        file_config = load_config()
-        context_config = ctx.obj or {}
-
-        # Load environment variables (middle priority)
-
-        env_config = {}
-        if os.getenv("AIP_API_URL"):
-            env_config["api_url"] = os.getenv("AIP_API_URL")
-        if os.getenv("AIP_API_KEY"):
-            env_config["api_key"] = os.getenv("AIP_API_KEY")
-
-        # Filter out None values from context config to avoid overriding other configs
-        filtered_context = {k: v for k, v in context_config.items() if v is not None}
-
-        # Merge configs: file (low) -> env (mid) -> CLI args (high)
-        config = {**file_config, **env_config, **filtered_context}
-
-        if not config.get("api_url") or not config.get("api_key"):
-            console.print(
-                AIPPanel(
-                    "[bold red]❌ Configuration incomplete[/bold red]\n\n"
-                    f"🔍 Current config:\n"
-                    f"   • API URL: {config.get('api_url', 'Not set')}\n"
-                    f"   • API Key: {'***' + config.get('api_key', '')[-4:] if config.get('api_key') else 'Not set'}\n\n"
-                    f"💡 To fix this:\n"
-                    f"   • Run 'aip configure' to set up credentials\n"
-                    f"   • Or run 'aip config list' to see current config",
-                    title="❌ Configuration Error",
-                    border_style="red",
-                )
-            )
-            console.print(
-                f"\n[bold green]✅ AIP - Ready[/bold green] (SDK v{_SDK_VERSION}) - Configure to connect"
-            )
-            sys.exit(1)
-
-        # Try to create client
-        client = Client(
-            api_url=config["api_url"],
-            api_key=config["api_key"],
-            timeout=config.get("timeout", 30.0),
-        )
-
-        # Test connection by listing resources
-        try:
-            with spinner_context(
-                ctx,
-                "[bold blue]Checking GL AIP status…[/bold blue]",
-                console_override=console,
-                spinner_style="cyan",
-            ) as status_indicator:
-                update_spinner(
-                    status_indicator, "[bold blue]Fetching agents…[/bold blue]"
-                )
-                agents = client.list_agents()
+        # Load and merge configuration
+        config = _load_and_merge_config(ctx)
 
-                update_spinner(
-                    status_indicator, "[bold blue]Fetching tools…[/bold blue]"
-                )
-                tools = client.list_tools()
-
-                update_spinner(
-                    status_indicator, "[bold blue]Fetching MCPs…[/bold blue]"
-                )
-                mcps = client.list_mcps()
-
-            # Create status table
-            table = AIPTable(title="🔗 GL AIP Status")
-            table.add_column("Resource", style="cyan", width=15)
-            table.add_column("Count", style="green", width=10)
-            table.add_column("Status", style="green", width=15)
-
-            table.add_row("Agents", str(len(agents)), "✅ Available")
-            table.add_row("Tools", str(len(tools)), "✅ Available")
-            table.add_row("MCPs", str(len(mcps)), "✅ Available")
-
-            console.print(
-                AIPPanel(
-                    f"[bold green]✅ Connected to GL AIP[/bold green]\n"
-                    f"🔗 API URL: {client.api_url}\n"
-                    f"🤖 Agent Run Timeout: {DEFAULT_AGENT_RUN_TIMEOUT}s",
-                    title="🚀 Connection Status",
-                    border_style="green",
-                )
-            )
-
-            console.print(table)
-
-        except Exception as e:
-            # Show AIP Ready status even if connection fails
-            console.print(
-                f"\n[bold green]✅ AIP - Ready[/bold green] (SDK v{_SDK_VERSION})"
-            )
-
-            console.print(
-                AIPPanel(
-                    f"[bold yellow]⚠️  Connection established but API call failed[/bold yellow]\n"
-                    f"🔗 API URL: {client.api_url}\n"
-                    f"❌ Error: {e}\n\n"
-                    f"💡 This usually means:\n"
-                    f"   • Network connectivity issues\n"
-                    f"   • API permissions problems\n"
-                    f"   • Backend service issues",
-                    title="⚠️  Partial Connection",
-                    border_style="yellow",
-                )
-            )
+        # Validate configuration
+        _validate_config_and_show_error(config, console)
 
+        # Create and test client connection
+        client = _create_and_test_client(config, console)
         client.close()
 
     except Exception as e:
-        console.print(
-            AIPPanel(
-                f"[bold red]❌ Connection failed[/bold red]\n\n"
-                f"🔍 Error: {e}\n\n"
-                f"💡 Troubleshooting steps:\n"
-                f"   • Run 'aip config list' to check configuration\n"
-                f"   • Run 'aip configure' to update credentials\n"
-                f"   • Verify your API URL and key are correct\n"
-                f"   • Check network connectivity to {config.get('api_url', 'your API')}",
-                title="❌ Connection Error",
-                border_style="red",
-            )
-        )
-        sys.exit(1)
+        # Handle any unexpected errors during the process
+        console = Console()
+        _handle_connection_error(config if "config" in locals() else {}, console, e)
 
 
 @main.command()

glaip_sdk/cli/mcp_validators.py

@@ -15,7 +15,7 @@ import click
 
 
 def format_validation_error(prefix: str, detail: str | None = None) -> str:
-    """Format a validation error message with optional detail.
+    r"""Format a validation error message with optional detail.
 
     Args:
         prefix: Main error message
@@ -26,7 +26,7 @@ def format_validation_error(prefix: str, detail: str | None = None) -> str:
 
     Examples:
         >>> format_validation_error("Invalid config", "Missing 'url' field")
-        "Invalid config\\nMissing 'url' field"
+        "Invalid config\nMissing 'url' field"
     """
     parts = [prefix]
     if detail:

glaip_sdk/cli/pager.py

@@ -57,8 +57,9 @@ def _get_console() -> Console:
 
 
 def _prepare_pager_env(clear_on_exit: bool = True) -> None:
-    """
-    Configure LESS flags for a predictable, high-quality UX:
+    """Configure LESS flags for a predictable, high-quality UX.
+
+    Sets sensible defaults for the system pager:
       -R  : pass ANSI color escapes
       -S  : chop long lines (horizontal scroll with ←/→)
     (No -F, no -X) so we open a full-screen pager and clear on exit.

glaip_sdk/cli/parsers/json_input.py

@@ -17,7 +17,7 @@ import click
 def _format_file_error(
     prefix: str, file_path_str: str, resolved_path: Path, *, detail: str | None = None
 ) -> str:
-    """Format a file-related error message with path context.
+    r"""Format a file-related error message with path context.
 
     Args:
         prefix: Main error message
@@ -31,7 +31,7 @@ def _format_file_error(
     Examples:
         >>> from pathlib import Path
         >>> _format_file_error("File not found", "config.json", Path("/abs/config.json"))
-        'File not found: config.json\\nResolved path: /abs/config.json'
+        'File not found: config.json\nResolved path: /abs/config.json'
     """
     parts = [f"{prefix}: {file_path_str}", f"Resolved path: {resolved_path}"]
     if detail: