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

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

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

@@ -11,13 +11,23 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 REPO_OVERRIDE=""
 
+# 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
+    echo "Usage: pr-view.sh -n <pr_number> [-r owner/repo] (see --help)" >&2
+    exit 2
+}
+
 while [[ $# -gt 0 ]]; do
     case $1 in
         -n|--number)
+            [[ $# -ge 2 && "$2" != - && "$2" != --* && ! "$2" =~ ^-[[:alnum:]] ]] || usage_error "option $1 requires a value (option-like values are rejected; bare - is reserved)"
             PR_NUMBER="$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
             ;;
@@ -28,18 +38,18 @@ while [[ $# -gt 0 ]]; do
             echo "  -n, --number   PR number (required)"
             echo "  -r, --repo     Repository slug (default: infer from git origin)"
             echo "  -h, --help     Show this help"
+            echo ""
+            echo "Exit codes: 0 success; 2 usage error (stderr); 1 provider/credential failure."
             exit 0
             ;;
         *)
-            echo "Unknown option: $1"
-            exit 1
+            usage_error "unknown option: $1"
             ;;
     esac
 done
 
 if [[ -z "$PR_NUMBER" ]]; then
-    echo "Error: PR number is required (-n)"
-    exit 1
+    usage_error "PR number is required (-n/--number)"
 fi
 
 if [[ -n "$REPO_OVERRIDE" ]]; then