help, completion: descriptive help text and bash completionv0.2.1

Add group/leaf descriptions to argparse help and richer command help
strings. Add generated bash completion (completions/firefly.bash) plus
its generator (scripts/gen_completion.py), wired into the command
checklist in CLAUDE.md and documented in the README. Bump to 0.2.1.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed, 64 insertions, 0 deletions

diff --git a/completions/firefly.bash b/completions/firefly.bash
new file mode 100644
index 0000000..c118f52
--- /dev/null
+++ b/completions/firefly.bash
@@ -0,0 +1,64 @@
+# bash completion for firefly (firefly-cli)
+# Install: source this file, or drop it in /etc/bash_completion.d/ or
+# /usr/share/bash-completion/completions/firefly
+#
+# Generated by scripts/gen_completion.py -- do not edit by hand.
+# Regenerate when commands change (see CLAUDE.md):
+#   python scripts/gen_completion.py > completions/firefly.bash
+
+_firefly() {
+    local cur prev words cword
+    _init_completion 2>/dev/null || {
+        cur="${COMP_WORDS[COMP_CWORD]}"
+        prev="${COMP_WORDS[COMP_CWORD-1]}"
+        words=("${COMP_WORDS[@]}")
+        cword=$COMP_CWORD
+    }
+
+    local global_opts="--human --url --token -h --help"
+    local groups="auth account category tag tx"
+
+    # Find the group and leaf among the words (skip the program name at 0).
+    local group="" leaf="" i
+    for ((i=1; i < cword; i++)); do
+        local w="${words[i]}"
+        case "$w" in
+            -*) ;;                      # an option, skip
+            --url|--token) ((i++));;    # option that takes a value
+            *)
+                if [[ -z $group ]]; then group="$w"
+                elif [[ -z $leaf ]]; then leaf="$w"
+                fi
+                ;;
+        esac
+    done
+
+    # Leaf-specific options.
+    local leaf_opts=""
+    case "$group $leaf" in
+        "auth set")         leaf_opts="--token --url";;
+        "account create")   leaf_opts="--currency --opening-balance --type";;
+        "account list")     leaf_opts="--type";;
+        "tx add")           leaf_opts="--category --date --desc --from --tags --to --type";;
+        "tx list")          leaf_opts="--account --limit --since --until";;
+    esac
+
+    # Leaves per group.
+    local leaves=""
+    case "$group" in
+        auth) leaves="set test";;
+        account) leaves="balance create get list";;
+        category) leaves="list";;
+        tag) leaves="list";;
+        tx) leaves="add get list search";;
+    esac
+
+    if [[ -z $group ]]; then
+        COMPREPLY=($(compgen -W "$groups $global_opts" -- "$cur"))
+    elif [[ -z $leaf ]]; then
+        COMPREPLY=($(compgen -W "$leaves" -- "$cur"))
+    else
+        COMPREPLY=($(compgen -W "$leaf_opts --help" -- "$cur"))
+    fi
+}
+complete -F _firefly firefly