annn

#!/usr/bin/env bash
# annn - Annotation helper for Taskwarrior
# version 0.5.2
#
# Usage:
#   annn <id>                    Open $EDITOR for a new annotation
#   annn <id>.                   List all annotations with index numbers
#   annn <id>.<N>                Edit annotation N in $EDITOR
#   annn <id>.<N> text...        Edit annotation N, pre-populated with text
#   annn -<id>.<N>               Remove annotation N (with confirmation)
#   annn <id> text...            Annotate directly, no editor
#   echo "text" | annn <id>      Annotate from pipe, no editor
#
# Designed for Taskwarrior 2.6.2
# License: MIT

set -euo pipefail

readonly VERSION="0.7.0"
readonly SCRIPT_NAME="$(basename "$0")"
readonly EDITOR="${EDITOR:-vim}"

# Global tmpfile for trap cleanup (avoids "unbound variable" with set -u)
tmpfile=""
trap 'rm -f "$tmpfile"' EXIT

# ============================================================================
# Helpers
# ============================================================================

usage() {
    cat <<EOF
Usage: $SCRIPT_NAME <id>[.<N>] [text...]

  $SCRIPT_NAME <id>                    New annotation (opens \$EDITOR)
  $SCRIPT_NAME <id> text...            New annotation, no editor
  $SCRIPT_NAME <id>.                   List annotations
  $SCRIPT_NAME <id>.<N>                Edit annotation N (opens \$EDITOR)
  $SCRIPT_NAME <id>.<N> text...        Edit annotation N, pre-populated with text
  $SCRIPT_NAME -<id>.<N>               Remove annotation N (requires index)
  echo "text" | $SCRIPT_NAME <id>      Annotate from pipe, no editor

  <id> must be a plain integer or UUID — no filters, tags, or project expressions.

Examples:
  $SCRIPT_NAME 42                      Add new annotation to task 42
  $SCRIPT_NAME 42 Fixed the bug        Inline annotation, no editor
  $SCRIPT_NAME 42.                     List annotations on task 42
  $SCRIPT_NAME 42.1                    Edit first annotation on task 42
  $SCRIPT_NAME 42.1 see ticket #99     Edit annotation 1, pre-populated
  $SCRIPT_NAME -42.1                   Remove first annotation from task 42
  echo "quick note" | $SCRIPT_NAME 42  Pipe a one-liner

Options:
  -h, --help       Show this help
  -v, --version    Show version
EOF
    exit 0
}

die() {
    echo "[annn] ERROR: $*" >&2
    exit 1
}

msg() {
    echo "[annn] $*"
}

# ============================================================================
# Load label template into tmpfile, or fall back to bare "label: " prefix
# Template file: ~/.task/templates/<label>.md (case-insensitive label match)
# ============================================================================

load_template() {
    local label="${1,,}"   # lowercase
    local tfile="${HOME}/.task/templates/${label}.md"
    if [[ -f "$tfile" ]]; then
        echo "$tfile"
    fi
}

populate_tmpfile_for_label() {
    local label="$1"
    local template
    template=$(load_template "$label")
    if [[ -n "$template" ]]; then
        cp "$template" "$tmpfile"
    else
        printf '%s: ' "$label" > "$tmpfile"
    fi
}

# ============================================================================
# Read-only task query — rc.hooks=off prevents cascading hook invocations
# ============================================================================

task_get() {
    task rc.hooks=off rc.verbose=nothing _get "$@" 2>/dev/null
}

# ============================================================================
# Validate that a value is a plain integer (task ID)
# ============================================================================

is_integer() {
    [[ "$1" =~ ^[0-9]+$ ]]
}

# ============================================================================
# Validate that a value is a UUID
# ============================================================================

is_uuid() {
    [[ "$1" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]]
}

# ============================================================================
# Validate a label name: letters/digits/hyphens, starting with a letter.
# 'note' is reserved for tasknotes.
# ============================================================================

is_label() {
    [[ "$1" =~ ^[a-zA-Z][a-zA-Z0-9_-]*$ ]] && [[ "${1,,}" != "note" ]]
}

