Skip to content

Latest commit

 

History

History
356 lines (262 loc) · 8.67 KB

CLAUDE.md

File metadata and controls

356 lines (262 loc) · 8.67 KB

CLAUDE.md - Sam's Simple Installer (ssi)

Project Overview

Sam's Simple Installer (ssi) is a lightweight bash script that simplifies installing binaries from GitHub releases. It automatically detects the user's operating system, downloads the appropriate release asset, and installs it to the user's local directory structure following XDG Base Directory conventions.

Core Concept

The script follows the pattern ssi owner/repository to install the latest release from any GitHub repository that provides binary releases.

Example Usage

# Install neovim
ssi neovim/neovim

# Install ripgrep
ssi BurntSushi/ripgrep

# Install any GitHub project with releases
ssi sharkdp/fd
ssi junegunn/fzf

Technical Requirements

Dependencies

  • curl: For downloading releases and API calls
  • tar: For extracting tarballs

Supported Platforms

  • Linux (x86_64, arm64, armv7)
  • macOS (x86_64, arm64/Apple Silicon)
  • Windows (via WSL or Git Bash)

Installation Directory Structure

Following XDG Base Directory specification:

~/.local/bin/     # Executable binaries (added to PATH)
~/.local/share/   # Shared data, documentation, man pages
~/.local/lib/     # Shared libraries and internal files

Core Features

1. OS and Architecture Detection

detect_platform() {
    OS=$(uname -s | tr '[:upper:]' '[:lower:]')
    ARCH=$(uname -m)

    case $ARCH in
        x86_64|amd64) ARCH="x86_64" ;;
        aarch64|arm64) ARCH="arm64" ;;
        armv7l) ARCH="armv7" ;;
    esac
}

2. GitHub API Integration

  • Fetch latest release information using GitHub API v4
  • Parse release assets to find matching platform binary
  • Handle rate limiting and API errors gracefully
  • Support for both public and private repositories (with token)

3. Asset Selection Logic

Priority order for selecting the correct asset:

  1. Exact OS and architecture match
  2. Generic patterns (e.g., linux, darwin, windows)
  3. Common naming conventions across projects
  4. Fallback to manual selection if multiple matches

4. Installation Process

  1. Pre-installation checks:
    • Verify dependencies are available
    • Check internet connectivity
    • Validate GitHub repository format
  2. Download and verification:
    • Download to temporary directory
    • Verify file integrity if checksums available
    • Detect archive type (tar.gz, tar.bz2, zip, etc.)
  3. User confirmation:
    • Display installation summary
    • Show target directories
    • Confirm before proceeding
  4. Installation:
    • Create directory structure if needed
    • Extract archive intelligently
    • Place binaries in appropriate locations
    • Handle overwriting existing installations
    • Set proper permissions

5. Smart Archive Handling

extract_archive() {
    local archive_file="$1"
    local extract_dir="$2"

    case "$archive_file" in
        *.tar.gz|*.tgz) tar -xzf "$archive_file" -C "$extract_dir" ;;
        *.tar.bz2|*.tbz2) tar -xjf "$archive_file" -C "$extract_dir" ;;
        *.tar.xz) tar -xJf "$archive_file" -C "$extract_dir" ;;
        *.zip) unzip -q "$archive_file" -d "$extract_dir" ;;
        *) echo "Unsupported archive format: $archive_file" ;;
    esac
}

Error Handling and Edge Cases

Network Issues

  • Retry logic for failed downloads
  • Graceful handling of GitHub API rate limits
  • Offline detection and appropriate messaging

Archive Variations

  • Handle nested directories in archives
  • Deal with single binary releases
  • Support various compression formats
  • Handle archives with multiple binaries

Permission Issues

  • Check write permissions before installation
  • Handle existing file conflicts

Repository Variations

  • Projects without releases
  • Pre-release vs stable release handling
  • Missing platform-specific builds

Configuration Options

Environment Variables

SSI_INSTALL_DIR="${HOME}/.local"     # Override installation directory
SSI_GITHUB_TOKEN=""                  # GitHub token for private repos/higher rate limits
SSI_TEMP_DIR="/tmp/ssi"             # Temporary download directory
SSI_AUTO_CONFIRM="false"            # Skip confirmation prompts
SSI_VERBOSE="false"                 # Enable verbose output

