Merge pull request #24 from dryan/briefcase-console-app

dryan · web-flow · commit 0aa434ed8bac · 2025-11-18T12:00:49.000-05:00
⚠️ v4.4.3: Add breaking change warning to update notifications
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,117 @@
+# AGENTS.md - Development Preferences for d3ploy Briefcase Conversion
+
+This file captures preferences and guidelines for AI agents working on the d3ploy project, specifically for converting it to a Briefcase console application.
+
+## Project Context
+
+- **Current State**: Python CLI tool that syncs files to AWS S3 with multiple environment support
+- **Goal**: Convert to standalone Briefcase console app for distribution without dependency management
+- **Repository**: <https://github.com/dryan/d3ploy>
+
+## Questions for Project Owner
+
+Please answer the following questions to help guide the development process:
+
+### 1. **Target Platforms & Distribution**
+
+- ✅ **Platforms**: All three (macOS, Windows, Linux)
+- ✅ **Distribution**: GitHub releases + PyPI distribution
+- ❓ **Architecture requirements**: Intel, ARM, universal binaries?
+
+### 2. **User Experience & Interface**
+
+- ✅ **Breaking changes allowed**: Yes, if they make sense
+- ✅ **New features**: Will be added in future releases after this conversion
+- ✅ **Interface improvements**: Open to modernizing the CLI experience
+
+### 3. **Configuration & Data**
+
+- ✅ **Config files**: Support both `d3ploy.json` and `.d3ploy.json` in project directory
+- ✅ **App data**: Move cache, logs, temp files to standard app data locations
+- ✅ **Configuration priority**: CLI flags > environment variables > config file > defaults
+
+### 4. **Dependencies & Bundling**
+
+- ✅ **Minimize dependencies**: Replace colorama with first-party code
+- ✅ **Use Textual**: Use <https://textual.textualize.io/> instead of colorama + tqdm
+- ✅ **boto3**: Keep for now, replace with custom AWS library in future
+- ✅ **Final bundle preference**: Textual for modern TUI experience
+
+### 5. **Development & Testing**
+
+- ✅ **Unified approach**: Pip package distributes Briefcase binary (like ruff/uv)
+- ✅ **Single codebase**: One version, different packaging approach
+- ✅ **Distribution**: PyPI wheels with binaries + GitHub releases
+
+### 6. **Maintenance & Updates**
+
+- ✅ **Update source**: Continue using PyPI as version source of truth
+- ✅ **Update notifications**: Follow Textual interface patterns
+- ✅ **Breaking changes**: Release patch version warning about upcoming changes
+- ✅ **Config migration**: Auto-detect and migrate old config versions
+- ✅ **Config versioning**: Add version property to new config structure
+
+### 7. **Code Organization**
+
+- ✅ **Refactoring allowed**: Yes, prioritize maintainability and testability
+- ✅ **Modular structure**: Break apart large d3ploy.py into focused modules
+- ✅ **Separation of concerns**: UI, AWS ops, config, file operations in separate modules
+- ✅ **Briefcase compatibility**: Structure code to work well with Briefcase and Textual
+
+---
+
+## Development Guidelines
+
+Based on the responses above, here are the guidelines for this conversion:
+
+### Architecture & Code Organization
+
+- **Modular design**: Refactor the monolithic `d3ploy.py` into focused modules:
+  - `config/` - Configuration loading, validation, and migration
+  - `aws/` - S3 and CloudFront operations (keeping boto3 for now)
+  - `ui/` - Textual-based interface components
+  - `sync/` - File synchronization logic
+  - `core/` - Main application logic and coordination
+- **Testability**: Design for easy unit testing of individual components
+- **Briefcase structure**: Follow Briefcase app conventions for entry points and packaging
+
+### User Interface & Experience
+
+- **Textual integration**: Replace colorama + tqdm with Textual for modern TUI experience
+- **Breaking changes**: Document and implement sensible improvements to CLI
+- **Error handling**: Improve error messages and user feedback with Textual's capabilities
+- **Progress indication**: Use Textual's rich progress components
+
+### Configuration & Data Management
+
+- **Config files**: Support both `d3ploy.json` and `.d3ploy.json` in project directory
+- **Config versioning**: Add `version` property to config structure for migration
+- **Auto-migration**: Detect and automatically upgrade old config formats
+- **Priority order**: CLI flags > environment variables > config file > defaults
+- **App data**: Move cache, logs, temp files to platform-standard app data directories
+
+### Dependencies & Bundling
+
+- **Textual**: Primary UI framework replacing colorama and tqdm
+- **boto3**: Keep for now, plan future replacement with custom AWS library
+- **Minimize deps**: Replace other dependencies where practical
+- **Bundle size**: Optimize for reasonable size while maintaining functionality
+
+### Distribution & Updates
+
+- **Unified approach**: Single codebase, PyPI distributes Briefcase binaries
+- **Platform support**: macOS, Windows, Linux binaries
+- **GitHub releases**: Direct binary downloads as alternative to PyPI
+- **Update checking**: Continue using PyPI as source of truth
+- **Breaking change warning**: Release patch version before major changes
+
+### Release Process
+
+- **Semantic versioning**: Continue current approach
+- **Git workflow**: Create PR → merge to main → push git tag → GitHub Actions triggers release
+- **PyPI automation**: GitHub Actions handles PyPI publishing on tag push  
+- **Gitmoji**: Always use gitmoji for commit messages
+- **Warning release**: Issue patch with breaking change notification
+- **Config migration**: Ensure smooth transition for existing users
+- **Testing**: Platform-specific testing for binary distributions
+- **CI/CD**: Build binaries for all platforms in automated pipeline
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -0,0 +1,218 @@
+# D3ploy Briefcase Conversion Roadmap
+
+This roadmap outlines the complete conversion of d3ploy from a traditional Python package to a Briefcase console application with Textual interface.
+
+## Phase 1: Breaking Change Warning Release
+
+### 1.1 Current Version Patch Release
+
+- [x] Update update notification text to warn about upcoming major changes
+- [x] Test warning message displays correctly
+- [ ] Release patch version (4.4.3) to PyPI
+- [ ] Monitor user feedback and questions
+- [ ] Document migration timeline and what's changing
+
+### 1.2 User Communication
+
+- [ ] Update GitHub README with migration notice
+- [ ] Create GitHub issue/discussion about upcoming changes
+- [ ] Provide clear timeline for new version
+- [ ] Document what will break and how to prepare
+
+## Phase 2: Project Setup & Foundation
+
+### 2.1 Briefcase Configuration
+
+- [x] Create initial `briefcase.toml` configuration
+- [ ] Install Briefcase and verify setup
+- [ ] Test basic Briefcase build process
+- [ ] Configure platform-specific settings
+
+### 2.2 Dependencies & Environment
+
+- [ ] Add Textual to dependencies
+- [ ] Update `pyproject.toml` with new dependency structure
+- [ ] Remove colorama and tqdm from requirements
+- [ ] Test dependency resolution
+
+### 2.3 Project Structure Planning
+
+- [ ] Design new modular package structure
+- [ ] Plan module responsibilities and interfaces
+- [ ] Create placeholder modules and **init**.py files
+
+## Phase 2: Code Refactoring & Modularization
+
+### 2.1 Configuration System
+
+- [ ] Create `d3ploy/config/` module
+- [ ] Implement config versioning system
+- [ ] Add support for both `d3ploy.json` and `.d3ploy.json`
+- [ ] Implement environment variable support
+- [ ] Create config migration logic for old formats
+- [ ] Add priority system: CLI flags > env vars > config file > defaults
+
+### 2.2 AWS Operations Module
+
+- [ ] Create `d3ploy/aws/` module
+- [ ] Extract S3 operations from main file
+- [ ] Extract CloudFront operations from main file
+- [ ] Maintain boto3 compatibility
+- [ ] Add proper error handling and retries
+
+### 2.3 File Synchronization Module
+
+- [ ] Create `d3ploy/sync/` module
+- [ ] Extract file discovery logic
+- [ ] Extract upload/download logic
+- [ ] Extract deletion logic
+- [ ] Implement pathspec-based filtering
+- [ ] Add gitignore support
+
+### 2.4 Core Application Logic
+
+- [ ] Create `d3ploy/core/` module
+- [ ] Extract main application coordination logic
+- [ ] Implement proper signal handling
+- [ ] Add graceful shutdown mechanisms
+
+## Phase 3: Textual Interface Implementation
+
+### 3.1 Basic UI Components
+
+- [ ] Create `d3ploy/ui/` module
+- [ ] Design Textual application structure
+- [ ] Implement progress bars to replace tqdm
+- [ ] Create status display components
+- [ ] Add colored output to replace colorama
+
+### 3.2 Interactive Features
+
+- [ ] Implement confirmation dialogs
+- [ ] Add real-time progress updates
+- [ ] Create error display components
+- [ ] Add update notification UI
+
+### 3.3 CLI Integration
+
+- [ ] Maintain command-line argument compatibility
+- [ ] Integrate Textual with argparse
+- [ ] Implement quiet mode for automated usage
+- [ ] Add proper exit codes and error handling
+
+## Phase 4: Data Management & Standards
+
+### 4.1 App Data Directories
+
+- [ ] Implement platform-specific app data paths
+- [ ] Move cache files to standard locations
+- [ ] Move log files to standard locations
+- [ ] Move temporary files to standard locations
+- [ ] Maintain backward compatibility for existing users
+
+### 4.2 Update System Enhancement
+
+- [ ] Modify update checker for new architecture
+- [ ] Implement Textual-based update notifications
+- [ ] Add breaking change warning system
+- [ ] Test PyPI version checking
+
+## Phase 5: Testing & Quality Assurance
+
+### 5.1 Unit Testing
+
+- [ ] Create tests for config module
+- [ ] Create tests for AWS operations module
+- [ ] Create tests for sync module
+- [ ] Create tests for core logic
+- [ ] Create tests for UI components (where applicable)
+- [ ] Ensure 100% test coverage maintenance
+
+### 5.2 Integration Testing
+
+- [ ] Test Briefcase build process
+- [ ] Test cross-platform compatibility
+- [ ] Test config migration scenarios
+- [ ] Test environment variable handling
+- [ ] Test real AWS operations (with mocking)
+
+### 5.3 Performance Testing
+
+- [ ] Benchmark new vs old performance
+- [ ] Test memory usage of bundled app
+- [ ] Test startup time
+- [ ] Test large file synchronization
+
+## Phase 6: Briefcase Build & Distribution
+
+### 6.1 Build Configuration
+
+- [ ] Finalize Briefcase configuration for all platforms
+- [ ] Configure app icons and metadata
+- [ ] Set up code signing (if needed)
+- [ ] Test builds on all target platforms
+
+### 6.2 Distribution Setup
+
+- [ ] Configure GitHub Actions for automated builds
+- [ ] Set up PyPI wheel distribution with binaries
+- [ ] Configure GitHub releases for direct downloads
+- [ ] Test installation from both sources
+
+### 6.3 Documentation Updates
+
+- [ ] Update README.md for new installation methods
+- [ ] Update configuration documentation
+- [ ] Add migration guide from old version
+- [ ] Document new features and breaking changes
+
+## Phase 7: Release Preparation
+
+### 7.1 Breaking Change Warning Release
+
+- [ ] Create patch release (e.g., 4.4.3) with breaking change warning
+- [ ] Update existing users about upcoming changes
+- [ ] Provide timeline for new version release
+- [ ] Ensure clear migration path documentation
+
+### 7.2 Final Release
+
+- [ ] Complete all testing and validation
+- [ ] Prepare release notes with full changelog
+- [ ] Tag new major version release
+- [ ] Deploy to PyPI and GitHub releases
+- [ ] Monitor for issues and provide support
+
+## Phase 8: Post-Release
+
+### 8.1 User Support
+
+- [ ] Monitor for bug reports
+- [ ] Help users with migration issues
+- [ ] Address any platform-specific problems
+- [ ] Collect feedback for future improvements
+
+### 8.2 Future Planning
+
+- [ ] Plan custom AWS library to replace boto3
+- [ ] Evaluate additional Textual features to implement
+- [ ] Consider new features for next release
+- [ ] Document lessons learned
+
+---
+
+## Current Status: Phase 1.1 - Breaking Change Warning Release
+
+**Next Steps:**
+
+1. Update update notification text with breaking change warning
+2. Test the warning message
+3. Release patch version 4.4.3 to PyPI
+
+**Blockers:** None currently identified
+
+**Notes:**
+
+- Keep AGENTS.md updated with any preference changes
+- Each phase should be tested before moving to the next
+- Breaking change warning gives users time to prepare
diff --git a/d3ploy/d3ploy.py b/d3ploy/d3ploy.py
@@ -24,7 +24,7 @@
 from colorama import init as colorama_init
 from tqdm import tqdm
 
-VERSION = "4.4.2"
+VERSION = "4.4.3"
 
 VALID_ACLS = [
     "private",
@@ -183,7 +183,11 @@ def check_for_updates(
                             f"There has been an update for d3ploy. Version "
                             f"{pypi_version} is now available.\n"
                             f"Please see https://github.com/dryan/d3ploy or run "
-                            f"`pip install --upgrade d3ploy`."
+                            f"`pip install --upgrade d3ploy`.\n\n"
+                            f"⚠️  IMPORTANT: A major update with breaking changes is coming soon! ⚠️\n"
+                            f"The next major version will include significant improvements but may\n"
+                            f"require config file updates. Please check the GitHub repository for\n"
+                            f"migration guidance before upgrading to version 5.0+."
                         ),
                         color=colorama.Fore.YELLOW,
                     )
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "d3ploy"
-version = "4.4.2"
+version = "4.4.3"
 description = "Easily deploy to S3 with multiple environment support."
 authors = [
     {name = "dryan", email = "dryan@users.noreply.github.com"},
