refactor: enhance argument parsing and command completion

- Introduced a shared argument parser in `lib/args.sh` to streamline command argument handling across various commands.
- Updated command scripts to utilize the new parser, improving clarity and maintainability by reducing repetitive code.
- Enhanced completion scripts for Bash, Zsh, and Fish to reflect updated command options and improve user experience.
- Added integration tests for the argument parser to ensure functionality and reliability in command execution.

Author: helizaga

bin/gtr

@@ -22,6 +22,7 @@ resolve_script_dir() {
 
 # Source library files
 . "$GTR_DIR/lib/ui.sh"
+. "$GTR_DIR/lib/args.sh"
 . "$GTR_DIR/lib/config.sh"
 . "$GTR_DIR/lib/platform.sh"
 . "$GTR_DIR/lib/core.sh"

completions/_git-gtr

@@ -1,4 +1,6 @@
 #compdef _git-gtr git-gtr gtr
+# AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
+# Re-generate with: ./scripts/generate-completions.sh
 #
 # Zsh completion for git gtr (Git Worktree Runner)
 #
@@ -119,10 +121,10 @@ _git-gtr() {
   elif (( CURRENT >= 5 )); then
     case "$words[3]" in
       editor)
-        _arguments '--editor[Editor to use]:editor:(cursor vscode zed idea pycharm webstorm vim nvim emacs sublime nano atom none)'
+        _arguments '--editor[Editor to use]:editor:(atom cursor emacs idea nano none nvim pycharm sublime vim vscode webstorm zed)'
         ;;
       ai)
-        _arguments '--ai[AI tool to use]:tool:(aider auggie claude codex continue copilot cursor gemini opencode none)'
+        _arguments '--ai[AI tool to use]:tool:(aider auggie claude codex continue copilot cursor gemini none opencode)'
         ;;
       rm)
         _arguments \
@@ -172,15 +174,15 @@ _git-gtr() {
                 '--local[Use local git config]' \
                 '--global[Use global git config]' \
                 '--system[Use system git config]' \
-                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
+                '*:config key:(gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider)'
               ;;
             set|add|unset)
               # Write operations only support --local and --global
               # (--system may require root or appropriate file permissions)
               _arguments \
                 '--local[Use local git config]' \
                 '--global[Use global git config]' \
-                '*:config key:(gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd)'
+                '*:config key:(gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider)'
               ;;
           esac
         fi

completions/git-gtr.fish

@@ -1,3 +1,6 @@
+# AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
+# Re-generate with: ./scripts/generate-completions.sh
+#
 # Fish completion for git gtr
 #
 # This completion integrates with fish's completion system by registering completions
@@ -88,10 +91,10 @@ complete -c git -n '__fish_git_gtr_using_command list' -l porcelain -d 'Machine-
 complete -c git -n '__fish_git_gtr_using_command ls' -l porcelain -d 'Machine-readable output'
 
 # Editor command options
-complete -c git -n '__fish_git_gtr_using_command editor' -l editor -d 'Editor to use' -r -a 'cursor vscode zed idea pycharm webstorm vim nvim emacs sublime nano atom none'
+complete -c git -n '__fish_git_gtr_using_command editor' -l editor -d 'Editor to use' -r -a 'atom cursor emacs idea nano none nvim pycharm sublime vim vscode webstorm zed'
 
 # AI command options
-complete -c git -n '__fish_git_gtr_using_command ai' -l ai -d 'AI tool to use' -r -a 'aider auggie claude codex continue copilot cursor gemini opencode none'
+complete -c git -n '__fish_git_gtr_using_command ai' -l ai -d 'AI tool to use' -r -a 'aider auggie claude codex continue copilot cursor gemini none opencode'
 
 # Clean command options
 complete -c git -n '__fish_git_gtr_using_command clean' -l merged -d 'Remove worktrees with merged PRs/MRs'
@@ -132,21 +135,21 @@ complete -f -c git -n '__fish_git_gtr_using_command config' -l global -d 'Use gl
 # --system only for read operations (list, get) - write requires root
 complete -f -c git -n '__fish_git_gtr_using_command config; and __fish_git_gtr_config_is_read' -l system -d 'Use system git config'
 complete -f -c git -n '__fish_git_gtr_using_command config' -a "
