# T3-2.4: Advanced Task Command Features

## Priority
Low

## Status
Completed

## Description
Add advanced features to task commands including JSON output mode, optimistic concurrency control, bulk operations, and enhanced error handling.

## Objectives
- Add `--json` flag to all task commands for machine-readable output
- Implement optimistic concurrency control with version checking
- Add bulk operations support
- Enhance error messages with actionable suggestions
- Add `--dry-run` mode for preview
- Support fuzzy task ID matching

## Features

### JSON Output Mode
```bash
# JSON output for scripting
$ anyt task show DEV-42 --json
{
  "id": 42,
  "identifier": "DEV-42",
  "title": "Implement OAuth callback",
  "status": "in progress",
  "priority": 2,
  "owner_id": "user_123",
  "labels": ["auth", "backend"],
  "created_at": "2025-10-15T10:00:00Z",
  "updated_at": "2025-10-15T14:30:00Z",
  "version": 5
}

$ anyt task list --status backlog --json
{
  "items": [...],
  "pagination": {
    "total": 15,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}
```

### Optimistic Concurrency Control
```bash
# Edit with version check
$ anyt task edit DEV-42 --status done --if-match 5
✓ Updated DEV-42

# Version conflict
$ anyt task edit DEV-42 --status done --if-match 4
✗ Error: Task was modified by another user
  Current version: 5
  Your version: 4

  Fetch latest with: anyt task show DEV-42
```

### Fuzzy Task ID Matching
```bash
# All of these work
$ anyt task show DEV-42    # Full identifier
$ anyt task show 42        # Number only
$ anyt task show dev42     # Case insensitive, no dash
$ anyt task show DEV 42    # With space
```

### Bulk Operations
```bash
# Close multiple tasks
$ anyt task done DEV-42 DEV-43 DEV-45
✓ Marked 3 tasks as done

# Update multiple tasks
$ anyt task edit --ids DEV-42,DEV-43 --status in progress
✓ Updated 2 tasks

# Add label to multiple tasks
$ anyt task edit --ids DEV-42,DEV-43,DEV-45 --labels +urgent
✓ Added label 'urgent' to 3 tasks
```

### Dry Run Mode
```bash
# Preview changes without applying
$ anyt task edit DEV-42 --status done --dry-run
[Preview] Would update DEV-42:
  status: in progress → done
  updated_at: 2025-10-15T14:30:00Z

Run without --dry-run to apply changes
```

### Enhanced Error Messages
```bash
# Task not found
$ anyt task show DEV-99
✗ Error: Task 'DEV-99' not found in workspace DEV

  Did you mean:
    DEV-42  Implement OAuth callback
    DEV-43  Add tests

  List all tasks: anyt task list

# Permission denied
$ anyt task rm DEV-42
✗ Error: Permission denied

  Deleting tasks requires 'maintainer' role or higher.
  Your role: contributor

  Contact workspace admin to request access.

# Validation error
$ anyt task add "New task" --priority 10
✗ Error: Invalid priority value

  Priority must be between -2 and 2
    -2: Lowest
    -1: Low
     0: Normal (default)
     1: High
     2: Highest
```

## Acceptance Criteria
- [x] All task commands support `--json` flag for machine-readable output
- [x] JSON output follows consistent schema
- [x] Optimistic concurrency control with `--if-match <version>`
- [x] Version conflict errors show current vs. provided version
- [x] Fuzzy task ID matching (case-insensitive, no dash required)
- [x] Bulk operations for `done`, `edit`, `rm` commands
- [x] `--dry-run` flag shows preview without applying changes
- [x] Error messages include actionable suggestions
- [x] Error messages suggest similar task IDs when not found
- [x] Permission errors explain required role

## Dependencies
- T3-2.1: CLI Task Commands - Core (core commands must exist first)

## Estimated Effort
4-5 hours

## Technical Notes

### JSON Output
- Use `--json` flag on all commands
- Suppress rich formatting when JSON mode enabled
- Output valid JSON to stdout
- Errors still go to stderr (even in JSON mode)

### Fuzzy Matching
```python
def normalize_identifier(task_id: str) -> str:
    """Normalize task identifier for fuzzy matching."""
    # DEV-42 → DEV-42
    # dev42 → DEV-42
    # 42 → 42 (try as ID)
    # DEV 42 → DEV-42
    pass
```

### Version Conflicts
- Check task version before update
- Use `If-Match` header with version number
- Handle 409 Conflict responses from API
- Show diff between current and attempted change

### Error Suggestions
- Use difflib for "Did you mean?" suggestions
- Limit to 3 most similar matches
- Include helpful commands in error messages

## Out of Scope
- Shell completion for task IDs (future enhancement)
- Task templates or snippets
- Undo/redo functionality
- Task history/changelog view

## Events

### 2025-10-15 21:30 - Started work
- Moved task from backlog to active
- Created new branch T3-2.4-advanced-task-features
- Beginning implementation of advanced task command features
- Will start with JSON output mode for all task commands

### 2025-10-15 22:00 - Implementation complete
- Added `--json` flag to all task commands (add, list, show, edit, done, rm)
- Implemented fuzzy task ID matching via `normalize_identifier()` function
  - Handles: DEV-42, dev42, 42, "DEV 42" variations
- Implemented optimistic concurrency control with `--if-match <version>` flag
  - Shows version conflict errors with current vs. provided version
  - Suggests running `anyt task show` to get latest version
- Added bulk operations support:
  - `anyt task done DEV-42 DEV-43 DEV-45` (multiple args)
  - `anyt task edit --ids DEV-42,DEV-43 --status inprogress` (comma-separated)
  - `anyt task rm DEV-42 DEV-43` (multiple args)
- Implemented `--dry-run` flag for `edit` command
  - Shows preview of changes before applying
- Enhanced error messages with actionable suggestions:
  - Task not found: Shows similar tasks using difflib fuzzy matching
  - Missing identifier: Suggests command usage
  - Invalid priority: Shows valid range with descriptions
  - Version conflict: Suggests fetching latest version
- JSON output follows consistent schema:
  - Success: `{"success": true, "data": {...}}`
  - Error: `{"success": false, "error": "...", "message": "..."}`
  - List: Includes pagination metadata
  - Bulk operations: Returns both `updated` and `errors` arrays
- All commands pass mypy type checking
- All linting issues resolved

### 2025-10-15 22:15 - Completed and merged
- Task moved to done/
- Committed changes with detailed commit message
- Created PR #24: https://github.com/supercarl87/AnyTaskBackend/pull/24
- PR includes comprehensive summary and test plan