# ============================================================================
# Validate arg1 is a strict ID or ID.N form — no filters, tags, or keywords
# Accepts: 42  42.  42.3  -42.3  42.label  -42.label  <uuid>
# ============================================================================

validate_id_arg() {
    local arg="$1"

    # Remove leading minus for remove-mode check
    local bare="${arg#-}"

    # Numeric dot forms: 42.  42.3  -42.3
    if [[ "$bare" =~ ^([0-9]+)(\.([0-9]*))?$ ]]; then
        return 0
    fi

    # Label dot form: 42.label  -42.label
    if [[ "$bare" =~ ^([0-9]+)\.([a-zA-Z][a-zA-Z0-9_-]*)$ ]]; then
        return 0
    fi

    # UUID (with optional leading minus — unusual but handle gracefully)
    if is_uuid "$bare"; then
        return 0
    fi

    die "Invalid ID: '$arg' — must be a plain integer or UUID (no filters, tags, or project expressions)"
}

# ============================================================================
# Sanitize task description for use in temp filename
# ============================================================================

sanitize_for_filename() {
    echo "$1" | tr '[:upper:]' '[:lower:]' \
              | sed 's/[^a-z0-9]/-/g; s/--*/-/g; s/^-//; s/-$//' \
              | cut -c1-40
}

# ============================================================================
# Make a descriptive temp file for a given task ID
# ============================================================================

make_tmpfile() {
    local id="$1"
    local desc
    desc=$(task_get "$id.description" 2>/dev/null || echo "")
    local slug
    slug=$(sanitize_for_filename "${desc:-task}")
    tmpfile=$(mktemp "/tmp/annn_${id}_${slug}.XXXXXX.md")
}

# ============================================================================
# Get annotation count via DOM
# ============================================================================

get_annotation_count() {
    local id="$1"
    local count=0
    while true; do
        local next=$(( count + 1 ))
        local desc
        desc=$(task_get "$id.annotations.${next}.description" 2>/dev/null) || break
        [[ -z "$desc" ]] && break
        count=$next
    done
    echo "$count"
}

# ============================================================================
# Resolve a strict ID (integer or UUID) to confirmed task ID
# ============================================================================

resolve_id() {
    local raw="$1"
    local id

    # Confirm the task exists
    id=$(task rc.hooks=off rc.verbose=nothing rc.color=off "$raw" _ids 2>/dev/null | head -1)

    if [[ -z "$id" ]]; then
        die "No task found with ID: $raw"
    fi

    echo "$id"
}

# ============================================================================
# Show task context line with annotation count
# ============================================================================

show_task_context() {
    local id="$1"
    local desc
    desc=$(task_get "$id.description" 2>/dev/null || echo "")
    local count
    count=$(get_annotation_count "$id")

    if [[ "$count" -eq 0 ]]; then
        msg "Task $id: $desc (no annotations)"
    elif [[ "$count" -eq 1 ]]; then
        msg "Task $id: $desc (1 annotation)"
    else
        msg "Task $id: $desc ($count annotations)"
    fi
}

# ============================================================================
# List annotations
# ============================================================================

list_annotations() {
    local id="$1"
    local count
    count=$(get_annotation_count "$id")

    if [[ "$count" -eq 0 ]]; then
        msg "No annotations on task $id"
        return
    fi

    local desc
    desc=$(task_get "$id.description" 2>/dev/null)
    echo "Task $id: $desc"
    echo "---"

    local i=1
    while [[ $i -le $count ]]; do
        local ann_desc ann_entry
        ann_desc=$(task_get "$id.annotations.${i}.description" 2>/dev/null)
        ann_entry=$(task_get "$id.annotations.${i}.entry" 2>/dev/null)

        local date_str="$ann_entry"
        if command -v date &>/dev/null && [[ -n "$ann_entry" ]]; then
            date_str=$(date -d "$ann_entry" "+%Y-%m-%d %H:%M" 2>/dev/null) || date_str="$ann_entry"
        fi

        printf "  .%-3d [%s]\n" "$i" "$date_str"
        # Highlight label: prefix if present
        if [[ "$ann_desc" =~ ^([a-zA-Z][a-zA-Z0-9_-]*):\ (.*)$ ]]; then
            printf "       \033[1m%s:\033[0m %s\n" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}"
        else
            echo "$ann_desc" | sed 's/^/       /'
        fi
        echo ""
        i=$(( i + 1 ))
    done
}

