Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 83 additions & 11 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,22 +145,94 @@ Before submitting a PR, ensure:
- What testing was performed?
- Any breaking changes or migration notes?

**Template for PR descriptions**:
```
## Summary of Changes

Brief description of what this PR accomplishes.

## Problem Statement

Explanation of the issue or enhancement being addressed.

## Solution Details

Detailed explanation of the implementation:
- Which files were modified
- What functions or logic were added/changed
- Why this approach was chosen

## Testing Performed

Description of how the changes were tested:
- Manual testing steps
- Automated tests run
- Validation script results
- ShellCheck compliance

## Affected Components

List of project components that are affected by these changes:
- Specific installer scripts
- Shared libraries
- Configuration files
- Documentation files

## Validation Results

Results from validation checks:
- All installer scripts pass validation: `./validate_installers.sh`
- ShellCheck passes locally: `shellcheck --severity=error installers/*.sh lib/*.sh`
- Any other relevant test results

## Migration Notes (if applicable)

Instructions for users/contributors about any breaking changes or steps needed to upgrade.
```

**Example**:
```
Fix ShellCheck SC1090 warnings for dynamic sourcing
Enhanced dependency installation in Fabric AI setup

## Summary of Changes

Updated setup_fabric.sh to automatically install missing dependencies instead of just checking for them.

## Problem Statement

The Fabric AI installer was checking for dependencies but not installing them automatically, requiring users to manually install missing packages before running the script.

## Solution Details

Modified the check_dependencies function in setup_fabric.sh to use ensure_command for each dependency:
- op (1password-cli)
- ffmpeg
- yt-dlp
- curl

This leverages the shared dependencies library to automatically install missing packages.

## Testing Performed

- Verified the script installs dependencies correctly when missing
- Confirmed existing installations are detected properly
- Validated installer still functions correctly after dependency installation
- Ran full validation suite: `./validate_installers.sh`
- Passed ShellCheck: `shellcheck installers/setup_fabric.sh`

## Affected Components

- installers/setup_fabric.sh

## Validation Results

Add shellcheck directives to suppress SC1090 warnings for dynamic remote
sourcing via curl in installer scripts. These warnings are expected for
remote sourcing and cannot be statically verified.
All 20 installer scripts pass validation:
- setup_fabric.sh: ✓ Pass
- ShellCheck: ✓ Pass

Fixed scripts:
- installers/setup_beyondcompare.sh
- installers/setup_gum.sh
- installers/setup_neovim.sh
- installers/setup_remote_example.sh
- installers/setup_vscode.sh
## Migration Notes

All validation passes with new configuration.
No breaking changes. Existing installations will continue to work as before.
```

### Code Review Process
Expand Down
126 changes: 58 additions & 68 deletions IMPROVEMENTS.md
Original file line number Diff line number Diff line change
@@ -1,68 +1,58 @@
# Project Analysis and Improvement Summary

## Completed Changes

### 1. Standardized Metadata (All 16 Installer Scripts)
- **Fixed missing metadata** in 3 scripts that lacked proper headers
- **Required headers now enforced:**
- `#!/usr/bin/env bash` (correct shebang)
- `Description:` (purpose of the script)
- `Category:` (functional category)
- `set -euo pipefail` (bash strict mode)

### 2. Validation System
- **New validation script** (`validate_installers.sh`)
- Validates all installer scripts have required metadata
- Checks for standard bash strict mode
- Verifies library references
- **Results:** 16/16 installers now pass validation ✓

### 3. Testing Infrastructure
- **New test file** (`tests/test_dependencies.bats`)
- Tests `command_exists` function
- Tests `check_dependencies` function
- Tests error handling paths

### 4. Error Tracking System
- **New error tracking library** (`lib/error_tracking.sh`)
- Centralized error logging across all installers
- Automatic error reporting and statistics
- Error report generation
- JSON metrics tracking (when jq available)
- Cleanup utilities for old logs

### 5. Uninstall System
- **New uninstaller generator** (`uninstaller_generator.sh`)
- Automatically generates companion uninstall scripts
- Uses installer metadata to create templates
- Creates uninstallers directory structure

### 6. Enhanced Dependencies Library
- **Added mode flags** to `lib/dependencies.sh`:
- `DRY_RUN` - for testing installation logic without changes
- `NON_INTERACTIVE` - for automated/scripted installations

### 7. Feature Branch
- **Created branch:** `feature/project-analysis`
- Working directory is clean and ready for additional improvements

## Key Improvements Implemented

1. ✓ **Metadata Consistency** - All 16 installer scripts now follow the same metadata standard
2. ✓ **Validation Pipeline** - Automated validation catches missing metadata or structural issues
3. ✓ **Testing Coverage** - Bats tests for dependency management functions
4. ✓ **Error Monitoring** - Centralized error tracking with reporting capabilities
5. ✓ **Uninstall System** - Automated uninstaller generation framework
6. ✓ **Enhanced Libraries** - Added dry-run and non-interactive modes for automation

## Next Steps Available

These additional improvements can be implemented:

1. **Dry-run mode** - Add `--dry-run` flag to installer scripts using the new DRY_RUN variable
2. **CI/CD integration** - Add validation to GitHub Actions workflow
3. **Error tracking integration** - Add calls to track_error/track_success in installer scripts
4. **Menu system** - Add a simple bash menu if desired (py_menu.py already exists)
5. **Documentation** - Update README with new validation and error tracking features

All changes maintain backward compatibility - existing functionality is preserved while adding new capabilities.
# Linux Setup Improvements Log

## Overview
This document tracks significant improvements made to the linux-setup project to enhance code quality, consistency, and maintainability.

## Recent Improvements

### 1. Enhanced Installer Validation
**Date**: February 10, 2026
**Files Modified**: `validate_installers.sh`

#### Changes Made:
- Updated validation script to treat missing library references as errors instead of warnings
- Improved error reporting with clearer messaging
- Added proper exit codes for validation failures

#### Impact:
- Ensures all installer scripts properly source required libraries
- Prevents runtime errors due to missing dependencies
- Maintains consistent code quality standards across all scripts

### 2. Standardized Library Sourcing Pattern
**Date**: February 10, 2026
**Files Modified**: `installers/setup_gum.sh`, `installers/new_installer.sh`

#### Changes Made:
- Updated `setup_gum.sh` to use the standard library sourcing pattern from `template.tpl`
- Fixed `new_installer.sh` to properly source both `logging.sh` and `dependencies.sh`
- Removed duplicate/custom library sourcing implementations
- Ensured both scripts follow the same remote/local sourcing logic

#### Impact:
- Eliminated inconsistencies in how scripts source shared libraries
- Improved maintainability by using a single, well-tested sourcing pattern
- Enhanced remote execution capabilities with proper branch detection
- Reduced code duplication and potential for errors

### 3. Validation Results
All 18 installer scripts now pass validation:
- ✅ 18/18 installers pass all checks
- ✅ All scripts properly reference required libraries
- ✅ Consistent structure and metadata across all scripts
- ✅ ShellCheck passes for core files

## Benefits Achieved

1. **Improved Code Quality**: All installer scripts now follow consistent patterns
2. **Better Error Prevention**: Validation catches missing library references early
3. **Enhanced Maintainability**: Standardized patterns make updates easier
4. **Increased Reliability**: Remote execution works consistently across all scripts
5. **Reduced Technical Debt**: Eliminated custom implementations that diverged from the standard

## Future Recommendations

1. Extend validation to cover all installer scripts automatically
2. Add automated testing for remote execution scenarios
3. Implement version tracking for template updates
4. Create documentation for the standard library sourcing pattern
98 changes: 66 additions & 32 deletions installers/new_installer.sh
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,70 @@

set -euo pipefail

# Detect if we're running locally or remotely
is_running_remotely() {
local script_path="${BASH_SOURCE[0]}"
# If script is in a temporary directory, it's likely running remotely
if [[ "$script_path" == /tmp/* ]] || [[ "$script_path" == /var/tmp/* ]]; then
return 0 # true
else
return 1 # false
fi
}

# Function to source library remotely or locally
source_library() {
local library_name="$1"

if is_running_remotely; then
# Source library from GitHub using environment variables with defaults
local repo_user="${REPO_USER:-gdellis}"
local repo_name="${REPO_NAME:-linux-setup}"
local repo_branch="${REPO_BRANCH:-main}"

# For remote execution, try to detect branch from script URL if possible
# This is an enhancement to handle cases where the script is run from a non-default branch
local script_url
script_url=$(curl -fsSL -w "%{url_effective}\n" -o /dev/null "https://raw.githubusercontent.com/$repo_user/$repo_name/$repo_branch/installers/new_installer.sh" 2>/dev/null || echo "")

if [[ -n "$script_url" ]] && [[ "$script_url" == *"raw.githubusercontent.com"* ]]; then
# Extract branch from URL if possible
local url_branch
url_branch=$(echo "$script_url" | sed -E "s@.*raw.githubusercontent.com/[^/]+/[^/]+/([^/]+)/.*@\1@")
if [[ -n "$url_branch" ]] && [[ "$url_branch" != "new_installer.sh" ]]; then
repo_branch="$url_branch"
fi
fi

echo "Sourcing $library_name from remote repository ($repo_user/$repo_name/$repo_branch)..." >&2
# shellcheck source=/dev/null # Dynamic sourcing - ShellCheck can't verify
if ! source <(curl -fsSL "https://raw.githubusercontent.com/$repo_user/$repo_name/$repo_branch/lib/$library_name"); then
echo "ERROR: Failed to source $library_name from remote repository" >&2
echo "Tried URL: https://raw.githubusercontent.com/$repo_user/$repo_name/$repo_branch/lib/$library_name" >&2
echo "Please ensure REPO_USER, REPO_NAME, and REPO_BRANCH environment variables are set correctly" >&2
echo "Current values: REPO_USER=$repo_user, REPO_NAME=$repo_name, REPO_BRANCH=$repo_branch" >&2
exit 1
fi
else
# Source library locally
local script_dir
script_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)

if [[ -f "$script_dir/../lib/$library_name" ]]; then
# shellcheck source=/dev/null
source "$script_dir/../lib/$library_name"
else
echo "ERROR: Local library $library_name not found" >&2
exit 1
fi
fi
}

# Source required libraries
source_library "logging.sh"
source_library "dependencies.sh"

# Save and change directories
readonly ORIG_PWD=$(pwd)
readonly SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
# Check argument first
Expand All @@ -21,7 +85,8 @@ fi
# Setup Logging
# ------------------------------------------------------------
# region
APP_NAME=$(basename "$0" .sh) # Directly strips .sh extension
SCRIPT_NAME=$(basename "$0" .sh)
readonly APP_NAME="${SCRIPT_NAME/setup_/}"
readonly DL_DIR="${HOME}/Downloads/$APP_NAME"
readonly LOG_DIR="${HOME}/logs/$APP_NAME"
readonly LOG_FILE="${LOG_DIR}/$(date +%Y%m%d_%H%M%S)_${APP_NAME}.log"
Expand All @@ -30,37 +95,6 @@ readonly LOG_FILE="${LOG_DIR}/$(date +%Y%m%d_%H%M%S)_${APP_NAME}.log"
mkdir -p "$DL_DIR"
mkdir -p "$LOG_DIR"

# Color codes
readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
readonly YELLOW='\033[1;33m'
readonly NC='\033[0m' # No Color

# Logging functions with color and file output
log()
{
local colored_msg plain_msg
colored_msg="[$(date '+%Y-%m-%d %H:%M:%S')] $*"

# Strip ANSI color codes for log file
plain_msg=$(echo -e "$colored_msg" | sed -E 's/\x1B\[([0-9]{1,2}(;[0-9]{1,2})?)?[mK]//g')

# Output to terminal (with colors)
echo -e "$colored_msg"

# Output to log file (without colors)
echo "$plain_msg" >> "$LOG_FILE"
}

# shellcheck disable=SC2317,SC2329 # Functions are used by trap and other scripts
log_info() { log "${GREEN}[INFO]${NC} $*";}
# shellcheck disable=SC2317,SC2329 # Functions are used by trap and other scripts
log_error() { log "${RED}[ERROR]${NC} $*";}
# shellcheck disable=SC2317,SC2329 # Functions are used by trap and other scripts
log_success() { log "${GREEN}[SUCCESS]${NC} $*";}
# shellcheck disable=SC2317,SC2329 # Functions are used by trap and other scripts
log_warning() { log "${YELLOW}[WARNING]${NC} $*";}

log_info "=== $APP_NAME Installer Started ==="
log_info "Log file: $LOG_FILE"
# endregion
Expand Down
Loading
Loading