chore(release): bump version to 0.2.0 and refactor to a new architecture

CHANGELOG.md

@@ -5,6 +5,104 @@ 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).
 
+## [0.2.0] - 2025-11-17
+
+### Added
+
+- **Four-Method Command Architecture**: Clear separation of responsibilities
+  - `uvup clone <source> <target>` - Create exact 1:1 copy of an environment
+  - `uvup new <name> --template <template>` - Create new project from template with modification support
+  - `uvup sync --template <template>` - Sync current project with template
+- **Template System**: Powerful project scaffolding capabilities
+  - Python version override with `--python <version>`
+  - Package filtering with `--exclude <packages>` and `--include <packages>`
+  - Custom project path with `--path <directory>`
+  - Dry-run preview mode with `--dry-run` for all template operations
+  - Full support for `[project.optional-dependencies]` in pyproject.toml
+- **Migration from pip freeze to pyproject.toml**: Modern dependency management
+  - pyproject.toml-based configuration instead of requirements.txt
+  - Lock file support via uv.lock for reproducible builds
+  - Optional dependency groups for dev tools, testing, etc.
+- **Safety Features**:
+  - Automatic backup creation in `sync` command (pyproject.toml.backup)
+  - Automatic rollback on failure (uv lock/sync errors)
+  - Preview changes before execution with `--dry-run`
+
+### Changed
+
+- **Breaking**: Replaced `uvup copy` with `uvup clone` for clearer semantics
+- Environment structure now includes:
+  - `pyproject.toml` - Project configuration and dependencies
+  - `uv.lock` - Lock file for reproducible installs
+  - `.venv/` - Virtual environment directory
+  - `hello.py` - Optional demo file
+
+### Removed
+
+- `uvup copy` command (replaced by `uvup clone`)
+- Direct pip freeze dependency management (replaced by pyproject.toml)
+
+### Documentation
+
+- Complete command reference in docs/COMMANDS.md (570 lines)
+- Real-world usage scenarios in docs/USE_CASES.md (489 lines)
+- Updated README with four-method architecture explanation
+- Simplified Core Philosophy to concise bullet points
+- Added "Documentation" section with quick help and complete docs links
+- Updated TARGET.md with v0.2.0 status and v0.3.0 planning
+
+### Technical
+
+- Enhanced `commands/new.rs` with full template modification support
+- Enhanced `commands/sync.rs` with backup and rollback mechanism
+- Refactored `commands/copy.rs` to `commands/clone.rs`
+- Added comprehensive dry-run implementation across all template commands
+- Improved dependency filtering logic with PEP 508 specifier support
+
+## [0.1.3] - 2025-11-16
+
+### Added
+
+- `uvup copy <source> <target>` - Copy an existing environment to a new one
+- `--python <version>` flag for copy command to override Python version
+
+### Changed
+
+- Upgraded `ureq` dependency from v2.x to v3.0 for improved HTTP handling
+
+### Technical
+
+- Added `commands/copy.rs` module
+- Enhanced CLI with Copy command variant
+
+## [0.1.2] - 2025-11-16
+
+### Added
+
+- `uvup update` - Self-update command to install latest version from GitHub releases
+- `uvup update --check` - Check for updates without installing
+
+### Fixed
+
+- Shell validation in deactivate command to prevent errors when called outside shell context
+
+### Technical
+
+- Added `commands/update.rs` module
+- Added GitHub release checking and binary replacement logic
+
+## [0.1.1] - 2025-11-15
+
+### Fixed
+
+- Installation script compatibility issues on macOS and Linux
+- Build target for Linux changed from `unknown-linux-gnu` to `unknown-linux-musl` for better portability
+
+### Technical
+
+- Updated installation scripts (install.sh, install.ps1)
+- Modified build configuration for Linux releases
+
 ## [0.1.0] - 2025-11-15
 
 ### Added
@@ -35,4 +133,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - clap 4.5 - CLI framework
 - dirs 6.0 - Cross-platform directory paths
 
+[0.2.0]: https://github.com/KercyDing/uvup/compare/v0.1.3...v0.2.0
+[0.1.3]: https://github.com/KercyDing/uvup/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/KercyDing/uvup/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/KercyDing/uvup/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/KercyDing/uvup/releases/tag/v0.1.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "uvup"
-version = "0.1.2"
+version = "0.2.0"
 edition = "2024"
 rust-version = "1.85"
 authors = ["KercyDing"]
@@ -19,6 +19,7 @@ ureq = { version = "3.0", features = ["json"] }
 serde_json = "1.0"
 self-replace = "1.5"
 tempfile = "3.0"
+toml_edit = "0.23"
 
 [dev-dependencies]
 

README.md

@@ -10,10 +10,10 @@ uvup aims to be a companion tool for uv, providing a familiar conda-like interfa
 
 ## Core Philosophy
 
-- **Enhancement, not replacement**: uvup calls uv for actual work
-- **User experience first**: Familiar commands and seamless activation
-- **Best practices**: Following proven patterns from conda and rustup
-- **Lightweight and cross-platform**: Single binary, works everywhere
+- **Enhancement, not replacement**: Calls uv for actual work
+- **Familiar interface**: Conda-like commands, seamless activation
+- **Single binary**: Lightweight and cross-platform
+- **Template-driven**: Reusable project configurations
 
 ## Installation
 