# ============================================================================
# New annotation — editor, inline text, or pipe
# ============================================================================

new_annotation() {
    local id="$1"
    local inline_text="${2:-}"   # optional pre-supplied text

    local annot

    if [[ ! -t 0 ]]; then
        # Piped input — read stdin directly, skip editor
        annot="$(cat)"
        if [[ -z "$annot" ]]; then
            msg "Empty input, nothing saved."
            return
        fi

    elif [[ -n "$inline_text" ]]; then
        # Inline text supplied on command line — no editor
        annot="$inline_text"

    else
        # Interactive — optionally prompt for a label, then open editor
        show_task_context "$id"
        local label_prompt=""
        read -rp "[annn] Label (optional, e.g. status, link — Enter to skip): " label_prompt
        if [[ -n "$label_prompt" ]]; then
            if [[ "${label_prompt,,}" == "note" ]]; then
                note_action "$id" ""
                return
            fi
            if ! is_label "$label_prompt"; then
                die "Invalid label '$label_prompt' — use letters, digits, hyphens only"
            fi
        fi
        make_tmpfile "$id"
        [[ -n "$label_prompt" ]] && populate_tmpfile_for_label "$label_prompt"
        $EDITOR "$tmpfile"

        if [[ ! -s "$tmpfile" ]]; then
            msg "Empty annotation, nothing saved."
            return
        fi
        annot="$(cat "$tmpfile" | sed 's/[[:space:]]*$//')"
        # Reject if only the pre-populated "label: " remains with no content
        if [[ -n "$label_prompt" && "$annot" == "${label_prompt}:" ]]; then
            msg "Empty annotation, nothing saved."
            return
        fi
    fi

    if task rc.verbose=nothing rc.confirmation=off "$id" annotate "$annot"; then
        msg "Annotation added to task $id"
    else
        echo ""
        msg "Error saving annotation."
        if [[ -n "${tmpfile:-}" && -f "${tmpfile:-}" ]]; then
            msg "Your text:"
            echo "---"
            cat "$tmpfile"
            echo "---"
        fi
    fi
}

# ============================================================================
# Edit existing annotation — with optional pre-populated text appended
# ============================================================================

edit_annotation() {
    local id="$1"
    local index="$2"
    local inline_text="${3:-}"   # optional text to append before editing

    local count
    count=$(get_annotation_count "$id")

    if [[ "$count" -eq 0 ]]; then
        die "No annotations on task $id"
    fi

    if [[ "$index" -lt 1 || "$index" -gt "$count" ]]; then
        die "Annotation .$index out of range (task has $count annotation(s))"
    fi

    local old_text
    old_text=$(task_get "$id.annotations.${index}.description" 2>/dev/null)

    if [[ -z "$old_text" ]]; then
        die "Could not read annotation .$index"
    fi

    show_task_context "$id"
    make_tmpfile "$id"

    # Write existing annotation text
    echo "$old_text" > "$tmpfile"

    # Append inline text on a new line if supplied
    if [[ -n "$inline_text" ]]; then
        echo "" >> "$tmpfile"
        echo "$inline_text" >> "$tmpfile"
    fi

    $EDITOR "$tmpfile"

    local new_text
    new_text=$(cat "$tmpfile")

    if [[ "$new_text" == "$old_text" ]]; then
        msg "No changes made."
        return
    fi

    if [[ -z "$new_text" ]]; then
        msg "Annotation emptied — removing it."
        task rc.verbose=nothing rc.confirmation=off "$id" denotate "$old_text"
        return
    fi

    if task rc.verbose=nothing rc.confirmation=off "$id" denotate "$old_text" 2>/dev/null; then
        if task rc.verbose=nothing rc.confirmation=off "$id" annotate "$new_text"; then
            msg "Annotation .$index updated on task $id"
        else
            echo ""
            msg "Error saving new annotation. Old was removed. Your text:"
            echo "---"
            cat "$tmpfile"
            echo "---"
        fi
    else
        msg "Warning: could not remove old annotation. No changes made."
    fi
}

