refactor: enhance testing and command structure

- Updated CLAUDE.md to clarify testing procedures, including automated BATS tests and manual smoke tests.
- Introduced new functions in `lib/args.sh` for validating positional arguments, improving error handling in command scripts.
- Refactored `lib/copy.sh` to streamline file copying logic with a new `_expand_and_copy_pattern` function, enhancing maintainability.
- Improved `create_worktree` and related functions in `lib/core.sh` for better folder name resolution and branch checking.
- Added comprehensive tests for new and existing functionalities, ensuring robust validation of command behaviors and error handling.

Author: helizaga

CLAUDE.md

@@ -14,10 +14,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Testing
 
-This project uses **BATS tests** for core functions and **manual smoke tests** for end-to-end workflows. After any change:
+This project uses **BATS tests** for core functions and **manual smoke tests** for end-to-end workflows. CI runs ShellCheck + BATS automatically on PRs (`.github/workflows/lint.yml`).
 
 1. Run automated tests: `bats tests/`
-2. Run relevant manual smoke tests:
+2. Run a single test file: `bats tests/config.bats`
+3. Run a single test by name: `bats tests/config.bats --filter "cfg_map_to_file_key"`
+4. Run relevant manual smoke tests:
 
 ```bash
 ./bin/gtr new test-feature          # Create worktree
@@ -30,6 +32,8 @@ This project uses **BATS tests** for core functions and **manual smoke tests** f
 
 For exhaustive manual testing (hooks, copy patterns, adapters, `--force`, `--from-current`, etc.), see the full checklist in CONTRIBUTING.md or `.github/instructions/testing.instructions.md`.
 
+**Test files**: `adapters`, `config`, `copy_safety`, `integration_lifecycle`, `parse_args`, `provider`, `resolve_base_dir`, `sanitize_branch_name` (all in `tests/`). Shared fixtures in `tests/test_helper.bash`.
+
 **Tip**: Use a disposable repo for testing to avoid polluting your working tree:
 
 ```bash
@@ -42,20 +46,25 @@ mkdir -p /tmp/gtr-test && cd /tmp/gtr-test && git init && git commit --allow-emp
 ### Binary Structure
 
 - `bin/git-gtr` — Thin wrapper enabling `git gtr` subcommand invocation
-- `bin/gtr` — Entry point (~105 lines): sources libraries and commands, contains `main()` dispatcher
+- `bin/gtr` — Entry point: sources libraries and commands, contains `main()` dispatcher
 
 ### Module Structure
 
-| File               | Purpose                                                                                                     |
-| ------------------ | ----------------------------------------------------------------------------------------------------------- |
-| `lib/core.sh`      | Worktree CRUD: `create_worktree`, `remove_worktree`, `list_worktrees`, `resolve_target`, `resolve_base_dir` |
-| `lib/config.sh`    | Git config wrapper with precedence: `cfg_get`, `cfg_default`, `cfg_get_all`                                 |
-| `lib/copy.sh`      | File/directory copying with glob patterns: `copy_patterns`, `copy_directories`                              |
-| `lib/hooks.sh`     | Hook execution: `run_hooks_in` for postCreate/preRemove/postRemove                                          |
-| `lib/ui.sh`        | Logging (`log_error`, `log_info`, `log_warn`), prompts, formatting                                          |
-| `lib/platform.sh`  | OS detection, GUI helpers                                                                                   |
-| `lib/adapters.sh`  | Adapter registry, builder functions, generic fallbacks, loader functions                                    |
-| `lib/commands/*.sh` | One file per subcommand: `cmd_create`, `cmd_remove`, etc. (16 files)                                       |
+| File                | Purpose                                                                                                     |
+| ------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `lib/ui.sh`         | Logging (`log_error`, `log_info`, `log_warn`), prompts, formatting                                          |
+| `lib/args.sh`       | Shared argument parser: flag specs (`--flag`, `--flag: val`, aliases), populates `_arg_*` vars              |
+| `lib/config.sh`     | Git config wrapper with precedence: `cfg_get`, `cfg_default`, `cfg_get_all`                                 |
+| `lib/platform.sh`   | OS detection, GUI helpers                                                                                   |
+| `lib/core.sh`       | Worktree CRUD: `create_worktree`, `remove_worktree`, `list_worktrees`, `resolve_target`, `resolve_base_dir` |
+| `lib/copy.sh`       | File/directory copying with glob patterns: `copy_patterns`, `copy_directories`                              |
+| `lib/hooks.sh`      | Hook execution: `run_hooks_in` for postCreate/preRemove/postRemove                                          |
+| `lib/provider.sh`   | Remote hosting detection (GitHub/GitLab) and CLI integration for `clean --merged`                           |
+| `lib/adapters.sh`   | Adapter registry, builder functions, generic fallbacks, loader functions                                    |
+| `lib/launch.sh`     | Editor/AI launch orchestration: `_open_editor`, `_auto_launch_editor`, `_auto_launch_ai`                    |
+| `lib/commands/*.sh` | One file per subcommand: `cmd_create`, `cmd_remove`, etc. (16 files)                                        |
+
+Libraries are sourced in the order listed above (ui → args → config → ... → launch → commands/\*.sh glob).
 
 ### Adapters
 
