API Reference

This document provides technical reference information for Crust Shell’s modules, functions, and internal APIs.

📁 Project Structure

crust/
├── src/                    # Main source code
│   ├── main.py            # Main shell loop and interface
│   ├── base.py            # Core console and UI components
│   ├── config_find.py     # Configuration directory discovery
│   ├── capk.py            # Package availability checker
│   ├── troubleshooting.py # AI-powered troubleshooting
│   └── custom_commands.py # Custom startup commands
├── .crust/                # Configuration directory
│   ├── aliases.py         # Command aliases configuration
│   ├── cmds.py           # System commands configuration
│   └── cohere-api-key.txt # AI API key
└── docs/                  # Documentation

🔧 Core Modules

main.py

The main module contains the interactive shell loop and command processing logic.

Key Functions

Shell Loop

while True:
    # Main interactive loop
    # Handles prompt display, input processing, and command execution

Prompt Generation

Built-in Command Handlers

AI Integration

Question Processing

# AI chat history management
chat_history = [{"role": "SYSTEM", "message": system_prompt}]

# Command execution detection
if line.startswith(".execute-command"):
    command = line.replace(".execute-command", "").strip()
    # User confirmation and execution logic

File Operations

# File editing capability
elif line.startswith(".edit-file"):
    filepath = line.replace(".edit-file", "").strip()
    # File modification with user confirmation

# File reading capability  
elif line.startswith(".read-file"):
    filepath = line.replace(".read-file", "").strip()
    # File content injection into AI conversation

base.py

Core UI components and console setup.

import rich
from rich.console import Console
from rich.table import Table

console = Console()

Exports

config_find.py

Configuration directory discovery utilities.

find_crust_folder()

Searches for the .crust configuration directory.

def find_crust_folder():
    """
    Searches upward from current directory for .crust folder.
    
    Returns:
        str: Path to .crust directory if found
        None: If no .crust directory found
        
    Search Order:
        1. Current working directory
        2. Parent directories (recursive up to root)
    """
    current_dir = os.getcwd()
    
    while True:
        candidate = os.path.join(current_dir, '.crust')
        if os.path.isdir(candidate):
            return candidate
            
        parent_dir = os.path.dirname(current_dir)
        if parent_dir == current_dir:  # Reached root
            return None
            
        current_dir = parent_dir

capk.py

Multi-platform package availability checker.

Package Manager Support

Supported Repositories

Core Functions

search(pkg)

def search(pkg):
    """
    Search for package across all supported repositories.
    
    Args:
        pkg (str): Package name to search for
        
    Output:
        Prints formatted results showing availability across platforms
    """

check_all(pkg)

def check_all(pkg):
    """
    Check package availability across all repositories.
    
    Args:
        pkg (str): Package name to check
        
    Returns:
        dict: Repository name -> availability (bool) mapping
    """

Individual Checker Functions

def check_pypi(pkg):
    """Check PyPI availability via API"""
    return requests.get(f"https://pypi.org/pypi/{pkg}/json").status_code == 200

def check_aur(pkg):
    """Check AUR availability via RPC API"""
    r = requests.get(f"https://aur.archlinux.org/rpc/?v=5&type=info&arg[]={pkg}")
    return r.ok and r.json().get("resultcount", 0) > 0
    
# Additional checker functions for each platform...

troubleshooting.py

AI-powered system troubleshooting interface.

Core Functions

run()

def run():
    """
    Main troubleshooting interface loop.
    
    Features:
    - Interactive problem description
    - AI-powered diagnosis
    - Command execution with user confirmation
    - File reading and editing capabilities
    - Persistent conversation history
    """

load_api_key()

def load_api_key():
    """
    Load Cohere API key from configuration.
    
    Returns:
        str: API key content
        
    Raises:
        SystemExit: If API key file not found
    """

build_system_prompt()

def build_system_prompt():
    """
    Build system prompt for AI troubleshooting context.
    
    Returns:
        dict: Formatted system message with troubleshooting instructions
    """

AI Command Processing

The troubleshooting module supports the same AI command syntax as the main shell:

custom_commands.py

Extensibility interface for custom startup commands.

def main():
    """
    Custom commands executed on shell startup.
    
    This function is called during Crust Shell initialization.
    Use for:
    - Environment setup
    - Custom notifications
    - System checks
    - Variable initialization
    """
    pass  # Default implementation

🔧 Configuration System

Dynamic Import System

Both main.py and aliases.py use dynamic imports for configuration loading:

import importlib.util
from pathlib import Path

# Dynamic module loading
spec = importlib.util.spec_from_file_location("module_name", file_path)
module = importlib.util.module_from_spec(spec)
sys.modules["module_name"] = module
spec.loader.exec_module(module)

This system ensures that configuration files are loaded from the correct location regardless of the current working directory.

Configuration File Structure

aliases.py Structure

# Required imports for dynamic cmds.py loading
import importlib.util
import sys
from pathlib import Path

# Dynamic cmds import
current_dir = Path(__file__).parent
cmds_path = current_dir / "cmds.py"
spec = importlib.util.spec_from_file_location("cmds", cmds_path)
cmds = importlib.util.module_from_spec(spec)
sys.modules["cmds"] = cmds
spec.loader.exec_module(cmds)

# Alias definitions
alias_name = "command_string"

cmds.py Structure

# Simple variable assignments
editor = "editor_command"
update_system = "update_command"
installpkg = "install_command"
# ... additional command configurations

🎨 UI Components

Rich Integration

Crust Shell extensively uses the Rich library for enhanced terminal output:

Table Creation

from rich.table import Table

table = Table(title="Table Title", show_lines=True)
table.add_column("Column Name", style="color")
table.add_row("data1", "data2")
base.console.print(table)

Colored Output

base.console.print("Message", style="color_style")
base.console.print("[color]Message[/color]")

Available Styles

🔌 Extension Points

Adding New Built-in Commands

Add command handling in the main loop of main.py:

elif prompt == "new_command":
    # Your command logic here
    base.console.print("Command executed", style="green")

Adding New Package Managers

Add to capk.py:

def check_new_manager(pkg):
    """Check new package manager"""
    # Implementation
    return True/False

# Add to checkers dictionary in check_all()
checkers = {
    # ... existing checkers
    "New Manager": check_new_manager,
}

Custom AI Commands

Extend AI command processing in main.py and troubleshooting.py:

elif line.startswith(".custom-command"):
    # Custom AI command logic
    parameter = line.replace(".custom-command", "").strip()
    # Process custom command

🔍 Error Handling

Exception Handling Patterns

Graceful Command Failure

try:
    subprocess.run(command, shell=True)
except KeyboardInterrupt:
    base.console.print("Command interrupted", style="bold red")
except Exception as e:
    base.console.print(f"Error: {e}", style="bold red")

Network Request Handling

try:
    response = requests.get(url)
    return response.status_code == 200
except Exception as e:
    print(f"Error: {e}")
    return False

Main Loop Error Handling

The main shell loop includes comprehensive error handling:

try:
    # Command processing
except KeyboardInterrupt:
    # Graceful exit
    break
except Exception as e:
    # Log error and continue
    base.console.print(f"Error occurred: {e}", style="bold red")
    continue

🧪 Testing Considerations

Testable Components

Mock Points

This API reference covers the technical internals of Crust Shell. For usage information, see the User Guide, and for contributing guidelines, check the Contributing Guide.