difflicious 0.1.0__tar.gz

difflicious-0.1.0/.dockerignore

@@ -0,0 +1,61 @@
+# Version control
+.git/
+.gitignore
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Testing
+tests/
+.pytest_cache/
+.coverage
+htmlcov/
+*.cover
+.hypothesis/
+
+# Documentation
+docs/
+*.md
+!README.md
+
+# Development files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Node modules (if any)
+node_modules/
+package-lock.json
+package.json
+
+# Build artifacts
+build/
+dist/
+*.egg
+
+# Environment files
+.env
+.env.local
+.venv/
+venv/
+
+# CI/CD
+.github/
+
+# Miscellaneous
+*.log
+*.tmp
+parsed_diff_output.json
+rendering_output_sample.json
+test_*.py
+test_*.txt

difflicious-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  python-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.9]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+    
+    - name: Run Python linting with ruff
+      run: uv run ruff check
+    
+    - name: Run Python formatting check with black
+      run: uv run black --check .
+    
+    - name: Run type checking with mypy
+      run: uv run mypy src/
+    
+    - name: Run Python tests with pytest
+      run: uv run pytest
+
+  javascript-lint:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '18'
+        cache: 'npm'
+    
+    - name: Install JavaScript dependencies
+      run: npm install
+    
+    - name: Run JavaScript linting with ESLint
+      run: npm run lint:js
+    
+    - name: Run JavaScript tests with Jest (if available)
+      run: npm run test:js
+      continue-on-error: true  # Allow this to fail if no tests exist yet

difflicious-0.1.0/.github/workflows/docker-publish.yml

@@ -0,0 +1,56 @@
+name: Docker Build and Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+
+env:
+  REGISTRY: docker.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to Docker Hub
+      if: github.event_name != 'pull_request'
+      uses: docker/login-action@v3
+      with:
+        username: ${{ secrets.DOCKER_USERNAME }}
+        password: ${{ secrets.DOCKER_HUB_TOKEN }}
+
+    - name: Extract metadata (tags, labels) for Docker
+      id: meta
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+        tags: |
+          type=ref,event=branch
+          type=ref,event=pr
+          type=semver,pattern={{version}}
+          type=semver,pattern={{major}}.{{minor}}
+          type=semver,pattern={{major}}
+          type=raw,value=latest,enable={{is_default_branch}}
+
+    - name: Build and push Docker image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        platforms: linux/amd64,linux/arm64
+        push: ${{ github.event_name != 'pull_request' }}
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max

difflicious-0.1.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,41 @@
+name: PyPI Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install build dependencies
+      run: |
+        uv sync --group dev
+
+    - name: Build package
+      run: |
+        uv build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        packages-dir: dist/

difflicious-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,50 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        uv sync
+
+    - name: Run linting
+      run: |
+        uv run ruff check
+
+    - name: Run type checking
+      run: |
+        uv run mypy src/ || true
+
+    - name: Run tests with coverage
+      run: |
+        uv run pytest --cov=src/difflicious --cov-report=xml --cov-report=term
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      if: matrix.python-version == '3.11'
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false

difflicious-0.1.0/.gitignore

@@ -0,0 +1,112 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build outputs
+dist/
+build/
+*.tgz
+*.tar.gz
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+logs/
+*.log
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage/
+.nyc_output/
+
+# Dependency directories
+jspm_packages/
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# next.js build output
+.next
+
+# Nuxt.js build output
+.nuxt
+
+# Gatsby files
+.cache/
+public
+
+# Storybook build outputs
+.out
+.storybook-out
+
+# Temporary folders
+tmp/
+temp/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Rust
+target/
+Cargo.lock
+
+# Go
+vendor/
+
+.coverage
+vendor/

difflicious-0.1.0/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md - Development Guide for Agentic Coding
+
+## Build/Test Commands
+- **Install dependencies**: `uv sync`
+- **Run tests**: `uv run pytest`
+- **Run single test**: `uv run pytest tests/test_app.py::test_index_route`
+- **Run with coverage**: `uv run pytest --cov=src/difflicious`
+- **Lint code**: `uv run ruff check`
+- **Format code**: `uv run black .`
+- **Type check**: `uv run mypy src/`
+- **Run app**: `uv run difflicious`
+
+## Docker Commands
+- **Build image**: `docker build -t insipid/difflicious:latest .`
+- **Build multi-platform**: `docker buildx build --platform linux/amd64,linux/arm64 -t insipid/difflicious:latest .`
+- **Push to Docker Hub**: `docker push insipid/difflicious:latest`
+- **Tag version**: `git tag v0.9.0 && git push origin v0.9.0` (triggers automated build/push)
+
+## Code Style Guidelines
+- **Line length**: 88 characters (Black/Ruff configured)
+- **Imports**: Use absolute imports, group stdlib/third-party/local with blank lines
+- **Type hints**: Required for all function definitions (`disallow_untyped_defs = true`)
+- **Docstrings**: Use triple quotes with Args/Returns sections for public functions
+- **Naming**: snake_case for functions/variables, PascalCase for classes
+- **Error handling**: Use custom exceptions (GitOperationError, DiffParseError) with descriptive messages
+- **Security**: All subprocess calls must use proper sanitization (see git_operations.py)
+- **File endings**: All text files must end with carriage return
+
+## Testing Patterns
+- Use pytest fixtures for app/client setup
+- Test classes for grouping related functionality (e.g., TestAPIDiffCommitComparison)
+- Assert response status codes and JSON structure for API endpoints
+- Mock external dependencies, test error handling paths