# ============================================================================
# Find annotations by label — returns matching index numbers (one per line)
# ============================================================================

find_by_label() {
    local id="$1"
    local label="${2,,}"   # lowercase for case-insensitive match
    local count
    count=$(get_annotation_count "$id")
    local i=1
    while [[ $i -le $count ]]; do
        local desc
        desc=$(task_get "$id.annotations.${i}.description" 2>/dev/null)
        if [[ "${desc,,}" =~ ^${label}:[[:space:]] ]]; then
            echo "$i"
        fi
        i=$(( i + 1 ))
    done
}

# ============================================================================
# Create a new annotation pre-populated with a label prefix
# ============================================================================

new_labeled_annotation() {
    local id="$1"
    local label="$2"
    local inline_text="${3:-}"

    if [[ ! -t 0 ]]; then
        # Pipe: prepend label to piped content
        local content
        content="$(cat)"
        if [[ -z "$content" ]]; then
            msg "Empty input, nothing saved."
            return
        fi
        if task rc.verbose=nothing rc.confirmation=off "$id" annotate "${label}: ${content}"; then
            msg "Annotation added to task $id"
        else
            msg "Error saving annotation."
        fi
        return
    fi

    if [[ -n "$inline_text" ]]; then
        # Inline text: prepend label
        if task rc.verbose=nothing rc.confirmation=off "$id" annotate "${label}: ${inline_text}"; then
            msg "Annotation added to task $id"
        else
            msg "Error saving annotation."
        fi
        return
    fi

    # Interactive: pre-populate editor with template or bare "label: "
    show_task_context "$id"
    make_tmpfile "$id"
    populate_tmpfile_for_label "$label"
    $EDITOR "$tmpfile"

    local annot
    annot="$(cat "$tmpfile" | sed 's/[[:space:]]*$//')"
    if [[ -z "$annot" || "$annot" == "${label}:" ]]; then
        msg "Empty annotation, nothing saved."
        return
    fi

    if task rc.verbose=nothing rc.confirmation=off "$id" annotate "$annot"; then
        msg "Annotation added to task $id"
    else
        msg "Error saving annotation."
    fi
}

# ============================================================================
# Dispatch action by label — create, edit, or select from duplicates
# ============================================================================

label_action() {
    local id="$1"
    local label="$2"
    local inline_text="${3:-}"

    mapfile -t matches < <(find_by_label "$id" "$label")
    local count="${#matches[@]}"

    if [[ $count -eq 0 ]]; then
        new_labeled_annotation "$id" "$label" "$inline_text"

    elif [[ $count -eq 1 ]]; then
        edit_annotation "$id" "${matches[0]}" "$inline_text"

    else
        # Multiple — list and prompt for selection
        local desc
        desc=$(task_get "$id.description" 2>/dev/null)
        echo "Task $id: $desc"
        echo "Multiple '${label}:' annotations — select one:"
        echo "---"
        for idx in "${matches[@]}"; do
            local ann_desc ann_entry date_str
            ann_desc=$(task_get "$id.annotations.${idx}.description" 2>/dev/null)
            ann_entry=$(task_get "$id.annotations.${idx}.entry" 2>/dev/null)
            date_str=$(date -d "$ann_entry" "+%Y-%m-%d %H:%M" 2>/dev/null) || date_str="$ann_entry"
            printf "  .%-3d [%s]\n" "$idx" "$date_str"
            echo "$ann_desc" | sed 's/^/       /'
            echo ""
        done
        read -rp "Edit which? [.N or Enter to cancel]: " sel
        sel="${sel#.}"
        [[ -z "$sel" ]] && { msg "Cancelled."; return; }
        local valid=false
        for idx in "${matches[@]}"; do
            [[ "$idx" == "$sel" ]] && valid=true && break
        done
        $valid || die ".$sel is not one of the matching annotations"
        edit_annotation "$id" "$sel" "$inline_text"
    fi
}