-  gtr.worktrees.dir\t'Worktrees base directory'
-  gtr.worktrees.prefix\t'Worktree folder prefix'
-  gtr.defaultBranch\t'Default branch'
-  gtr.editor.default\t'Default editor'
-  gtr.editor.workspace\t'Path to workspace file (.code-workspace)'
-  gtr.ai.default\t'Default AI tool'
-  gtr.provider\t'Hosting provider (github, gitlab)'
-  gtr.copy.include\t'Files to copy'
-  gtr.copy.exclude\t'Files to exclude'
-  gtr.copy.includeDirs\t'Directories to copy (e.g., node_modules)'
-  gtr.copy.excludeDirs\t'Directories to exclude'
-  gtr.hook.postCreate\t'Post-create hook'
-  gtr.hook.preRemove\t'Pre-remove hook (abort on failure)'
-  gtr.hook.postRemove\t'Post-remove hook'
-  gtr.hook.postCd\t'Post-cd hook (shell integration only)'
+  gtr.copy.include	'Files to copy'
+  gtr.copy.exclude	'Files to exclude'
+  gtr.copy.includeDirs	'Directories to copy (e.g., node_modules)'
+  gtr.copy.excludeDirs	'Directories to exclude'
+  gtr.hook.postCreate	'Post-create hook'
+  gtr.hook.preRemove	'Pre-remove hook (abort on failure)'
+  gtr.hook.postRemove	'Post-remove hook'
+  gtr.hook.postCd	'Post-cd hook (shell integration only)'
+  gtr.editor.default	'Default editor'
+  gtr.editor.workspace	'Path to workspace file (.code-workspace)'
+  gtr.ai.default	'Default AI tool'
+  gtr.worktrees.dir	'Worktrees base directory'
+  gtr.worktrees.prefix	'Worktree folder prefix'
+  gtr.defaultBranch	'Default branch'
+  gtr.provider	'Hosting provider (github, gitlab)'
 "
 
 # Helper function to get branch names and special '1' for main repo

completions/gtr.bash

@@ -1,4 +1,7 @@
 #!/bin/bash
+# AUTO-GENERATED by scripts/generate-completions.sh — DO NOT EDIT MANUALLY
+# Re-generate with: ./scripts/generate-completions.sh
+#
 # Bash completion for git gtr
 #
 # Prerequisites:
@@ -52,7 +55,7 @@ _git_gtr() {
       if [[ "$cur" == -* ]]; then
         COMPREPLY=($(compgen -W "--editor" -- "$cur"))
       elif [ "$prev" = "--editor" ]; then
-        COMPREPLY=($(compgen -W "cursor vscode zed idea pycharm webstorm vim nvim emacs sublime nano atom none" -- "$cur"))
+        COMPREPLY=($(compgen -W "atom cursor emacs idea nano none nvim pycharm sublime vim vscode webstorm zed" -- "$cur"))
       else
         local branches all_options
         branches=$(git branch --format='%(refname:short)' 2>/dev/null || true)
@@ -64,7 +67,7 @@ _git_gtr() {
       if [[ "$cur" == -* ]]; then
         COMPREPLY=($(compgen -W "--ai" -- "$cur"))
       elif [ "$prev" = "--ai" ]; then
-        COMPREPLY=($(compgen -W "aider auggie claude codex continue copilot cursor gemini opencode none" -- "$cur"))
+        COMPREPLY=($(compgen -W "aider auggie claude codex continue copilot cursor gemini none opencode" -- "$cur"))
       else
         local branches all_options
         branches=$(git branch --format='%(refname:short)' 2>/dev/null || true)
@@ -128,15 +131,15 @@ _git_gtr() {
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "--local --global --system" -- "$cur"))
             else
-              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
+              COMPREPLY=($(compgen -W "gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider" -- "$cur"))
             fi
             ;;
           set|add|unset)
             # Write operations only support --local and --global (--system requires root)
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "--local --global" -- "$cur"))
             else
-              COMPREPLY=($(compgen -W "gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.provider gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd" -- "$cur"))
+              COMPREPLY=($(compgen -W "gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider" -- "$cur"))
             fi
             ;;
         esac

lib/adapters.sh

