feat: add smart-merge to enhance command

[eliasecchig]

Summary

• Add 3-way comparison smart-merge to the enhance command
• Move backups from in-project .backup_* directories to ~/.agent-starter-pack/backups/
• Create shared backup utility used by both create --in-folder and enhance (smart-merge)
• Extract shared merge utilities into cli/utils/merge.py for reuse across commands

Changes

Smart-merge (3-way comparison)

• When saved project metadata exists, enhance compares current project against old + new templates
• Files the user hasn't modified are auto-updated; files ASP didn't change are preserved; conflicts are surfaced
• Agent code and config files are never modified
• Dependency merging preserves user-added packages while updating ASP-managed ones
• --dry-run flag previews changes without applying
• --force flag bypasses smart-merge for brute-force overwrite

External backups

• New shared utility agent_starter_pack/cli/utils/backup.py with create_project_backup()
• Backups stored at ~/.agent-starter-pack/backups/<project>_<timestamp>/
• Excludes .git, .venv, node_modules, __pycache__, etc.
• Handles failures gracefully: auto-approve continues silently, interactive mode prompts
• Both create (--in-folder) and enhance (smart-merge) use the same backup utility

Other

• Remove starter_pack_* file preservation logic (replaced by smart-merge)
• Remove .backup_* from gitignore patterns and file exclusion lists
• Refactored upgrade command to import from shared cli/utils/merge.py

How smart-merge works

1. Read saved metadata from pyproject.toml ([tool.agent-starter-pack])
2. Regenerate the "old" template (original generation params) into a temp dir
3. Generate the "new" template (with enhance overrides) into a temp dir
4. For each file, 3-way compare current_project vs old_template vs new_template:
   • current == old → user didn't modify → safe to overwrite with new
   • current != old and old == new → user modified, template unchanged → preserve
   • current != old and old != new → both changed → conflict (prompt or auto-keep)
   • File only in new → always add
   • File only in old → prompt to delete
5. Back up the project to ~/.agent-starter-pack/backups/ before applying changes

[gemini-code-assist]

Summary of Changes

Hello @eliasecchig, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the enhance command by integrating a robust smart-merge mechanism. This change allows the command to intelligently update project files, preserving user modifications while applying template enhancements. It also introduces --force for brute-force overwrites and --dry-run for previewing changes, making the enhance process safer and more transparent. The underlying merge logic has been centralized into a new utility module, promoting code reusability and maintainability across related CLI commands.

Highlights

• Smart-Merge for Enhance Command: Implemented a 3-way comparison smart-merge feature for the enhance command, leveraging existing upgrade command infrastructure to intelligently update project files while preserving user modifications.
• Shared Merge Utilities: Extracted common merge utilities (template generation, result display, conflict resolution, file copying) into a new cli/utils/merge.py module for improved code reuse and maintainability across both enhance and upgrade commands.
• New CLI Flags: Added --force and --dry-run command-line flags to the enhance command, allowing users to bypass smart-merge for brute-force overwrites or preview changes without applying them.
• Enhanced Test Coverage: Introduced comprehensive unit tests for the new _build_enhance_create_args function and the TestSmartMerge and TestSmartMergeFallback scenarios, ensuring robustness of the new merge logic and fallback behaviors.

Changelog

• agent_starter_pack/cli/commands/enhance.py
  • Imported shutil, tempfile, metadata_to_cli_args, and merge utilities (apply_changes, display_results, run_create_command, compare_all_files, group_results_by_action, merge_pyproject_dependencies, write_merged_dependencies).
  • Added _build_enhance_create_args function to convert project configuration and CLI overrides into create command arguments.
  • Implemented _run_smart_merge function to orchestrate the 3-way comparison, template generation, and conflict resolution.
  • Integrated smart-merge logic into the enhance command, with fallbacks for --force or missing metadata.
  • Added --force and --dry-run options to the enhance CLI command.
• agent_starter_pack/cli/commands/upgrade.py
  • Removed difflib and shlex imports.
  • Removed previously defined _run_create_command, _display_results, _handle_conflict, _copy_file, and _apply_changes functions.
  • Imported apply_changes, display_results, and run_create_command from the new ../utils/merge.py module.
  • Updated calls to use the newly imported shared merge functions.
  • Removed the MAX_DIFF_DISPLAY_CHARS constant.
• agent_starter_pack/cli/utils/merge.py
  • Added new file containing shared merge utilities.
  • Defined run_create_command for generating templates.
  • Defined display_results for presenting comparison outcomes.
  • Defined handle_conflict for interactive conflict resolution.
  • Defined copy_file for copying files with directory creation.
  • Defined MAX_DIFF_DISPLAY_CHARS constant for diff display limits.
• tests/cli/commands/test_enhance.py
  • Imported re and _build_enhance_create_args.
  • Added strip_ansi helper function for cleaning test output.
  • Added TestBuildEnhanceCreateArgs class with tests for metadata conversion, CLI override precedence, and skip value filtering.
  • Added TestSmartMerge class with tests for auto-updating unchanged files, preserving user modifications, detecting conflicts, adding new files, and dry-run functionality.
  • Added TestSmartMergeFallback class with tests for --force flag behavior, no-metadata fallback, --dry-run error cases, and smart-merge failure fallback.
• tests/cli/commands/test_upgrade.py
  • Modified existing @patch decorators in various test methods to reference run_create_command from the shared agent_starter_pack.cli.commands.upgrade.run_create_command utility.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a valuable smart-merge capability to the enhance command, significantly improving the user experience when updating projects. The refactoring of shared logic from the upgrade command into a new cli/utils/merge.py module is a great step towards better code organization and reuse. The addition of --force and --dry-run flags provides useful control over the enhancement process. The new tests are comprehensive and cover various scenarios, including success cases, conflicts, and fallback mechanisms. I have one suggestion to improve the readability of a loop, but overall this is a solid contribution.