@@ -135,6 +144,17 @@ When adding commands or flags, update all three files:
 - `completions/_git-gtr` (Zsh)
 - `completions/git-gtr.fish` (Fish)
 
+## Critical Gotcha: `set -e`
+
+`bin/gtr` runs with `set -e`. Any unguarded non-zero return silently exits the entire script. When calling functions that may `return 1`, guard with `|| true`:
+
+```bash
+result=$(my_func) || true           # Prevents silent exit
+if my_func; then ...; fi            # Also safe (if guards the return)
+```
+
+This is the most common source of subtle bugs in this codebase.
+
 ## Code Style
 
 - Shebang: `#!/usr/bin/env bash`

lib/args.sh

@@ -123,3 +123,13 @@ EOF
     esac
   done
 }
+
+# Validate that at least N positional arguments were provided.
+# Call after parse_args. Exits with error message if insufficient args.
+# Usage: require_args <min_count> "<usage message>"
+require_args() {
+  if [ "${#_pa_positional[@]}" -lt "$1" ]; then
+    log_error "$2"
+    exit 1
+  fi
+}

lib/commands/ai.sh

@@ -4,16 +4,12 @@
 # shellcheck disable=SC2154  # _arg_* _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_ai() {
   parse_args "--ai: value" "$@"
+  require_args 1 "Usage: git gtr ai <id|branch> [--ai <name>] [-- args...]"
 
-  local identifier="${_pa_positional[0]:-}"
+  local identifier="${_pa_positional[0]}"
   local ai_tool="${_arg_ai:-}"
   local -a ai_args=("${_pa_passthrough[@]}")
 
-  if [ -z "$identifier" ]; then
-    log_error "Usage: git gtr ai <id|branch> [--ai <name>] [-- args...]"
-    exit 1
-  fi
-
   # Get AI tool from flag or config (with .gtrconfig support)
   if [ -z "$ai_tool" ]; then
     ai_tool=$(_cfg_ai_default)

lib/commands/clean.sh

@@ -1,76 +1,86 @@
 #!/usr/bin/env bash
 
 # Clean command (remove prunable worktrees)
