cherry-files-toolkit 0.1.0__tar.gz

cherry_files_toolkit-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__
+.venv
+dist/
+*.egg-info/

cherry_files_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nelson Urrutia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cherry_files_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: cherry-files-toolkit
+Version: 0.1.0
+Summary: TUI toolkit for cherry-picking files between git branches
+Project-URL: Repository, https://github.com/NelsonUrrutia/cherry-files-toolkit
+Author-email: Nelson Urrutia <nelurrutia15@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Nelson Urrutia
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: textual
+Description-Content-Type: text/markdown
+
+# Cherry Files Toolkit
+
+> A terminal UI (built with [Textual](https://textual.textualize.io/)) for moving
+> work between git branches at the **file** level — pick the final state of the
+> files you want and apply them to another branch as one clean commit, no
+> commit-by-commit cherry-picking.
+
+It ships two tools side by side:
+
+- **Cherry Files Picker** — select files from your current branch and commit
+  their current content onto a target branch.
+- **Cherry Files Diff** — see every file added, modified, or deleted on a
+  branch since it diverged from its base, grouped as a scannable tree.
+
+## The idea
+
+This project is a new iteration of my previous
+[Cherry Files Picker](https://github.com/NelsonUrrutia/cherry-files-picker).
+The goal is the same — move the final state of selected files between branches
+as one clean commit — but this version upgrades the UI to a full TUI and adds
+a second module, **Cherry Files Diff**, for understanding branch divergence at
+a glance.
+
+## Install
+
+```bash
+pip install cherry-files-toolkit
+```
+
+Requires Python 3.10+ and `git` on your PATH.
+
+## Usage
+
+Run it from inside any git repository:
+
+```bash
+cherry-files-toolkit
+```
+
+Press `Ctrl+Q` to quit.
+
+### Cherry Files Picker (right panel)
+
+Transfers the final approved state of selected files from your working branch
+to another branch:
+
+1. **Source branch** is pre-filled with your current branch.
+2. Pick a **target branch** — where the work should land.
+3. Search and select the **files** to move. Selections persist while you
+   filter.
+4. Write a **commit title and description**, review the selected files, and
+   hit **Cherry Pick Files**. The toolkit commits those files' current
+   content onto the target branch in a single commit.
+
+Use it when you know which files are done and want them on another branch
+without replaying the messy commit history that produced them.
+
+### Cherry Files Diff (left panel)
+
+Explains branch divergence at the file level, so you can recover context on a
+branch you don't know well:
+
+1. Pick the **divergent branch** (the one with the work) and its **base
+   branch**.
+2. **Start Diff Checker** finds the point where they diverged and lists every
+   file created, modified, or deleted since — with per-category counts and a
+   directory tree for fast scanning.
+
+## License
+
+[MIT](LICENSE)

cherry_files_toolkit-0.1.0/README.md

@@ -0,0 +1,71 @@
+# Cherry Files Toolkit
+
+> A terminal UI (built with [Textual](https://textual.textualize.io/)) for moving
+> work between git branches at the **file** level — pick the final state of the
+> files you want and apply them to another branch as one clean commit, no
+> commit-by-commit cherry-picking.
+
+It ships two tools side by side:
+
+- **Cherry Files Picker** — select files from your current branch and commit
+  their current content onto a target branch.
+- **Cherry Files Diff** — see every file added, modified, or deleted on a
+  branch since it diverged from its base, grouped as a scannable tree.
+
+## The idea
+
+This project is a new iteration of my previous
+[Cherry Files Picker](https://github.com/NelsonUrrutia/cherry-files-picker).
+The goal is the same — move the final state of selected files between branches
+as one clean commit — but this version upgrades the UI to a full TUI and adds
+a second module, **Cherry Files Diff**, for understanding branch divergence at
+a glance.
+
+## Install
+
+```bash
+pip install cherry-files-toolkit
+```
+
+Requires Python 3.10+ and `git` on your PATH.
+
+## Usage
+
+Run it from inside any git repository:
+
+```bash
+cherry-files-toolkit
+```
+
+Press `Ctrl+Q` to quit.
+
+### Cherry Files Picker (right panel)
+
+Transfers the final approved state of selected files from your working branch
+to another branch:
+
+1. **Source branch** is pre-filled with your current branch.
+2. Pick a **target branch** — where the work should land.
+3. Search and select the **files** to move. Selections persist while you
+   filter.
+4. Write a **commit title and description**, review the selected files, and
+   hit **Cherry Pick Files**. The toolkit commits those files' current
+   content onto the target branch in a single commit.
+
+Use it when you know which files are done and want them on another branch
+without replaying the messy commit history that produced them.
+
+### Cherry Files Diff (left panel)
+
+Explains branch divergence at the file level, so you can recover context on a
+branch you don't know well:
+
+1. Pick the **divergent branch** (the one with the work) and its **base
+   branch**.
+2. **Start Diff Checker** finds the point where they diverged and lists every
+   file created, modified, or deleted since — with per-category counts and a
+   directory tree for fast scanning.
+
+## License
+
+[MIT](LICENSE)

cherry_files_toolkit-0.1.0/TODO.md

@@ -0,0 +1,15 @@
+# TODO
+
+## Cherry Files Diff
+
+- Preview created and modified files content
+  - Navigate with arrow keys
+  - Press enter or click the file name
+  - Show file diff content in a popup
+- Search for refactor opportunities
+
+## Cherry Pick Files
+
+- Improve UI
+- Get data from the commit content
+- Start git steps

cherry_files_toolkit-0.1.0/cherry-files-diff.sh

@@ -0,0 +1,275 @@
+#!/usr/bin/env bash
+# Show all files created, modified, or deleted on a branch relative to a base branch.
+# Usage: cherry-files-diff [branch-name] [--base <base-branch>] [--tree] [--no-color] [--help]
+
+set -euo pipefail
+
+# ── Help ───────────────────────────────────────────────────────────────────────
+for arg in "$@"; do
+  if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
+    cat <<'EOF'
+cherry-files-diff — Show all files changed on a branch, grouped by folder.
+
+USAGE
+  cherry-files-diff [branch] [--base <base-branch>] [--tree] [--no-color] [--help]
+
+ARGUMENTS
+  branch              Branch to inspect. Defaults to the current branch.
+
+FLAGS
+  --base <branch>     Branch to compare against. Defaults to "main".
+  --tree              Output as a file tree (ideal for saving to a file).
+  --no-color          Disable color output (also auto-disabled when piping).
+  -h, --help          Show this help message.
+
+EXAMPLES
+  cherry-files-diff
+      Compare the current branch against main.
+
+  cherry-files-diff my-feature --base develop
+      Compare my-feature against develop.
+
+  cherry-files-diff --tree > changes.txt
+      Save a tree-formatted plain-text report to a file.
+
+OUTPUT
+  Files are grouped by top-level folder and categorized as:
+    +  CREATED   — files added on the branch
+    ~  MODIFIED  — files changed on the branch
+    -  DELETED   — files removed on the branch
+EOF
+    exit 0
+  fi
+done
+
+# ── Color support ──────────────────────────────────────────────────────────────
+USE_COLOR=true
+for arg in "$@"; do
+  [[ "$arg" == "--no-color" ]] && USE_COLOR=false
+done
+[[ "${NO_COLOR:-}" != "" ]] && USE_COLOR=false
+[ -t 1 ] || USE_COLOR=false
+if $USE_COLOR && ! tput colors &>/dev/null 2>&1; then
+  USE_COLOR=false
+fi
+
+if $USE_COLOR; then
+  GREEN="\033[0;32m"
+  YELLOW="\033[0;33m"
+  RED="\033[0;31m"
+  BOLD="\033[1m"
+  DIM="\033[2m"
+  RESET="\033[0m"
+else
+  GREEN="" YELLOW="" RED="" BOLD="" DIM="" RESET=""
+fi
+
+err() { printf "${RED}ERROR:${RESET} %s\n" "$*" >&2; }
+
+# ── Guard: must be inside a git repo ──────────────────────────────────────────
+if ! git rev-parse --git-dir &>/dev/null; then
+  err "Not inside a git repository."
+  exit 1
+fi
+
+# ── Parse arguments ───────────────────────────────────────────────────────────
+BRANCH=""
+BASE="main"
+TREE=false
+skip_next=false
+
+for arg in "$@"; do
+  if $skip_next; then
+    BASE="$arg"
+    skip_next=false
+    continue
+  fi
+  case "$arg" in
+  --no-color | --help | -h) ;;
+  --tree) TREE=true ;;
+  --base) skip_next=true ;;
+  *) [[ -z "$BRANCH" ]] && BRANCH="$arg" ;;
+  esac
+done
+
+if [[ -z "$BRANCH" ]]; then
+  BRANCH=$(git rev-parse --abbrev-ref HEAD)
+  printf "${DIM}No branch specified. Using current branch: %s${RESET}\n" "$BRANCH"
+fi
+
+# ── Guard: branches must exist ────────────────────────────────────────────────
+branch_exists() {
+  git show-ref --verify --quiet "refs/heads/$1" ||
+    git show-ref --verify --quiet "refs/remotes/origin/$1"
+}
+
+if ! branch_exists "$BRANCH"; then
+  err "Branch '$BRANCH' not found locally or on origin."
+  echo ""
+  echo "Available local branches:"
+  git branch --list | sed 's/^/  /'
+  exit 1
+fi
+
+if ! branch_exists "$BASE"; then
+  err "Base branch '$BASE' not found locally or on origin."
+  echo ""
+  echo "Available local branches:"
+  git branch --list | sed 's/^/  /'
+  exit 1
+fi
+
+# ── Guard: branch and base must differ ────────────────────────────────────────
+if [[ "$BRANCH" == "$BASE" ]]; then
+  err "Branch and base are both '$BRANCH'. Select a different branch to compare."
+  exit 1
+fi
+
+# ── Find divergence point ─────────────────────────────────────────────────────
+MERGE_BASE=$(git merge-base "$BASE" "$BRANCH" 2>/dev/null) || {
+  err "Could not compute merge-base between '$BASE' and '$BRANCH'."
+  exit 1
+}
+MERGE_BASE_SHORT="${MERGE_BASE:0:8}"
+
+echo ""
+printf "${BOLD}Branch diff: %s${RESET}\n" "$BRANCH"
+printf "${DIM}Comparing from merge-base %s (where %s diverged from %s)${RESET}\n" "$MERGE_BASE_SHORT" "$BRANCH" "$BASE"
+echo ""
+
+# ── Get all changed files ─────────────────────────────────────────────────────
+DIFF_OUTPUT=$(git diff --name-status "$MERGE_BASE".."$BRANCH" 2>/dev/null)
+
+if [[ -z "$DIFF_OUTPUT" ]]; then
+  printf "${DIM}No file changes found between '%s' and '%s'.${RESET}\n" "$BASE" "$BRANCH"
+  exit 0
+fi
+
+# ── Parse into buckets ────────────────────────────────────────────────────────
+ADDED=$(echo "$DIFF_OUTPUT" | awk '$1 == "A" {print $2}')
+MODIFIED=$(echo "$DIFF_OUTPUT" | awk '$1 == "M" {print $2}')
+DELETED=$(echo "$DIFF_OUTPUT" | awk '$1 == "D" {print $2}')
+
+count() { [[ -z "$1" ]] && echo 0 || echo "$1" | grep -c .; }
+COUNT_A=$(count "$ADDED")
+COUNT_M=$(count "$MODIFIED")
+COUNT_D=$(count "$DELETED")
+COUNT_TOTAL=$((COUNT_A + COUNT_M + COUNT_D))
+
+# ── Summary header ────────────────────────────────────────────────────────────
+printf "${BOLD}Summary:${RESET}  "
+printf "${GREEN}+%d created${RESET}  " "$COUNT_A"
+printf "${YELLOW}~%d modified${RESET}  " "$COUNT_M"
+printf "${RED}%s deleted${RESET}\n" "-${COUNT_D}"
+echo ""
+
+# ── Tree output ───────────────────────────────────────────────────────────────
+print_as_tree() {
+  local files="$1" label="$2" cat_conn="$3" cat_pipe="$4"
+
+  printf "%s %s\n" "$cat_conn" "$label"
+
+  local folder_arr=()
+  while IFS= read -r line; do
+    folder_arr+=("$line")
+  done < <(echo "$files" | awk -F'/' 'NF > 1 {print $1} NF == 1 {print "(root)"}' | sort -u)
+
+  local nfolders=${#folder_arr[@]}
+  local fi
+  for ((fi = 0; fi < nfolders; fi++)); do
+    local folder="${folder_arr[$fi]}"
+    local folder_conn="├──" folder_pipe="│   "
+    if [[ $fi -eq $((nfolders - 1)) ]]; then
+      folder_conn="└──"
+      folder_pipe="    "
+    fi
+
+    local folder_files
+    if [[ "$folder" == "(root)" ]]; then
+      folder_files=$(echo "$files" | awk -F'/' 'NF == 1')
+    else
+      folder_files=$(echo "$files" | awk -v f="$folder/" 'index($0, f) == 1 {print substr($0, length(f)+1)}')
+    fi
+
+    local file_arr=()
+    while IFS= read -r line; do
+      file_arr+=("$line")
+    done <<<"$folder_files"
+
+    local nfiles=${#file_arr[@]}
+    printf "%s %s %s/ (%d)\n" "$cat_pipe" "$folder_conn" "$folder" "$nfiles"
+
+    local fj
+    for ((fj = 0; fj < nfiles; fj++)); do
+      local file_conn="├──"
+      if [[ $fj -eq $((nfiles - 1)) ]]; then file_conn="└──"; fi
+      printf "%s %s %s %s\n" "$cat_pipe" "$folder_pipe" "$file_conn" "${file_arr[$fj]}"
+    done
+  done
+}
+
+# ── Grouped output ────────────────────────────────────────────────────────────
+print_by_folder() {
+  local files="$1" prefix="$2" color="$3"
+
+  local folders
+  folders=$(echo "$files" | awk -F'/' 'NF > 1 {print $1} NF == 1 {print "(root)"}' | sort -u)
+
+  while IFS= read -r folder; do
+    local folder_files folder_count
+    if [[ "$folder" == "(root)" ]]; then
+      folder_files=$(echo "$files" | awk -F'/' 'NF == 1')
+    else
+      folder_files=$(echo "$files" | awk -v f="$folder/" 'index($0, f) == 1 {print substr($0, length(f)+1)}')
+    fi
+    folder_count=$(echo "$folder_files" | grep -c .)
+    printf "  ${BOLD}%s/${RESET} ${DIM}(%d)${RESET}\n" "$folder" "$folder_count"
+    echo "$folder_files" | while IFS= read -r fname; do
+      printf "    ${color}%s${RESET} %s\n" "$prefix" "$fname"
+    done
+  done <<<"$folders"
+  echo ""
+}
+
+if $TREE; then
+  printf "%s (vs %s)\n" "$BRANCH" "$BASE"
+
+  cat_arr=()
+  if [[ $COUNT_A -gt 0 ]]; then cat_arr+=("A"); fi
+  if [[ $COUNT_M -gt 0 ]]; then cat_arr+=("M"); fi
+  if [[ $COUNT_D -gt 0 ]]; then cat_arr+=("D"); fi
+
+  ncats=${#cat_arr[@]}
+  for ((ci = 0; ci < ncats; ci++)); do
+    cat_conn="├──"
+    cat_pipe="│  "
+    if [[ $ci -eq $((ncats - 1)) ]]; then
+      cat_conn="└──"
+      cat_pipe="   "
+    fi
+    case "${cat_arr[$ci]}" in
+    A) print_as_tree "$ADDED" "CREATED ($COUNT_A)" "$cat_conn" "$cat_pipe" ;;
+    M) print_as_tree "$MODIFIED" "MODIFIED ($COUNT_M)" "$cat_conn" "$cat_pipe" ;;
+    D) print_as_tree "$DELETED" "DELETED ($COUNT_D)" "$cat_conn" "$cat_pipe" ;;
+    esac
+  done
+  echo ""
+else
+  if [[ $COUNT_A -gt 0 ]]; then
+    printf "${GREEN}${BOLD}CREATED (%d)${RESET}\n" "$COUNT_A"
+    print_by_folder "$ADDED" "+" "$GREEN"
+  fi
+  if [[ $COUNT_M -gt 0 ]]; then
+    printf "${YELLOW}${BOLD}MODIFIED (%d)${RESET}\n" "$COUNT_M"
+    print_by_folder "$MODIFIED" "~" "$YELLOW"
+  fi
+  if [[ $COUNT_D -gt 0 ]]; then
+    printf "${RED}${BOLD}DELETED (%d)${RESET}\n" "$COUNT_D"
+    print_by_folder "$DELETED" "-" "$RED"
+  fi
+fi
+
+# ── Footer ────────────────────────────────────────────────────────────────────
+printf "${BOLD}Total: %d files touched on '%s'${RESET}\n" "$COUNT_TOTAL" "$BRANCH"
+printf "${DIM}(merge-base: %s)${RESET}\n" "$MERGE_BASE_SHORT"
+echo ""

cherry_files_toolkit-0.1.0/cherry-files-toolkit.md

@@ -0,0 +1,176 @@
+# Cherry Files Toolkit — Requirements & Implementation Checklist
+
+## Overview
+
+Two separate bash CLI tools that together form a git file workflow toolkit:
+
+| Tool                  | Command                                                              | Purpose                                                                                                          |
+| --------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `cherry-files-diff`   | `cherry-files-diff [branch] [--base <branch>] [--tree] [--no-color]` | Show all files changed on a branch vs a base, grouped by folder                                                  |
+| `cherry-files-picker` | `cherry-files-picker`                                                | Interactive TUI to cherry-pick specific files from a source branch into a target branch as a single clean commit |
+
+1. Now — Python: Enhance cherry-files-picker with the diff integration (show changed files as a selectable list, manual entry below). Publish to PyPI when ready.
+2. Later — Bash: Rewrite as a learning exercise, zero deps, distribution-friendly single file.
+
+---
+
+## Tool 1 — cherry-files-diff
+
+### What it is
+
+Already built. Currently installed at `~/.local/bin/branch-diff`. Needs to be renamed.
+
+### Requirements
+
+- [ ] Rename `~/.local/bin/branch-diff` → `~/.local/bin/cherry-files-diff`
+- [ ] Update the name in the script's header comment and usage line
+
+### Flags (already implemented)
+
+- `[branch]` — branch to inspect (default: current branch)
+- `--base <branch>` — branch to compare against (default: `main`)
+- `--tree` — output as a file tree
+- `--no-color` — disable color (auto-disabled when piping)
+- `-h, --help` — show help
+
+---
+
+## Tool 2 — cherry-files-picker
+
+### What it is
+
+A bash rewrite of the existing Python `cherry-files-picker` tool, enhanced with a `gum` TUI and integrated diff-based file selection.
+
+### Dependencies
+
+- `gum` by Charmbracelet — `brew install gum`
+- Script must check for `gum` on startup and print install instructions if missing
+
+### Install location
+
+`~/.local/bin/cherry-files-picker`
+
+---
+
+## cherry-files-picker — Detailed Requirements
+
+### Startup
+
+- [ ] Check `gum` is installed; print `brew install gum` and exit 1 if not
+- [ ] Check we're inside a git repo; styled error + exit 1 if not
+- [ ] Display branded header using `gum style --border rounded`
+
+---
+
+### Step 1 — Branch Settings
+
+- [ ] Show section header: `── 1. BRANCH SETTINGS ──`
+- [ ] **Source branch** — `gum choose` from `git branch --list` output
+- [ ] **Base branch** — `gum choose` with `main` pre-highlighted (used for diff computation)
+- [ ] **Target branch** — `gum choose` from branch list
+- [ ] Guard: source branch ≠ target branch; show error and exit 1 if equal
+
+---
+
+### Step 2 — File Selection
+
+- [ ] Show section header: `── 2. FILE SELECTION ──`
+
+**Part A — From diff (primary)**
+
+- [ ] Compute merge base: `git merge-base "$BASE" "$SOURCE"`
+- [ ] Get changed file list: `git diff --name-only "$MERGE_BASE".."$SOURCE"`
+- [ ] If files exist: present with `gum choose --no-limit` (SPACE to toggle, ENTER to confirm)
+- [ ] If no files in diff: show a notice and skip to Part B
+
+**Part B — Manual entry (secondary, optional)**
+
+- [ ] Show prompt explaining optional manual additions
+- [ ] Loop: `gum input --placeholder "File path (leave blank to finish)"`
+- [ ] Stop loop on empty input
+- [ ] Append manual entries to selected list; skip duplicates
+
+**Validation**
+
+- [ ] Guard: at least 1 file must be selected total; show error and exit 1 if none
+
+---
+
+### Step 3 — Commit Settings
+
+- [ ] Show section header: `── 3. COMMIT SETTINGS ──`
+- [ ] **Commit title** — `gum input`, re-prompt if blank (required)
+- [ ] **Commit description** — `gum input`, re-prompt if blank (required)
+
+---
+
+### Step 4 — Summary
+
+- [ ] Show section header: `── SUMMARY ──`
+- [ ] Display source branch, base branch, target branch
+- [ ] List all selected files (bulleted)
+- [ ] Display commit title and description
+
+---
+
+### Step 5 — Confirm
+
+- [ ] `gum confirm "Continue with merge?"`
+- [ ] On cancel: print "Merge cancelled." and exit 0
+
+---
+
+### Step 6 — Execute
+
+- [ ] Create a temp directory (`mktemp -d`) for staging file contents
+- [ ] For each selected file: `git show "$SOURCE:$file" > "$TMPDIR/<index>"` (reads from source branch without switching)
+- [ ] `git checkout "$TARGET"`
+- [ ] For each file: `mkdir -p "$(dirname "$file")"` + copy from temp
+- [ ] `git add -A`
+- [ ] `git commit -m "$TITLE" -m "$DESC" -m "Source branch: $SOURCE"`
+- [ ] Clean up temp directory
+- [ ] Display styled success message
+
+---
+
+## Edge Cases
+
+| Scenario                            | Expected behavior                                         |
+| ----------------------------------- | --------------------------------------------------------- |
+| `gum` not installed                 | Error with `brew install gum` instructions, exit 1        |
+| Not in a git repo                   | Styled error, exit 1                                      |
+| Source == Target branch             | Error "Source and target must be different", exit 1       |
+| No files in diff                    | Skip Part A, go straight to manual entry                  |
+| No files selected at all            | Error "No files selected", exit 1                         |
+| Blank commit title or description   | Re-prompt until non-empty                                 |
+| User cancels at confirm             | "Merge cancelled." exit 0                                 |
+| File doesn't exist on source branch | `git show` will error; catch and report which file failed |
+
+---
+
+## Verification
+
+```bash
+# Tool 1
+cherry-files-diff --help                         # check renamed correctly
+cherry-files-diff --base main                    # verify output unchanged
+
+# Tool 2 — happy path
+cd ~/Documents/GitHub/Retheme-Half-Magic
+cherry-files-picker
+# 1. Select source: euphoria-collab-launch
+# 2. Select base: main
+# 3. Select target: stage
+# 4. Pick files from diff checkboxes
+# 5. Add one manual file path
+# 6. Enter commit title + description
+# 7. Confirm → check git log on stage shows new commit
+
+# Tool 2 — cancel
+cherry-files-picker   # proceed to confirm step → select No → exits cleanly
+
+# Tool 2 — no gum
+# Temporarily: mv $(which gum) /tmp/gum_bak
+cherry-files-picker   # should print install instructions
+# mv /tmp/gum_bak back
+```