Aliasing System Architecture¶

This document explains how Angreal's aliasing system works internally to enable white-labeling and custom command names.

Overview¶

The aliasing system creates executable wrapper scripts that redirect to angreal while maintaining the illusion of a separate command. When you run angreal alias create mycompany-tool, it generates a script in ~/.local/bin/mycompany-tool that imports and calls angreal.

Core Components¶

Wrapper Script Generation¶

Platform-specific executable scripts are created in ~/.local/bin/:

Unix/Linux/macOS:

#!/usr/bin/env python3
# ANGREAL_ALIAS: alias-name
import sys
try:
    import angreal
    angreal.main()
except ImportError:
    print(f"Error: angreal not installed. Remove alias: rm {script_path}", file=sys.stderr)
    sys.exit(1)

Windows:

@echo off
REM ANGREAL_ALIAS: alias-name
python -m angreal %*

Registry Management¶

A JSON registry at ~/.angrealrc/aliases.json tracks registered aliases:

["mycompany-tool", "project-cli", "devops-helper"]

Implementation Details¶

Cross-Platform Handling¶

The Rust code generates platform-appropriate scripts:

#[cfg(unix)]
{
    // Create Python script with shebang
    // Set executable permissions (755)
}

#[cfg(windows)]
{
    // Create .bat file
    // No permission changes needed
}

Argument Preservation¶

Wrapper scripts preserve all command-line arguments: - Unix: sys.argv contains alias name and all arguments - Windows: %* passes all arguments unchanged

From angreal's perspective, sys.argv[0] contains the alias name instead of "angreal", so help messages show the custom command name.

Design Decisions¶

Why Wrapper Scripts Instead of Symlinks?¶

Symlinks were rejected because: 1. Shell completion wouldn't work properly 2. Error messages would show "angreal" instead of custom name 3. Cross-platform complexity (Windows symlinks)

Why ~/.local/bin?¶

No sudo required (user-level installation)
Standard XDG convention
Per-user isolation
Easy cleanup

Why Python Scripts Instead of Shell Scripts?¶

Better error handling for missing angreal
Cross-platform compatibility
Direct access to angreal module

Security¶

Conflict prevention: Checks for existing commands before creation
User-only: Uses ~/.local/bin and ~/.angrealrc (no system modifications)
Minimal permissions: 755 on Unix
Atomic registry updates: Prevents corruption during concurrent access

Error Handling¶

Missing angreal: Wrapper script provides clear error message and removal instructions

Registry corruption: System recovers by resetting to empty registry

Path conflicts: Registration fails with helpful error message

The aliasing system provides transparent command redirection while maintaining full angreal functionality and shell integration.