# ============================================================================
# Remove annotation by label (with confirmation) — handles duplicates
# ============================================================================

remove_by_label() {
    local id="$1"
    local label="$2"

    mapfile -t matches < <(find_by_label "$id" "$label")
    local count="${#matches[@]}"

    if [[ $count -eq 0 ]]; then
        die "No '${label}:' annotation found on task $id"

    elif [[ $count -eq 1 ]]; then
        remove_annotation "$id" "${matches[0]}"

    else
        local desc
        desc=$(task_get "$id.description" 2>/dev/null)
        echo "Task $id: $desc"
        echo "Multiple '${label}:' annotations — select one to remove:"
        echo "---"
        for idx in "${matches[@]}"; do
            local ann_desc ann_entry date_str
            ann_desc=$(task_get "$id.annotations.${idx}.description" 2>/dev/null)
            ann_entry=$(task_get "$id.annotations.${idx}.entry" 2>/dev/null)
            date_str=$(date -d "$ann_entry" "+%Y-%m-%d %H:%M" 2>/dev/null) || date_str="$ann_entry"
            printf "  .%-3d [%s]\n" "$idx" "$date_str"
            echo "$ann_desc" | sed 's/^/       /'
            echo ""
        done
        read -rp "Remove which? [.N or Enter to cancel]: " sel
        sel="${sel#.}"
        [[ -z "$sel" ]] && { msg "Cancelled."; return; }
        local valid=false
        for idx in "${matches[@]}"; do
            [[ "$idx" == "$sel" ]] && valid=true && break
        done
        $valid || die ".$sel is not one of the matching annotations"
        remove_annotation "$id" "$sel"
    fi
}

# ============================================================================
# Remove annotation (with confirmation) — index required
# ============================================================================

remove_annotation() {
    local id="$1"
    local index="$2"

    local count
    count=$(get_annotation_count "$id")

    if [[ "$count" -eq 0 ]]; then
        die "No annotations on task $id"
    fi

    if [[ "$index" -lt 1 || "$index" -gt "$count" ]]; then
        die "Annotation .$index out of range (task has $count annotation(s))"
    fi

    local ann_text
    ann_text=$(task_get "$id.annotations.${index}.description" 2>/dev/null)

    if [[ -z "$ann_text" ]]; then
        die "Could not read annotation .$index"
    fi

    local desc
    desc=$(task_get "$id.description" 2>/dev/null)
    echo "Task $id: $desc"
    echo "---"

    local ann_entry
    ann_entry=$(task_get "$id.annotations.${index}.entry" 2>/dev/null)
    local date_str="$ann_entry"
    if command -v date &>/dev/null && [[ -n "$ann_entry" ]]; then
        date_str=$(date -d "$ann_entry" "+%Y-%m-%d %H:%M" 2>/dev/null) || date_str="$ann_entry"
    fi

    printf "  .%-3d [%s]\n" "$index" "$date_str"
    echo "$ann_text" | sed 's/^/       /'
    echo ""

    read -rp "Remove this annotation? [y/N]: " response
    if [[ "${response,,}" != "y" ]]; then
        msg "Cancelled."
        return
    fi

    if task rc.verbose=nothing rc.confirmation=off "$id" denotate "$ann_text"; then
        msg "Annotation .$index removed from task $id"
    else
        msg "Error: could not remove annotation .$index"
    fi
}

# ============================================================================
# Task notes — note: label with file storage in ~/.task/notes/
# File: ~/.task/notes/<slug>-<uuid8>.note.md
# ============================================================================

NOTES_DIR="${HOME}/.task/notes"

get_note_file() {
    local id="$1"
    local desc uuid slug
    desc=$(task_get "$id.description")
    uuid=$(task_get "$id.uuid")
    slug=$(sanitize_for_filename "${desc:-task}")
    echo "${NOTES_DIR}/${slug}-${uuid:0:8}.note.md"
}