+
+# Detect hosting provider with error messaging.
+# Prints provider name on success; returns 1 on failure.
+_clean_detect_provider() {
+  local provider
+  provider=$(detect_provider) || true
+  if [ -n "$provider" ]; then
+    printf "%s" "$provider"
+    return 0
+  fi
+
+  local remote_url
+  remote_url=$(git remote get-url origin 2>/dev/null || true)
+  if [ -z "$remote_url" ]; then
+    log_error "No remote URL configured for 'origin'"
+  else
+    # Sanitize URL to avoid leaking embedded credentials (e.g., https://token@host/...)
+    local safe_url="${remote_url%%@*}"
+    if [ "$safe_url" != "$remote_url" ]; then
+      safe_url="<redacted>@${remote_url#*@}"
+    fi
+    log_error "Could not detect hosting provider from remote URL: $safe_url"
+    log_info "Set manually: git gtr config set gtr.provider github  (or gitlab)"
+  fi
+  return 1
+}
+
+# Check if a worktree should be skipped during merged cleanup.
+# Returns 0 if should skip, 1 if should process.
+# Usage: _clean_should_skip <dir> <branch>
+_clean_should_skip() {
+  local dir="$1" branch="$2"
+
+  if [ -z "$branch" ] || [ "$branch" = "(detached)" ]; then
+    log_warn "Skipping $dir (detached HEAD)"
+    return 0
+  fi
+
+  if ! git -C "$dir" diff --quiet 2>/dev/null || \
+     ! git -C "$dir" diff --cached --quiet 2>/dev/null; then
+    log_warn "Skipping $branch (has uncommitted changes)"
+    return 0
+  fi
+
+  if [ -n "$(git -C "$dir" ls-files --others --exclude-standard 2>/dev/null)" ]; then
+    log_warn "Skipping $branch (has untracked files)"
+    return 0
+  fi
+
+  return 1
+}
+
 # Remove worktrees whose PRs/MRs are merged (handles squash merges)
 # Usage: _clean_merged repo_root base_dir prefix yes_mode dry_run
 _clean_merged() {
   local repo_root="$1" base_dir="$2" prefix="$3" yes_mode="$4" dry_run="$5"
 
   log_step "Checking for worktrees with merged PRs/MRs..."
 
-  # Detect hosting provider (GitHub, GitLab, etc.)
   local provider
-  provider=$(detect_provider) || true
-  if [ -z "$provider" ]; then
-    local remote_url
-    remote_url=$(git remote get-url origin 2>/dev/null || true)
-    if [ -z "$remote_url" ]; then
-      log_error "No remote URL configured for 'origin'"
-    else
-      # Sanitize URL to avoid leaking embedded credentials (e.g., https://token@host/...)
-      local safe_url="${remote_url%%@*}"
-      if [ "$safe_url" != "$remote_url" ]; then
-        safe_url="<redacted>@${remote_url#*@}"
-      fi
-      log_error "Could not detect hosting provider from remote URL: $safe_url"
-      log_info "Set manually: git gtr config set gtr.provider github  (or gitlab)"
-    fi
-    exit 1
-  fi
-
-  # Ensure provider CLI is available and authenticated
+  provider=$(_clean_detect_provider) || exit 1
   ensure_provider_cli "$provider" || exit 1
 
-  # Fetch latest from origin
   log_step "Fetching from origin..."
   git fetch origin --prune 2>/dev/null || log_warn "Could not fetch from origin"
 
-  local removed=0
-  local skipped=0
-
-  # Get main repo branch to exclude it
+  local removed=0 skipped=0
   local main_branch
   main_branch=$(current_branch "$repo_root")
 
-  # Iterate through worktree directories
   for dir in "$base_dir/${prefix}"*; do
     [ -d "$dir" ] || continue
 
     local branch
     branch=$(current_branch "$dir") || true
 
-    if [ -z "$branch" ] || [ "$branch" = "(detached)" ]; then
-      log_warn "Skipping $dir (detached HEAD)"
-      skipped=$((skipped + 1))
-      continue
-    fi
-
-    # Skip if same as main repo branch
-    if [ "$branch" = "$main_branch" ]; then
-      continue
-    fi
-
-    # Check if worktree has uncommitted changes
-    if ! git -C "$dir" diff --quiet 2>/dev/null || \
-       ! git -C "$dir" diff --cached --quiet 2>/dev/null; then
-      log_warn "Skipping $branch (has uncommitted changes)"
-      skipped=$((skipped + 1))
-      continue
-    fi
+    # Skip main repo branch silently (not counted)
+    [ "$branch" = "$main_branch" ] && continue
 
-    # Check for untracked files
-    if [ -n "$(git -C "$dir" ls-files --others --exclude-standard 2>/dev/null)" ]; then
-      log_warn "Skipping $branch (has untracked files)"
+    if _clean_should_skip "$dir" "$branch"; then
       skipped=$((skipped + 1))
       continue
     fi
@@ -83,7 +93,6 @@ _clean_merged() {
       elif [ "$yes_mode" -eq 1 ] || prompt_yes_no "Remove worktree and delete branch '$branch'?"; then
         log_step "Removing worktree: $branch"
 
-        # Run pre-remove hooks (skip worktree on failure)
         if ! run_hooks_in preRemove "$dir" \
           REPO_ROOT="$repo_root" \
           WORKTREE_PATH="$dir" \
@@ -94,11 +103,9 @@ _clean_merged() {
         fi
 
         if remove_worktree "$dir" 0; then
-          # Delete the local branch (safe: already merged)
           git branch -d "$branch" 2>/dev/null || git branch -D "$branch" 2>/dev/null || true
           removed=$((removed + 1))
 
-          # Run post-remove hooks (worktree already removed, don't abort)
           if ! run_hooks postRemove \
             REPO_ROOT="$repo_root" \
             WORKTREE_PATH="$dir" \
@@ -111,7 +118,6 @@ _clean_merged() {
         skipped=$((skipped + 1))
       fi
     fi
-    # Branches without merged PRs are silently skipped (this is the normal case)
   done
 
   echo ""

lib/commands/editor.sh

@@ -4,15 +4,11 @@
 # shellcheck disable=SC2154  # _arg_* _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_editor() {
   parse_args "--editor: value" "$@"
+  require_args 1 "Usage: git gtr editor <id|branch> [--editor <name>]"
 
-  local identifier="${_pa_positional[0]:-}"
+  local identifier="${_pa_positional[0]}"
   local editor="${_arg_editor:-}"
 
-  if [ -z "$identifier" ]; then
-    log_error "Usage: git gtr editor <id|branch> [--editor <name>]"
-    exit 1
-  fi
-
   # Get editor from flag or config (with .gtrconfig support)
   if [ -z "$editor" ]; then
     editor=$(_cfg_editor_default)

lib/commands/go.sh

@@ -4,11 +4,7 @@
 # shellcheck disable=SC2154  # _pa_* set by parse_args, _ctx_* set by resolve_*
 cmd_go() {
   parse_args "" "$@"
-
-  if [ "${#_pa_positional[@]}" -ne 1 ]; then
-    log_error "Usage: git gtr go <id|branch>"
-    exit 1
-  fi
+  require_args 1 "Usage: git gtr go <id|branch>"
 
   local identifier="${_pa_positional[0]}"
   resolve_repo_context || exit 1

lib/commands/remove.sh

@@ -9,15 +9,12 @@ cmd_remove() {
 --force"
   parse_args "$_spec" "$@"
 
+  require_args 1 "Usage: git gtr rm <id|branch> [<id|branch>...] [--delete-branch] [--force] [--yes]"
+
   local delete_branch="${_arg_delete_branch:-0}"
   local yes_mode="${_arg_yes:-0}"
   local force="${_arg_force:-0}"
 
-  if [ ${#_pa_positional[@]} -eq 0 ]; then
-    log_error "Usage: git gtr rm <id|branch> [<id|branch>...] [--delete-branch] [--force] [--yes]"
-    exit 1
-  fi
-
   resolve_repo_context || exit 1
 
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"

lib/commands/rename.sh

@@ -8,17 +8,13 @@ cmd_rename() {
 --yes"
   parse_args "$_spec" "$@"
 
-  local old_identifier="${_pa_positional[0]:-}"
-  local new_name="${_pa_positional[1]:-}"
+  require_args 2 "Usage: git gtr mv <old> <new> [--force] [--yes]"
+
+  local old_identifier="${_pa_positional[0]}"
+  local new_name="${_pa_positional[1]}"
   local force="${_arg_force:-0}"
   local yes_mode="${_arg_yes:-0}"
 
-  # Validate arguments
-  if [ -z "$old_identifier" ] || [ -z "$new_name" ]; then
-    log_error "Usage: git gtr mv <old> <new> [--force] [--yes]"
-    exit 1
-  fi
-
   resolve_repo_context || exit 1
 
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"