@@ -48,20 +48,23 @@ For detailed uninstallation instructions and manual removal, see [Uninstallation
 
 ## Planned Features
 
-### MVP (v0.1.0) - Completed
+### v0.2.0 - Completed
 
-- [x] `uvup init` - Shell integration (Bash, Zsh, Fish, PowerShell)
-- [x] `uvup create <name>` - Create environments
-- [x] `uvup activate <name>` - Activate environments (via shell hook)
-- [x] `uvup list` - List all environments
-- [x] `uvup remove <name>` - Remove environments
+- [x] `uvup clone <source> <target>` - Clone environments (1:1 exact copy)
+- [x] `uvup new <name> --template <template>` - Create projects from templates
+- [x] `uvup sync --template <template>` - Sync current project with template
+- [x] Template modification support (--python, --exclude, --include)
+- [x] Dry-run preview mode for all template operations
+- [x] pyproject.toml-based dependency management
+- [x] optional-dependencies support
 
 ### Future Versions
 
-- `uvup default <name>` - Set default environment (auto-activate on new terminal)
-- `uvup undefault` - Remove default environment
-- Installation via package managers (Homebrew, Scoop, Winget)
-- Enhanced `list` command with more environment details
+- Official template repository with curated project templates
+- `uvup template list` - Browse available official templates
+- Auto-download templates on first use
+- `uvup default <name>` - Set default environment
+- Package manager support (Homebrew, Scoop, Winget)
 
 ## Usage
 
@@ -73,8 +76,6 @@ uvup create myproject
 
 # Create with specific Python version
 uvup create myproject --python 3.12
-# or
-uvup create --python 3.12 myproject
 
 # List all environments
 uvup list
@@ -83,7 +84,7 @@ uvup list
 uvup activate myproject
 
 # Install packages (using uv)
-uv pip install numpy pandas
+uv add numpy pandas
 
 # Deactivate
 uvup deactivate
@@ -92,17 +93,124 @@ uvup deactivate
 uvup remove myproject
 ```
 
+### Environment Cloning
+
+Clone an existing environment to create an exact 1:1 copy:
+
+```bash
+# Clone an environment
+uvup clone myproject myproject-backup
+
+# The cloned environment will have identical:
+# - Python version
+# - All dependencies (from pyproject.toml)
+# - Lock file (uv.lock)
+```
+
+### Template-based Project Creation
+
+Create new projects from template environments with modification support:
+
+```bash
+# Preview changes before creating
+uvup new myapp --template web-template --dry-run
+
+# Create a project from a template
+uvup new myapp --template web-template
+
+# Create with custom Python version
+uvup new myapp --template web-template --python 3.11
+
+# Create with package filtering
+uvup new myapp --template web-template --exclude pytest,black
+uvup new myapp --template web-template --include numpy,pandas,requests
+
+# Create in a custom directory
+uvup new myapp --template web-template --path ~/projects
+```
+
+### Template Synchronization
+
+Sync an existing project with a template environment:
+
+```bash
+# Preview changes before syncing
+uvup sync --template web-template --dry-run
+
+# Sync current project with template
+cd myproject
+uvup sync --template web-template
+
+# Sync with Python version override
+uvup sync --template web-template --python 3.11
+
+# Sync with package filtering
+uvup sync --template web-template --exclude dev-packages
+uvup sync --template web-template --include numpy,pandas
+```
+
+### Command Categories
+
+uvup provides four distinct command categories:
+
+1. **Create** - Create empty environments
+   ```bash
+   uvup create myenv --python 3.12
+   ```
+
+2. **Clone** - 1:1 exact copy (no modifications)
+   ```bash
+   uvup clone source-env target-env
+   ```
+
+3. **New** - Create projects from templates (with modifications)
+   ```bash
+   uvup new myproject --template base-template --exclude pytest
+   ```
+
+4. **Sync** - Update current project from template (with modifications)
+   ```bash
+   uvup sync --template base-template --python 3.11
+   ```
+
+For complete command reference with all options and examples, see [COMMANDS.md](docs/COMMANDS.md).
+
+## Documentation
+
+### Quick Help
+
+Use the built-in help system for command-specific usage:
+
+```bash
+# General help
+uvup --help
+
+# Command-specific help
+uvup new --help
+uvup sync --help
+uvup clone --help
+```
+
+### Complete Documentation
+
+- **[COMMANDS.md](docs/COMMANDS.md)** - Complete command reference with all options and examples
+- **[USE_CASES.md](docs/USE_CASES.md)** - Real-world usage scenarios and workflows
+- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes
+
 ## Scope
 
-uvup focuses on **environment management only**. For package management, use uv directly:
+uvup focuses on **environment management and template-based workflows**. For package management, use uv directly:
 
 ```bash
 # Environment management with uvup
 uvup create myproject
 uvup activate myproject
 
 # Package management with uv
-uv pip install numpy pandas
+uv add numpy pandas
+uv remove pandas
+uv lock
+uv sync
 ```
 
 ## IDE Integration