LHI Bash Utilities

Professional JavaScript-style bash module system for reusable utility functions across LHI projects.

Overview

The LHI Bash Utilities module provides a centralized location for reusable bash scripts with JavaScript-style module loading. This system eliminates code duplication and provides clear function traceability for both developers and AI agents.

Features

• JavaScript-style Loading: lhi-bash-loader "module_name"
• Full Function Traceability: module_name function_name args
• Namespace Consistency: Filename matches main function name
• Cross-platform Compatibility: Works on macOS and Linux
• Module Management: Load, unload, list, and status tracking
• AI Agent Friendly: Clear origins and dependencies

Module Structure

lhi_modules/lhi_git_projects/LifeHackInnovationsLLC/lhi_node_modules/lhi_bash_utilities/
├── lhi_module.json              # Module metadata
├── bin/lhi-bash-loader.sh       # JavaScript-style loader
├── lib/                         # Utility modules
│   ├── terminal_box_utils.sh
│   ├── cross_platform_daemon_manager.sh
│   ├── gitignore_to_find_excludes.sh
│   └── gitignore_to_fswatch_excludes.sh
├── demo/demo_module_system.sh   # Working demonstration
├── README.md                    # This file
├── PLANNING.md                  # Strategic planning
└── TASK.md                      # Task tracking

Quick Start

1. Load the Module System

# Load the module system
source /Users/patrickwatsonlhi/lhi_scripts/lhi_modules/lhi_git_projects/LifeHackInnovationsLLC/lhi_node_modules/lhi_bash_utilities/bin/lhi-bash-loader.sh

2. Import Modules with JavaScript-style Loading

# Load specific modules
lhi-bash-loader "terminal_box_utils"
lhi-bash-loader "gitignore_to_find_excludes"
lhi-bash-loader "cross_platform_daemon_manager"

3. Use with Full Function Traceability

# Terminal utilities
terminal_box_utils create_single_box "My Title" "Content here"

# GitIgnore utilities
exclude_params=($(gitignore_to_find_excludes generate ".gitignore" "/path/to/repo"))

# Daemon management
cross_platform_daemon_manager install "my-service" "/path/to/service.sh"

Available Modules

terminal_box_utils

Professional terminal box drawing with mathematical centering.

Functions:

• terminal_box_utils create_single_box "title" "content"
• terminal_box_utils create_double_box "title" "content"
• terminal_box_utils create_custom_box "title" "content" "width"

cross_platform_daemon_manager

Unified daemon management for macOS (launchd) and Linux (systemd).

Functions:

• cross_platform_daemon_manager install "name" "script_path"
• cross_platform_daemon_manager start "name"
• cross_platform_daemon_manager stop "name"
• cross_platform_daemon_manager status "name"

gitignore_to_find_excludes

Convert .gitignore patterns to find command exclude parameters.

Functions:

• gitignore_to_find_excludes generate "gitignore_file" "base_dir"
• gitignore_to_find_excludes combined "base_dir" "gitignore" "lhi_excludes"

gitignore_to_fswatch_excludes

Convert .gitignore patterns to fswatch regex exclude parameters.

Functions:

• gitignore_to_fswatch_excludes generate "gitignore_file"
• gitignore_to_fswatch_excludes combined "gitignore" "lhi_excludes"

Module Management Commands

# List available modules
lhi-bash-loader-list

# Show loaded modules
lhi-bash-loader-status

# Unload a module (for testing)
lhi-bash-loader-unload "module_name"

# Show help
lhi-bash-loader-help

Development Guidelines

Creating New Modules

1. Namespace Pattern: Filename must match main function name

   # File: lib/my_utility.sh
   # Must contain: my_utility() function

2. Function Structure: Use namespace prefixing for internal functions

   # Main function (matches filename)
   my_utility() {
       local action="$1"
       case "$action" in
           "main_action") _mu_internal_function "$@" ;;
           *) echo "my_utility: Unknown action '$action'" ;;
       esac
   }
      
   # Internal functions use namespace prefix
   _mu_internal_function() {
       # Implementation
   }

3. Documentation: Include clear usage examples and function descriptions

Module Guidelines

• Reusable: Functions should be generic enough for multiple projects
• Self-contained: Minimal external dependencies
• Well-documented: Clear parameter requirements and return values
• Error handling: Graceful failure with meaningful error messages
• Cross-platform: Works on macOS and Linux when possible

Integration with Existing Projects

Standard Integration Pattern

#!/bin/bash
# Load LHI Bash Utilities
source /Users/patrickwatsonlhi/lhi_scripts/lhi_modules/lhi_git_projects/LifeHackInnovationsLLC/lhi_node_modules/lhi_bash_utilities/bin/lhi-bash-loader.sh

# Import required modules
lhi-bash-loader "terminal_box_utils"
lhi-bash-loader "gitignore_to_find_excludes"

# Use utilities with full traceability
terminal_box_utils create_single_box "Status" "Processing files..."
exclude_params=($(gitignore_to_find_excludes generate ".gitignore" "$PWD"))

Migration from Copied Scripts

When migrating existing scripts to use the module system:

1. Move utility to bash utilities: Add reusable script to lib/
2. Update imports: Replace source with lhi-bash-loader
3. Update function calls: Use namespace pattern for traceability
4. Remove duplicate files: Clean up copied scripts

Benefits

For Developers

• No Code Duplication: Single source of truth for utilities
• Clear Dependencies: JavaScript-style imports show what's being used
• Easy Testing: Module system supports loading/unloading for tests
• Professional Organization: Industry-standard modular patterns

For AI Agents

• Function Traceability: Clear origins (terminal_box_utils create_single_box)
• Dependency Understanding: Explicit imports show requirements
• Consistent Patterns: Standard module loading across all projects
• Namespace Safety: No function name collisions

Examples

Complete Working Example

#!/bin/bash
# Example: File processor with professional utilities

# Load module system
source /Users/patrickwatsonlhi/lhi_scripts/lhi_modules/lhi_git_projects/LifeHackInnovationsLLC/lhi_node_modules/lhi_bash_utilities/bin/lhi-bash-loader.sh

# Import required modules
lhi-bash-loader "terminal_box_utils"
lhi-bash-loader "gitignore_to_find_excludes"

# Create status display
terminal_box_utils create_single_box "File Processor" "Starting file processing..."

# Get exclude parameters from .gitignore
exclude_params=($(gitignore_to_find_excludes generate ".gitignore" "$PWD"))

# Process files with proper exclusions
if [[ ${#exclude_params[@]} -gt 0 ]]; then
    find "$PWD" \( "${exclude_params[@]}" \) -prune -o -type f -name "*.txt" -print
else
    find "$PWD" -type f -name "*.txt" -print
fi

# Show completion
terminal_box_utils create_single_box "Complete" "File processing finished!"

Demo Script

Run the demonstration to see the module system in action:

/Users/patrickwatsonlhi/lhi_scripts/lhi_modules/lhi_git_projects/LifeHackInnovationsLLC/lhi_node_modules/lhi_bash_utilities/demo/demo_module_system.sh

Version Information

• Version: 1.0.0
• Form Factor: lhi_bash_utilities
• Type: bash_utilities
• Status: active

License

Copyright (c) 2025 LifeHack Innovations LLC. All rights reserved. MIT License - See individual module files for details.

Support

For issues or feature requests, please refer to the main LHI Scripts project documentation and task tracking system.