@@ -96,8 +96,10 @@ _load_from_ai_registry() {
   if [ -n "$info_lines_raw" ]; then
     local old_ifs="$IFS"
     IFS=';'
+    set -f  # Disable globbing during split
     # shellcheck disable=SC2086
     set -- $info_lines_raw
+    set +f
     _AI_INFO_LINES=("$@")
     IFS="$old_ifs"
   fi

lib/args.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Shared argument parser for gtr commands
+# Depends on: ui.sh (log_error, show_command_help)
+#
+# Usage:
+#   parse_args "<spec>" "$@"
+#
+# Spec format (one flag per line):
+#   --force                    # boolean flag → _arg_force=1
+#   --from: value              # value flag → _arg_from="<val>"
+#   --dry-run|-n               # aliases → _arg_dry_run=1
+#   --editor|-e                # short alias → _arg_editor=1
+#
+# Output variables:
+#   _pa_positional[]   — positional arguments (array)
+#   _pa_passthrough[]  — arguments after -- (array)
+#   _arg_<name>        — one per declared flag (hyphens → underscores)
+declare -a _pa_positional _pa_passthrough
+
+# Try to match a flag against the spec. Sets _arg_<name> and _pa_shift_count.
+# Returns 0 if matched, 1 if no match.
+_pa_match_flag() {
+  local spec="$1" flag="$2" next_val="${3:-}"
+
+  _pa_shift_count=0
+
+  local line
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+
+    # Check if spec line ends with ": value"
+    local has_value=0
+    case "$line" in
+      *": value")
+        has_value=1
+        line="${line%: value}"
+        ;;
+    esac
+
+    # Check if $flag matches any alternative in the pattern
+    local alt matched=0
+    local IFS_save="$IFS"
+    IFS="|"
+    for alt in $line; do
+      if [ "$flag" = "$alt" ]; then
+        matched=1
+        break
+      fi
+    done
+    IFS="$IFS_save"
+
+    if [ "$matched" = "1" ]; then
+      # Derive variable name from the first (canonical) pattern
+      local canonical="${line%%|*}"
+      canonical="${canonical#--}"
+      canonical="${canonical#-}"
+      canonical="${canonical//-/_}"
+
+      if [ "$has_value" = "1" ]; then
+        if [ -z "$next_val" ]; then
+          log_error "$flag requires a value"
+          exit 1
+        fi
+        eval "_arg_${canonical}=\"\$next_val\""
+        _pa_shift_count=2
+      else
+        eval "_arg_${canonical}=1"
+        _pa_shift_count=1
+      fi
+      return 0
+    fi
+  done <<EOF
+$spec
+EOF
+
+  return 1
+}
+
+# Main parser. Call from command functions as: parse_args "<spec>" "$@"
+parse_args() {
+  local _pa_spec="$1"
+  shift
+
+  _pa_positional=()
+  _pa_passthrough=()
+
+  # Reset all _arg_ variables from the spec to empty
+  local _pa_line
+  while IFS= read -r _pa_line; do
+    [ -z "$_pa_line" ] && continue
+    local _pa_clean="${_pa_line%: value}"
+    local _pa_canonical="${_pa_clean%%|*}"
+    _pa_canonical="${_pa_canonical#--}"
+    _pa_canonical="${_pa_canonical#-}"
+    _pa_canonical="${_pa_canonical//-/_}"
+    eval "_arg_${_pa_canonical}=''"
+  done <<EOF
+$_pa_spec
+EOF
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      -h|--help)
+        show_command_help
+        ;;
+      --)
+        shift
+        _pa_passthrough=("$@")
+        break
+        ;;
+      -*)
+        if _pa_match_flag "$_pa_spec" "$@"; then
+          shift "$_pa_shift_count"
+        else
+          log_error "Unknown flag: $1"
+          exit 1
+        fi
+        ;;
+      *)
+        _pa_positional+=("$1")
+        shift
+        ;;
+    esac
+  done
+}

lib/commands/adapter.sh

@@ -45,9 +45,7 @@ EOF
 }
 
 cmd_adapter() {
-  if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
-    show_command_help
-  fi
+  parse_args "" "$@"
 
   echo "Available Adapters"
   echo ""

lib/commands/ai.sh

@@ -1,38 +1,13 @@
 #!/usr/bin/env bash
+# shellcheck disable=SC2154
 
 # AI command
 cmd_ai() {
-  local identifier=""
-  local ai_tool=""
-  local -a ai_args=()
+  parse_args "--ai: value" "$@"
 
-  # Parse arguments
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --ai)
-        ai_tool="$2"
-        shift 2
-        ;;
-      --)
-        shift
-        ai_args=("$@")
-        break
-        ;;
-      -h|--help)
-        show_command_help
-        ;;
-      -*)
-        log_error "Unknown flag: $1"
-        exit 1
-        ;;
-      *)
-        if [ -z "$identifier" ]; then
-          identifier="$1"
-        fi
-        shift
-        ;;
-    esac
-  done
+  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...]"
@@ -52,7 +27,7 @@ cmd_ai() {
   fi
 
   resolve_repo_context || exit 1
-  # shellcheck disable=SC2154
+
   local repo_root="$_ctx_repo_root" base_dir="$_ctx_base_dir" prefix="$_ctx_prefix"
 
   # Load AI adapter (after context — fail fast on bad repo first)
@@ -61,12 +36,12 @@ cmd_ai() {
   # Resolve target branch
   local worktree_path branch
   resolve_worktree "$identifier" "$repo_root" "$base_dir" "$prefix" || exit 1
-  # shellcheck disable=SC2154
+
   worktree_path="$_ctx_worktree_path" branch="$_ctx_branch"
 
   log_step "Starting $ai_tool for: $branch"
-  echo "Directory: $worktree_path"
-  echo "Branch: $branch"
+  log_info "Directory: $worktree_path"
+  log_info "Branch: $branch"
 
   ai_start "$worktree_path" "${ai_args[@]}"
 }