diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..343ec13 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,56 @@ +# Git +.git/ +.gitignore +.github/ + +# Documentation (not needed for tests) +*.md +!README.md + +# Test artifacts +.pytest_cache/ +.coverage +htmlcov/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Logs +*.log +*.log.* + +# Backups +*.bak +*.backup +*.old + +# OS +.DS_Store +Thumbs.db + +# Node +node_modules/ +npm-debug.log +yarn-error.log + +# Python +__pycache__/ +*.py[cod] +*$py.class +.Python +venv/ +env/ + +# Build artifacts +dist/ +build/ +*.egg-info/ + +# Temporary +tmp/ +temp/ +*.tmp diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..f2ae5af --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,123 @@ +name: Tests + +on: + push: + branches: [ main, master, develop, claude/* ] + pull_request: + branches: [ main, master, develop ] + +jobs: + test: + name: Run Tests + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up test environment + run: | + sudo apt-get update + sudo apt-get install -y jq + + - name: Run test suite + run: | + chmod +x run-tests.sh + chmod +x tests/*.sh + ./run-tests.sh bootstrap configs scripts + + - name: Test summary + if: always() + run: | + echo "### Test Results" >> $GITHUB_STEP_SUMMARY + if [ $? -eq 0 ]; then + echo "✅ All tests passed!" >> $GITHUB_STEP_SUMMARY + else + echo "❌ Some tests failed!" >> $GITHUB_STEP_SUMMARY + fi + + shellcheck: + name: ShellCheck Linting + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run ShellCheck + uses: ludeeus/action-shellcheck@master + with: + scandir: '.' + ignore_paths: '.git tmux/plugins yazi/plugins bat/themes' + severity: warning + continue-on-error: true + + - name: ShellCheck summary + run: echo "### ShellCheck completed" >> $GITHUB_STEP_SUMMARY + + validate-configs: + name: Validate Configuration Files + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install validators + run: | + sudo apt-get update + sudo apt-get install -y jq yamllint + + - name: Validate JSON files + run: | + echo "Validating JSON files..." + find . -name "*.json" ! -path "./.git/*" ! -path "./node_modules/*" | while read -r file; do + echo "Checking $file" + jq empty "$file" || exit 1 + done + + - name: Validate YAML files + run: | + echo "Validating YAML files..." + find . -name "*.yml" -o -name "*.yaml" ! -path "./.git/*" ! -path "./node_modules/*" | while read -r file; do + echo "Checking $file" + yamllint -d relaxed "$file" || true + done + + - name: Check for backup files + run: | + echo "Checking for backup files that shouldn't be committed..." + if git ls-files | grep -E '\.(bak|backup|old|swp|tmp)$'; then + echo "❌ Found backup files in git!" + exit 1 + else + echo "✅ No backup files found" + fi + + docker-test: + name: Docker Integration Test + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Build quick test image + run: docker build -f Dockerfile.test-quick -t dotfiles-test:quick . + + - name: Run quick Docker test + run: | + docker run --rm dotfiles-test:quick + + - name: Docker test summary + if: always() + run: | + echo "### Docker Test Results" >> $GITHUB_STEP_SUMMARY + if [ $? -eq 0 ]; then + echo "✅ Docker tests passed!" >> $GITHUB_STEP_SUMMARY + else + echo "❌ Docker tests failed!" >> $GITHUB_STEP_SUMMARY + fi diff --git a/.gitignore b/.gitignore index 77b20f8..98b40e1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,35 +1,36 @@ +# Backup and temporary files *.bak *.backup - -# Default meson build dir -/build - -/outputs - -# ccls -/.ccls-cache - -result -result-* +*.back +*.old +*.orig +*.save +*.swp +*.swo +*.tmp +*.temp +*~ +*.backup.* +*.*.backup +.#* +#*# # IDE .vscode/ .idea/ +.cursorindexingignore -.pre-commit-config.yaml - -# clangd and possibly more +# Cache directories .cache/ # Mac OS .DS_Store -flake-regressions - # direnv .direnv/ -CLAUDE.md + +# Claude Code .claude/settings.local.json -CLAUDE.md + +# Tool logs navi/navi.log -.cursorindexingignore diff --git a/.specstory/.gitignore b/.specstory/.gitignore deleted file mode 100644 index 47967ea..0000000 --- a/.specstory/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -# SpecStory explanation file -/.what-is-this.md -/history diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6e17077 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,105 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] - 2025-11-08 + +### Added + +#### Testing Infrastructure +- Comprehensive test framework with custom assertion library (`tests/test-framework.sh`) +- Test suites for bootstrap, configurations, and scripts (`tests/test-*.sh`) +- Test orchestrator with colorized output (`run-tests.sh`) +- Docker testing infrastructure with multiple modes (quick, full, multi-distro) +- Docker test environments (`Dockerfile.test`, `Dockerfile.test-quick`, `docker-compose.test.yml`) +- Docker testing orchestrator script (`scripts/test-in-docker.sh`) +- GitHub Actions CI/CD pipeline with parallel testing jobs +- Pre-commit git hooks for automated testing +- Docker integration testing in CI/CD pipeline + +#### Scripts and Utilities +- Shared utility library with error handling (`scripts/common.sh`) +- Post-installation validation script (`scripts/validate-install.sh`) +- Environment health check diagnostic tool (`scripts/health-check.sh`) +- Git hooks installation script (`scripts/install-hooks.sh`) + +#### Documentation +- Comprehensive testing guide (`docs/testing-guide.md`) +- Docker testing documentation (`docs/docker-testing.md`) +- Script reference manual (`docs/script-reference.md`) +- Troubleshooting guide (`docs/troubleshooting.md`) +- MCP migration summary moved to docs +- Enhanced README with new sections and examples + +#### Development Tools +- Comprehensive Makefile with 28+ targets for task automation +- Shell completions support preparation +- Version management with VERSION file +- This CHANGELOG for tracking changes + +#### Configuration +- `.dockerignore` for optimized Docker builds +- `.editorconfig` preparation for consistent formatting +- Enhanced `.gitignore` with comprehensive backup patterns + +#### Features +- Dry-run mode for bootstrap script (`--dry-run` flag) +- Enhanced logging system with multiple levels (DEBUG, INFO, WARN, ERROR) +- Signal handling and cleanup registration in scripts +- Retry logic with exponential backoff for network operations +- JSON/YAML validation utilities +- Interactive confirmation prompts +- Timestamped backup creation + +### Changed +- Reorganized repository structure with dedicated `setup/` and `tests/` directories +- Improved bootstrap script with better error handling and logging +- Updated test-configs.sh to match actual file structure +- Enhanced Makefile with validation and diagnostic targets +- Moved MCP-related scripts to appropriate directories + +### Fixed +- Script permissions in `scripts/` directory (11 scripts made executable) +- Test framework arithmetic compatibility issues +- Configuration file test expectations to match actual structure +- Docker test image non-root user security + +### Removed +- Legacy migration scripts (migrate-to-mcp-json.sh, test-mcp-json.sh) +- Empty `.specstory/` directory +- Obsolete `.gitignore` entries (meson, ccls, Nix) +- 7 backup files from yazi directory (keymap.toml-*) +- Scattered root-level scripts (moved to organized directories) + +### Security +- Non-root user in Docker containers +- Signal trap handlers for cleanup +- Safe directory and file operations +- Backup file exclusion patterns + +## [Unreleased] + +### Planned +- Interactive setup wizard with tool selection +- Automated release process with GitHub Actions +- Performance benchmarking in CI +- Shell completion files for bash and zsh +- Uninstall script for clean removal +- Configuration profile system (work/personal/server) +- Update checker for tool versions + +--- + +## Version History + +- **1.0.0** - Initial stable release with comprehensive testing and documentation +- Earlier versions were informal development iterations + +## Links + +- [Repository](https://github.com/ryanwclark1/dotfiles) +- [Issue Tracker](https://github.com/ryanwclark1/dotfiles/issues) +- [Releases](https://github.com/ryanwclark1/dotfiles/releases) diff --git a/CLAUDE.md b/CLAUDE.md index c9f4f3e..933d747 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,10 +20,10 @@ This is a personal dotfiles repository that manages configuration files and util ### Testing and Validation ```bash # Test MCP servers functionality -./test-mcp.sh +./tests/test-mcp.sh # Clean up duplicate dotfiles entries in .bashrc -./cleanup_bashrc.sh +./scripts/cleanup_bashrc.sh ``` ### VSCode Extension Management @@ -260,4 +260,7 @@ The `update_dots.sh` script automatically excludes backup files with these patte 1. **Making Changes**: Edit configurations in `~/.config/` during normal use 2. **Syncing Changes**: Run `./update_dots.sh` to copy changes back to repository 3. **Adding New Tools**: Follow the bootstrap script extension guide above -4. **Testing**: Use provided test scripts (`test-mcp.sh`) to validate functionality +4. **Testing**: Use the comprehensive test framework to validate changes + - Run all tests: `./run-tests.sh` + - Run specific suite: `./run-tests.sh bootstrap` or `./run-tests.sh configs` + - See `docs/testing-guide.md` for detailed testing documentation diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ed2a8a0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,433 @@ +# Contributing to Dotfiles + +Thank you for your interest in contributing to this dotfiles repository! This document provides guidelines and instructions for contributing. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Coding Standards](#coding-standards) +- [Testing Requirements](#testing-requirements) +- [Commit Guidelines](#commit-guidelines) +- [Pull Request Process](#pull-request-process) +- [Adding New Tools](#adding-new-tools) +- [Documentation](#documentation) + +## Code of Conduct + +This project follows a simple code of conduct: be respectful, constructive, and helpful. We welcome contributions from everyone. + +## Getting Started + +### Prerequisites + +- Git +- Bash 4.0+ or Zsh +- Docker (for running Docker tests) +- Basic understanding of shell scripting + +### Fork and Clone + +1. Fork the repository on GitHub +2. Clone your fork locally: + ```bash + git clone https://github.com/YOUR_USERNAME/dotfiles.git + cd dotfiles + ``` +3. Add upstream remote: + ```bash + git remote add upstream https://github.com/ryanwclark1/dotfiles.git + ``` + +### Set Up Development Environment + +```bash +# Install git hooks +make install-hooks + +# Or manually +./scripts/install-hooks.sh + +# Run tests to ensure everything works +make test +``` + +## Development Workflow + +### 1. Create a Feature Branch + +```bash +git checkout -b feature/your-feature-name +``` + +### 2. Make Your Changes + +- Follow the coding standards (see below) +- Add tests for new functionality +- Update documentation as needed + +### 3. Test Your Changes + +```bash +# Run all tests +make test + +# Run specific test suite +./run-tests.sh bootstrap + +# Test in Docker (recommended) +make docker-test + +# Run full CI checks locally +make ci +``` + +### 4. Commit Your Changes + +Follow the commit guidelines (see below). + +### 5. Push and Create Pull Request + +```bash +git push origin feature/your-feature-name +``` + +Then create a pull request on GitHub. + +## Coding Standards + +### Shell Scripts + +1. **Strict Mode**: All scripts should use: + ```bash + #!/usr/bin/env bash + set -euo pipefail + ``` + +2. **Naming Conventions**: + - Use lowercase with underscores for functions: `my_function()` + - Use UPPERCASE for constants: `INSTALL_DIR="/usr/local"` + - Use lowercase for local variables: `local my_var="value"` + +3. **Error Handling**: + - Use signal handlers for cleanup + - Provide meaningful error messages + - Use `log()` function from `scripts/common.sh` + ```bash + source "$(dirname "$0")/common.sh" + setup_signal_handlers + log "INFO" "Starting operation..." + ``` + +4. **Documentation**: + - Add header comments explaining purpose + - Document function parameters and return values + - Include usage examples + +5. **ShellCheck**: All scripts must pass ShellCheck: + ```bash + make lint + ``` + +### Example Script Structure + +```bash +#!/usr/bin/env bash +# +# script-name.sh - Brief description of what this script does +# +# Usage: +# ./script-name.sh [OPTIONS] +# +# Options: +# -h, --help Show this help message +# -v, --verbose Enable verbose output + +set -euo pipefail + +# Source common utilities +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/common.sh" + +# Constants +readonly SCRIPT_NAME="$(basename "$0")" +readonly VERSION="1.0.0" + +# Functions +usage() { + cat </dev/null; then + test_fail "Should have failed with invalid option" +else + test_pass +fi + +test_summary +``` + +### Running Tests + +```bash +# All tests +make test + +# Specific suite +./run-tests.sh bootstrap + +# Docker tests (recommended before PR) +make docker-test +make docker-test-full +make docker-test-multi + +# Complete CI check +make ci +``` + +### Test Requirements + +- All new features must include tests +- Tests must pass on Ubuntu, Debian, and Alpine (use `make docker-test-multi`) +- Maintain or improve test coverage +- Tests should be fast (<1 second per test when possible) + +## Commit Guidelines + +### Commit Message Format + +``` +: + + + +