P1b: read-only viewers join the R1/R4 usage contract (#1472)

Co-authored-by: marcie <[email protected]>

packages/mosaic/framework/tools/git/pr-list.sh

@@ -34,29 +34,41 @@ Examples:
     $(basename "$0") -s merged -a username    # Merged PRs by user
     $(basename "$0") --repo ddk/ai-bma         # List PRs from anywhere
 EOF
-    exit "${1:-1}"
+    exit "${1:-2}"
 }
 
 # Parse arguments
+# Usage-error contract (R4): usage errors print to STDERR and exit 2,
+# distinct from provider, credential, and verification failures (exit 1).
+usage_error() {
+    echo "Error: $*" >&2
+    usage >&2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -s|--state)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             STATE="$2"
             shift 2
             ;;
         -l|--label)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LABEL="$2"
             shift 2
             ;;
         -a|--author)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             AUTHOR="$2"
             shift 2
             ;;
         -n|--limit)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             LIMIT="$2"
             shift 2
             ;;
         -r|--repo)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             REPO_OVERRIDE="$2"
             shift 2
             ;;
@@ -64,8 +76,7 @@ while [[ $# -gt 0 ]]; do
             usage 0
             ;;
         *)
-            echo "Unknown option: $1" >&2
-            usage
+            usage_error "unknown option: $1"
             ;;
     esac
 done