difflicious-0.1.0/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+All notable changes to difflicious 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).
+
+## [0.9.0] - 2025-10-31
+
+### Infrastructure & Deployment
+
+#### Docker & Containerization
+- **Multi-stage Dockerfile** with Alpine Linux for minimal image size
+- **.dockerignore** for optimized build context
+- **Multi-platform support** for AMD64 and ARM64 architectures
+- **Security hardening** with non-root user execution
+- **Health checks** for container monitoring
+- **Proper environment configuration** for local usage
+
+#### CI/CD Pipeline
+- **GitHub Actions workflows** for automated testing and deployment
+- **Multi-version testing** across Python 3.9, 3.10, 3.11, and 3.12
+- **Automated linting** with Ruff for Python code quality
+- **Automated type checking** with MyPy
+- **Code coverage reporting** with Codecov integration
+- **JavaScript linting** with ESLint
+- **Automated Docker publishing** to Docker Hub on version tags
+- **Automated PyPI publishing** with trusted publishing
+- **Build caching** for faster CI/CD runs
+
+#### Testing Infrastructure
+- **Comprehensive test suite** with 169 passing tests
+- **86% test coverage** across all modules
+- **Integration tests** for critical workflows
+- **Security tests** for git command sanitization
+- **Automated test execution** on every commit and PR
+- **Quality metrics** tracking and reporting
+
+#### Code Quality Automation
+- **Automated linting** with Ruff
+- **Automated formatting** with Black
+- **Automated type checking** with MyPy
+- **Automated quality checks** in CI pipeline
+- **Consistent code style** across the project
+
+### Build & Packaging
+- **Modern Python packaging** with pyproject.toml
+- **uv package management** for fast dependency resolution
+- **Standalone builds** with PyInstaller support
+- **CLI interface** with Click framework
+- **Version management** with dynamic versioning
+
+### Documentation
+- **Installation guide** with Docker and local installation instructions
+- **Troubleshooting guide** for common issues and solutions
+- **Contributing guidelines** for developers
+- **Changelog** for version history tracking
+- **Updated README** with current features and setup
+
+## [0.8.0] - Previous Versions
+
+### Features
+- **Side-by-side diff visualization** with professional interface
+- **Syntax highlighting** with Pygments for 30+ languages
+- **Intelligent diff parsing** with proper line alignment
+- **Interactive UI** with search, filtering, and expand/collapse
+- **Git integration** with status, diff, and branch detection
+- **Font customization** with 6 programming fonts
+- **Dark/Light mode** support
+- **Context expansion** for viewing more code around hunks
+- **Rename detection** for moved files
+
+### Infrastructure
+- **Flask backend** for minimal setup and git integration
+- **Alpine.js frontend** for lightweight, declarative UI
+- **Service layer architecture** with clean separation of concerns
+- **Error handling** with proper exception hierarchy
+- **Security** with subprocess sanitization for git commands
+
+## Version History
+
+- **0.9.0** (2025-10-31): Infrastructure milestone with Docker, CI/CD, and deployment automation
+- **0.8.0** and earlier: Core features and functionality
+
+## Future Releases
+
+### Planned for 1.0
+- Final UI/UX polish and improvements
+- Performance optimizations
+- Accessibility enhancements
+- Browser compatibility improvements
+- User feedback incorporation
+
+### Under Consideration
+- Real-time updates with Server-Sent Events
+- Advanced search and filtering
+- Keyboard shortcuts
+- Plugin system
+- Export options
+
+---
+
+## Release Notes
+
+### 0.9.0 - Infrastructure Release
+
+The 0.9 release marks a significant milestone for difflicious, establishing the development and operational infrastructure needed for reliable releases. This release focuses entirely on infrastructure, automation, and packaging tooling, laying the foundation for the 1.0 feature release.
+
+**Key Achievements:**
+- ✅ Complete CI/CD pipeline with GitHub Actions
+- ✅ Docker images for easy local installation
+- ✅ Automated testing across multiple Python versions
+- ✅ 86% test coverage with 169 passing tests
+- ✅ Automated quality checks and code coverage reporting
+- ✅ Docker Hub and PyPI publishing automation
+
+**What's Next:**
+Version 1.0 will focus on final features, polish, and user experience improvements based on real-world usage feedback from the 0.9 release.
+
+---
+
+*For detailed information about changes in each version, see the git commit history.*

difflicious-0.1.0/CLAUDE.md