update_note_annotation() {
    local id="$1"
    local note_file="$2"
    local first_line
    first_line=$(grep -m1 '.' "$note_file" 2>/dev/null || echo "")

    # Remove any existing note: annotation(s)
    local idxs old_text
    mapfile -t idxs < <(find_by_label "$id" "note")
    for idx in "${idxs[@]}"; do
        old_text=$(task_get "$id.annotations.${idx}.description")
        task rc.verbose=nothing rc.confirmation=off "$id" denotate "$old_text" 2>/dev/null || true
    done

    if ! task rc.verbose=nothing rc.confirmation=off "$id" annotate "note: ${first_line}"; then
        msg "ERROR: annotation update failed. Note file preserved at: $note_file"
    fi
}

note_action() {
    local id="$1"
    local inline_text="${2:-}"
    local note_file
    note_file=$(get_note_file "$id")
    mkdir -p "$NOTES_DIR"

    local is_new=true
    [[ -f "$note_file" ]] && is_new=false

    if [[ ! -t 0 ]]; then
        # Pipe: create or append
        local content
        content="$(cat)"
        if [[ -z "$content" ]]; then
            msg "Empty input, nothing saved."
            return
        fi
        if $is_new; then
            echo "$content" > "$note_file"
        else
            echo "" >> "$note_file"
            echo "$content" >> "$note_file"
        fi
        update_note_annotation "$id" "$note_file"
        msg "Note updated for task $id"
        return
    fi

    if [[ -n "$inline_text" ]]; then
        # Inline: create with template+text, or append to existing
        if $is_new; then
            local template
            template=$(load_template "note")
            if [[ -n "$template" ]]; then
                cp "$template" "$note_file"
                echo "" >> "$note_file"
            fi
            echo "$inline_text" >> "$note_file"
        else
            echo "" >> "$note_file"
            echo "$inline_text" >> "$note_file"
        fi
        update_note_annotation "$id" "$note_file"
        msg "Note updated for task $id"
        return
    fi

    # Interactive: open note file directly (with template if new)
    show_task_context "$id"
    if $is_new; then
        local template
        template=$(load_template "note")
        [[ -n "$template" ]] && cp "$template" "$note_file"
    fi
    $EDITOR "$note_file"

    if [[ ! -f "$note_file" || ! -s "$note_file" ]]; then
        rm -f "$note_file"
        msg "Empty note, nothing saved."
        return
    fi

    update_note_annotation "$id" "$note_file"
    if $is_new; then
        msg "Note created: $note_file"
    else
        msg "Note updated: $note_file"
    fi
}

remove_note() {
    local id="$1"
    local note_file
    note_file=$(get_note_file "$id")

    local desc
    desc=$(task_get "$id.description")
    echo "Task $id: $desc"
    echo "---"
    if [[ -f "$note_file" ]]; then
        echo "Note file: $note_file"
        printf "  %s\n" "$(head -1 "$note_file")"
    else
        echo "(No note file at $note_file)"
    fi
    echo ""

    read -rp "Remove note annotation and file? [y/N]: " response
    if [[ "${response,,}" != "y" ]]; then
        msg "Cancelled."
        return
    fi

    local idxs old_text removed=0
    mapfile -t idxs < <(find_by_label "$id" "note")
    for idx in "${idxs[@]}"; do
        old_text=$(task_get "$id.annotations.${idx}.description")
        if task rc.verbose=nothing rc.confirmation=off "$id" denotate "$old_text" 2>/dev/null; then
            removed=$(( removed + 1 ))
        fi
    done
    [[ $removed -gt 0 ]] && msg "Note annotation removed from task $id"

    if [[ -f "$note_file" ]]; then
        rm "$note_file"
        msg "Note file deleted: $note_file"
    fi
}

# ============================================================================
# Main
# ============================================================================

# Handle flags (only when stdin is a terminal — pipes shouldn't trigger usage)
if [[ -t 0 ]]; then
    case "${1:-}" in
        -h|--help) usage ;;
        -v|--version) echo "annn v$VERSION"; exit 0 ;;
        "") usage ;;
    esac
