[cueman] Add unit tests and validation for frame operations (AcademySoftwareFoundation#1999)

**Link the Issue(s) this Pull Request is related to.**
- AcademySoftwareFoundation#1929
- AcademySoftwareFoundation#1800 

**Summarize your change.**

Summary:

Add comprehensive unit tests for frame-specific operations and implement
input validation for stagger, reorder, and frame range operations.
Updated documentation to reflect new validation requirements.

Changes:

1) Unit tests (`cueman/tests/test_frame_operations.py`)

Created comprehensive test suite covering:
- Frame eat/kill/retry operations with layer and range filters
- Frame state filtering (running, waiting, dead, succeeded)
- Frame range parsing and validation
- Mark done functionality
- Stagger operations with increment validation (positive integers only)
- Reorder operations with position validation (FIRST, LAST, REVERSE)
- Confirmation prompts for destructive operations
- Error handling for invalid inputs

2) Input validation (`cueman/cueman/main.py`)

Added validation to ensure:
- Stagger increments must be positive integers (rejects 0, negative,
non-numeric)
- Reorder positions must be FIRST, LAST, or REVERSE
- Frame ranges must be valid numeric formats with start < = end

3) Documentation updates

Updated documentation across multiple files:
- `docs/_docs/reference/tools/cueman.md`: Added validation notes and
troubleshooting examples for invalid inputs
- `docs/_docs/tutorials/cueman-tutorial.md`: Added validation notes in
Frame Manipulation section and error examples
- `cueman/cueman_tutorial.md`: Added validation notes for stagger and
reorder
- `cueman/README.md`: Updated inline comments to reflect requirements

4) Test fixes

- Fixed typo in test method name: from `test_done_fundtionality` to
`test_done_functionality`
- Corrected layer parameter type from string to list in 7 tests to match
argparse `nargs="+"` behavior
- Updated assertions to expect list values for consistency with actual
command-line argument parsing

Co-authored-by: Kathy Lee <lee.j.kathy@gmail.com>
Co-authored-by: Ramon Figueiredo <rfigueiredo@imageworks.com>

Author: kkxthyl

cueman/README.md

@@ -217,10 +217,10 @@ cueman -retry job_name -state DEAD
 ## Frame Manipulation
 
 ```bash
-# Stagger frames by increment
+# Stagger frames by increment (must be positive integer)
 cueman -stagger job_name 1-100 5
 
-# Reorder frames
+# Reorder frames (position must be FIRST, LAST, or REVERSE)
 cueman -reorder job_name 1-100 FIRST
 cueman -reorder job_name 50-100 LAST
 cueman -reorder job_name 1-100 REVERSE

cueman/cueman/main.py

@@ -567,6 +567,9 @@ def handleArgs(args):
     elif args.stagger:
         name, frame_range, increment = args.stagger
         try:
+            if not increment.isdigit() or int(increment) < 1:
+                logger.error("Error: Increment must be a positive integer.")
+                sys.exit(1)
             job = opencue.api.findJob(name)
             layers = args.layer
             common.confirm(
@@ -591,6 +594,9 @@ def handleArgs(args):
     elif args.reorder:
         name, frame_range, position = args.reorder
         try:
+            if position not in ["FIRST", "LAST", "REVERSE"]:
+                logger.error("Error: Position must be one of FIRST, LAST, or REVERSE.")
+                sys.exit(1)
             job = opencue.api.findJob(name)
             layers = args.layer
             common.confirm(
@@ -725,6 +731,14 @@ def buildFrameSearch(args):
     if args.layer:
         s["layer"] = args.layer
     if args.range:
+        if not re.match(r"^\d+$|^\d+-\d+$", args.range):
+            logger.error("Invalid range format: %s", args.range)
+            sys.exit(1)
+        if "-" in args.range:
+            r = args.range.partition("-")
+            if r[0] > r[2]:
+                logger.error("Invalid range format: %s", args.range)
+                sys.exit(1)
         s["range"] = args.range
     if args.state:
         s["state"] = [common.Convert.strToFrameState(st) for st in args.state]

cueman/cueman_tutorial.md

@@ -376,6 +376,8 @@ cueman -stagger job_name 1-100 5
 cueman -stagger job_name 1-50 10 -layer sim_layer
 ```
 
+**Note:** Increment must be a positive integer. Zero, negative, and non-numeric values will be rejected.
+
 ### Reorder Frames
 Change frame execution order:
 
@@ -393,6 +395,8 @@ cueman -reorder job_name 1-100 REVERSE
 cueman -reorder job_name 1-50 FIRST -layer hero_layer
 ```
 
+**Note:** Position must be one of: `FIRST`, `LAST`, or `REVERSE`. Other values will be rejected.
+
 ## Real-World Scenarios
 
 ### Scenario 1: Handling Stuck Frames