Testing Strategy

Test Structure

tests/
├── unit/
│   ├── test_platform_detection.py
│   ├── test_github_api.py
│   ├── test_archive_handling.py
│   └── test_installation.py
├── integration/
│   ├── test_full_installation.py
│   └── test_edge_cases.py
├── fixtures/
│   ├── sample_releases.json
│   └── sample_archives/
└── conftest.py

Test Categories

Unit Tests

  • Platform detection accuracy
  • GitHub API response parsing
  • Archive extraction logic
  • File permission handling
  • Configuration parsing

Integration Tests

  • Full installation workflow
  • Multiple platform testing
  • Real GitHub repository testing
  • Network failure simulation
  • Cleanup and rollback testing

Mock Testing

  • GitHub API responses
  • File system operations
  • Network requests
  • User input simulation

Test Data

SAMPLE_REPOSITORIES = [
    "neovim/neovim",      # Complex multi-platform releases
    "BurntSushi/ripgrep", # Rust project with many targets
    "sharkdp/fd",         # Simple binary releases
    "junegunn/fzf",       # Go project with various formats
]

PLATFORM_MATRIX = [
    ("linux", "x86_64"),
    ("linux", "arm64"),
    ("darwin", "x86_64"),
    ("darwin", "arm64"),
]

Implementation Phases

Phase 1: Core Functionality

  • Basic GitHub API integration
  • Platform detection
  • Simple archive extraction
  • Basic installation to ~/.local/bin

Phase 2: Enhanced Features

  • Smart asset selection
  • User confirmation prompts
  • Configuration file support
  • Better error handling

Phase 3: Advanced Features

  • Rollback functionality
  • Update checking
  • Batch installation
  • Shell completion

Phase 4: Polish and Testing

  • Comprehensive test suite
  • Documentation
  • Performance optimization
  • Security hardening

File Structure

ssi/
├── ssi                          # Main bash script
├── README.md                    # User documentation
├── CLAUDE.md                    # This file
├── LICENSE                      # Project license
├── tests/                       # Test suite
│   ├── conftest.py
│   ├── unit/
│   ├── integration/
│   └── fixtures/
├── docs/                        # Additional documentation
│   ├── INSTALLATION.md
│   ├── CONFIGURATION.md
│   └── TROUBLESHOOTING.md
└── examples/                    # Usage examples
    └── common_packages.md

Security Considerations

Download Safety

  • Verify HTTPS connections
  • Check file signatures when available
  • Validate downloaded file integrity
  • Use temporary directories with proper permissions

Installation Safety

  • Never run as root unless explicitly required
  • Validate installation paths
  • Check for path traversal attacks
  • Set appropriate file permissions

API Security

  • Secure token storage
  • Rate limit handling
  • Input validation for repository names

User Experience Goals

Simplicity

  • Single command installation
  • Minimal configuration required
  • Clear, helpful error messages
  • Intuitive command-line interface

Reliability

  • Robust error handling
  • Graceful degradation
  • Consistent behavior across platforms
  • Proper cleanup on failures

Transparency

  • Show what will be installed where
  • Provide installation progress feedback
  • Log important actions
  • Enable verbose mode for debugging

Success Metrics

Functionality

  • Successfully install from 95% of repositories with binary releases
  • Handle all major platforms (Linux, macOS, Windows/WSL)
  • Complete installation in under 30 seconds for typical packages

Usability

  • Zero configuration required for basic usage
  • Clear error messages for all failure modes
  • Consistent behavior across different projects

Reliability

  • Pass 100% of test suite
  • Handle network failures gracefully
  • Maintain backwards compatibility

Future Enhancements

Potential Features

  • Integration with package managers
  • Dependency resolution
  • Version pinning and management
  • Automatic updates
  • Shell integration and completion
  • Web interface for discovery

Community Features

  • User-contributed package definitions
  • Installation analytics (opt-in)
  • Community package recommendations
  • Integration with dotfiles managers

This document serves as the comprehensive guide for developing the Sam's Simple Installer. It should be updated as the project evolves and new requirements are discovered.