else
    if [[ $# -eq 0 ]]; then
        die "Usage: echo \"text\" | $SCRIPT_NAME <id>"
    fi
fi

# ============================================================================
# Argument parsing
#
# Strict: arg1 must be integer, integer+dot, integer+dot+N, -integer.N, or UUID.
# No filter expressions, project:, +tag, or bare words permitted as ID.
#
# Accepted forms:
#   annn 42               → new annotation (editor)
#   annn 42 text...       → new annotation (inline, no editor)
#   annn 42.              → list annotations
#   annn 42.3             → edit annotation 3 (editor)
#   annn 42.3 text...     → edit annotation 3 (editor, text appended)
#   annn -42.3            → remove annotation 3
# ============================================================================

arg1="${1:-}"
shift

# Validate arg1 before anything else
validate_id_arg "$arg1"

remove_mode=false
filter=""
action="new"
ann_index=""
ann_label=""

if [[ "$arg1" =~ ^-([0-9]+)\.([a-zA-Z][a-zA-Z0-9_-]*)$ ]]; then
    # Remove by label: -42.status
    filter="${BASH_REMATCH[1]}"
    ann_label="${BASH_REMATCH[2]}"
    remove_mode=true
    action="label"

elif [[ "$arg1" =~ ^-([0-9]+)\.([0-9]+)$ ]]; then
    # Remove by index: -42.3
    filter="${BASH_REMATCH[1]}"
    ann_index="${BASH_REMATCH[2]}"
    remove_mode=true

elif [[ "$arg1" =~ ^-([0-9]+)(\.?)$ ]]; then
    # -42 or -42. without an index — ambiguous, require index
    die "Remove requires an annotation index or label: use -${BASH_REMATCH[1]}.<N> or -${BASH_REMATCH[1]}.<label>"

elif [[ "$arg1" =~ ^([0-9]+)\.([a-zA-Z][a-zA-Z0-9_-]*)$ ]]; then
    # Label action: 42.status
    filter="${BASH_REMATCH[1]}"
    ann_label="${BASH_REMATCH[2]}"
    action="label"

elif [[ "$arg1" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
    # Edit by index: 42.3
    filter="${BASH_REMATCH[1]}"
    ann_index="${BASH_REMATCH[2]}"
    action="edit"

elif [[ "$arg1" =~ ^([0-9]+)\.$  ]]; then
    # List: 42.
    filter="${BASH_REMATCH[1]}"
    action="list"

elif is_integer "$arg1" || is_uuid "$arg1"; then
    # Plain ID — new annotation (or inline if args follow)
    filter="$arg1"
    action="new"

else
    die "Invalid ID: '$arg1' — must be a plain integer or UUID"
fi

# Resolve to confirmed task ID
id=$(resolve_id "$filter")

# Collect any remaining args as inline text
inline_text=""
if [[ $# -gt 0 ]]; then
    inline_text="$*"
fi

# ============================================================================
# Dispatch
# ============================================================================

if [[ "$remove_mode" == true ]]; then
    if [[ "$action" == "label" ]]; then
        if [[ "${ann_label,,}" == "note" ]]; then
            remove_note "$id"
        else
            remove_by_label "$id" "$ann_label"
        fi
    elif ! [[ "$ann_index" =~ ^[0-9]+$ ]]; then
        die "Invalid annotation index: .$ann_index"
    else
        remove_annotation "$id" "$ann_index"
    fi

else
    case "$action" in
        list)
            list_annotations "$id"
            ;;
        edit)
            if ! [[ "$ann_index" =~ ^[0-9]+$ ]]; then
                die "Invalid annotation index: .$ann_index"
            fi
            edit_annotation "$id" "$ann_index" "$inline_text"
            ;;
        label)
            if [[ "${ann_label,,}" == "note" ]]; then
                note_action "$id" "$inline_text"
            else
                label_action "$id" "$ann_label" "$inline_text"
            fi
            ;;
        new)
            new_annotation "$id" "$inline_text"
            ;;
        *)
            die "Unknown action: $action"
            ;;
    esac
fi