@@ -0,0 +1,126 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Difflicious is a lightweight web-based git diff visualization tool built with Flask backend and Alpine.js frontend. It provides developers with an elegant interface for viewing git changes while working on branches locally.
+
+## Architecture
+
+**Technology Stack:**
+- Backend: Python Flask with service layer architecture for business logic separation
+- Services: Dedicated service classes (DiffService, GitService) with secure subprocess calls
+- Frontend: Alpine.js (~15KB) + vanilla CSS with Grid/Flexbox
+- Real-time: Server-Sent Events (SSE) for live git status monitoring
+- Security: Proper subprocess sanitization for git command execution
+
+**Service Layer Architecture:**
+- `BaseService`: Common functionality and lazy-loaded git repository access
+- `DiffService`: Business logic for diff processing and rendering
+- `GitService`: Git repository operations (status, branches, file access)
+- Service exceptions: `DiffServiceError`, `GitServiceError` for proper error handling
+- Clear separation between HTTP concerns (Flask routes) and business logic
+
+**Distribution Strategy:**
+1. PyPI package (primary) - `pip install difflicious`
+2. Docker image (secondary) - containerized deployment  
+3. Source installation (development fallback)
+
+## Development Commands
+
+This project uses `uv` for fast Python package management and development environments.
+
+**Project Setup:**
+```bash
+# Install uv if not already installed
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv sync
+
+# Run in development mode
+uv run difflicious
+
+# Access at localhost:5000
+```
+
+**Development Commands:**
+```bash
+# Add new dependencies
+uv add package-name
+
+# Add development dependencies
+uv add --dev pytest ruff black
+
+# Run tests (comprehensive test suite available)
+uv run pytest
+
+# Run linting/formatting
+uv run ruff check
+uv run black .
+
+# Build package
+uv build
+```
+
+**Docker Development:**
+- Multi-stage builds using uv for optimized container images
+- Base images will use uv for dependency installation
+
+## Current Development Status
+
+**Phase 1 - Project Setup & Core Backend (COMPLETED):**
+1. ✅ Set up modern Python project structure with pyproject.toml and uv
+2. ✅ Create Flask backend with proper uv-based packaging
+3. ✅ Implement git command execution wrapper with security
+4. ✅ Create basic HTML template with Alpine.js integration
+5. ✅ Build JSON API endpoints for git status and diff data
+6. 🚧 Create Dockerfile using uv for containerized deployment
+
+**Implementation Completed:**
+- ✅ Git command wrapper: Secure subprocess sanitization with comprehensive security validation
+- ✅ Flask backend: Complete API with `/api/status` and `/api/diff` endpoints
+- ✅ Service Layer: Business logic extracted to DiffService and GitService with 100% test coverage
+- ✅ Frontend: Alpine.js reactive interface with search, filtering, and diff visualization
+- ✅ Security: All git commands properly sanitized, injection prevention, path validation
+- ✅ Testing: Comprehensive test suite including dedicated service layer tests
+
+## Core Features Status
+
+- ✅ **Advanced Diff Parsing**: Complete git diff parser with side-by-side structure generation
+- ✅ **Side-by-Side Visualization**: Professional-grade diff interface with line numbering and color coding
+- ✅ **Syntax Highlighting**: Beautiful code highlighting for 30+ languages using Highlight.js
+- ✅ **Smart UI Controls**: Expand/collapse all buttons with intelligent disabled states
+- ✅ **Clean File Paths**: Automatic removal of git diff artifacts (a/, b/ prefixes)
+- ✅ **Interactive Controls**: Toggle visibility, search/filter capabilities implemented
+- ✅ **Git Integration**: Live git status and structured diff data from real repositories
+- ✅ **Service Architecture**: Clean separation of concerns with testable business logic
+- ✅ **Command-line Interface**: Full CLI with host, port, debug options
+- ✅ **Modern UI**: Tailwind CSS styling with responsive design
+- 🚧 **Real-time Updates**: Server-Sent Events implementation planned
+- 🚧 **Word-level Diffs**: Advanced word-diff parsing (available in separate branch)
+
+## Security Requirements (IMPLEMENTED)
+
+- ✅ All git command execution uses proper subprocess sanitization
+- ✅ Command injection prevention with argument validation and character filtering
+- ✅ Safe git option validation with whitelist-based approach
+- ✅ File path validation to prevent directory traversal attacks
+- ✅ Timeout protection for git commands to prevent resource exhaustion
+- ✅ No exposure of sensitive git repository information
+- ✅ Local-only operation (no external network calls for core functionality)
+
+## Code Quality Requirements
+
+- **File Formatting**: ALL TEXT FILES SHOULD END WITH A CARRIAGE RETURN
+- **Documentation Sync**: Any changes to architecture/infrastructure must update PLAN.md, README.md, and CLAUDE.md to keep them in sync
+- **Package Management**: Use `uv` for all Python dependency management and virtual environments
+- **Security**: All git command execution must use proper subprocess sanitization
+
+## Deployment Targets
+
+The application is designed for multiple distribution channels:
+- PyPI package for easy `pip install` (built with uv)
+- Docker containers using uv for consistent, fast dependency installation
+- Source installation with uv for development and customization