stack/packages/mosaic/framework/tools/git/pr-review.sh

#!/bin/bash
# pr-review.sh - Review a pull request on GitHub or Gitea
# Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>]
#
# Gitea reviews and comments are written through the supported REST API, not
# `tea`: tea 0.11.1 cannot emit the id of a record it creates and can silently
# no-op while exiting 0 (#865 defect class), so an exit code is the only — and
# untrustworthy — signal it offers. approve/request-changes POST to
# /pulls/{n}/reviews (returns the created review with its id); the `comment`
# action POSTs to /issues/{n}/comments (returns the created comment with its
# id). Each write is then verified by GETting that exact returned id, so a
# concurrent record cannot masquerade as this write and a no-op fails closed.
#
# --login override: the default login is resolved from the local tea login list
# for this repo's host (get_gitea_login_for_host). Pass --login <name> to
# override it for this invocation only. The REST write, the /user identity read,
# and every read-back are ALL performed with the token of the EFFECTIVE login,
# so the write and its verification bind to the same identity.

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# shellcheck source=packages/mosaic/framework/tools/git/detect-platform.sh
source "$SCRIPT_DIR/detect-platform.sh"

# Parse arguments
PR_NUMBER=""
ACTION=""
COMMENT=""
LOGIN_OVERRIDE=""

while [[ $# -gt 0 ]]; do
    case $1 in
        -n|--number)
            PR_NUMBER="$2"
            shift 2
            ;;
        -a|--action)
            ACTION="$2"
            shift 2
            ;;
        -c|--comment)
            COMMENT="$2"
            shift 2
            ;;
        -l|--login)
            LOGIN_OVERRIDE="$2"
            shift 2
            ;;
        -h|--help)
            echo "Usage: pr-review.sh -n <pr_number> -a <action> [-c <comment>] [--login <name>]"
            echo ""
            echo "Options:"
            echo "  -n, --number   PR number (required)"
            echo "  -a, --action   Review action: approve, request-changes, comment (required)"
            echo "  -c, --comment  Review comment (required for request-changes)"
            echo "  -l, --login    Override the detected Gitea tea login (approve/request-changes only)"
            echo "  -h, --help     Show this help"
            exit 0
            ;;
        *)
            echo "Unknown option: $1"
            exit 1
            ;;
    esac
done

if [[ -z "$PR_NUMBER" ]]; then
    echo "Error: PR number is required (-n)"
    exit 1
fi

if [[ -z "$ACTION" ]]; then
    echo "Error: Action is required (-a): approve, request-changes, comment"
    exit 1
fi

detect_platform >/dev/null

# Post a comment to a Gitea PR (PR comments ARE issue comments) via the
# supported REST API and verify it against a PROVIDER-RETURNED created id. The
# write is a direct POST that returns the created comment object, so we learn
# the exact id of THIS write; we GET that exact id and require id == created id
# AND author == acting identity AND exact body AND that it belongs to this PR.
# Keying to the returned id means no concurrent comment (even same identity /
# body) can masquerade as this write, and a no-op create yields no id and fails
# closed. Requires GITEA_API_BASE / GITEA_API_TOKEN to be resolved first (via
# gitea_resolve_api_for_login). Prints the created comment id on success.
#
# Args: $1 = PR number, $2 = comment body, $3 = acting identity login.
gitea_create_comment_verified() {
    local pr_number="$1" comment_body="$2" acting_login="$3"
    local payload write_file readback_file write_status readback_status created_id

    payload=$(COMMENT_BODY="$comment_body" python3 -c '
import json
import os

print(json.dumps({"body": os.environ["COMMENT_BODY"]}))
')
    write_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-write.XXXXXX")
    readback_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-getid.XXXXXX")
    trap 'rm -f "$write_file" "$readback_file"' RETURN

    if ! write_status=$(curl -sS -o "$write_file" -w '%{http_code}' \
        -X POST \
        -H "Authorization: token $GITEA_API_TOKEN" \
        -H 'Content-Type: application/json' \
        -d "$payload" \
        "$GITEA_API_BASE/issues/$pr_number/comments"); then
        echo "Error: Gitea comment write transport failed" >&2
        return 1
    fi
    if [[ "$write_status" != "201" ]]; then
        echo "Error: Gitea comment write failed with HTTP $write_status" >&2
        return 1
    fi

    created_id=$(python3 - "$write_file" <<'PY'
import json
import sys

try:
    with open(sys.argv[1], encoding="utf-8") as response:
        comment = json.load(response)
    created_id = comment.get("id") if isinstance(comment, dict) else None
    if not isinstance(created_id, int) or created_id <= 0:
        raise ValueError("create response carried no positive comment id")
except (OSError, json.JSONDecodeError, ValueError) as error:
    print(f"Error: could not identify created Gitea comment: {error}", file=sys.stderr)
    raise SystemExit(1)
print(created_id)
PY
) || return 1

    if ! readback_status=$(curl -sS -o "$readback_file" -w '%{http_code}' \
        -H "Authorization: token $GITEA_API_TOKEN" \
        "$GITEA_API_BASE/issues/comments/$created_id"); then
        echo "Error: Gitea comment read-back transport failed" >&2
        return 1
    fi
    if [[ "$readback_status" != "200" ]]; then
        echo "Error: Gitea comment read-back failed with HTTP $readback_status" >&2
        return 1
    fi

    EXPECTED_COMMENT_ID="$created_id" EXPECTED_COMMENT_BODY="$comment_body" \
        ACTING_LOGIN="$acting_login" EXPECTED_REPO_SLUG="${GITEA_API_BASE##*/repos/}" \
        EXPECTED_PR_NUMBER="$pr_number" \
        python3 - "$readback_file" <<'PY' || return 1
import json
import os
import sys
from urllib.parse import urlparse

try:
    with open(sys.argv[1], encoding="utf-8") as response:
        comment = json.load(response)
    if not isinstance(comment, dict):
        raise ValueError("response is not a comment object")
    expected_id = int(os.environ["EXPECTED_COMMENT_ID"])
    expected_body = os.environ["EXPECTED_COMMENT_BODY"]
    acting_login = os.environ["ACTING_LOGIN"]
    expected_suffix = (
        f"/repos/{os.environ['EXPECTED_REPO_SLUG']}"
        f"/issues/{os.environ['EXPECTED_PR_NUMBER']}"
    )
    issue_path = urlparse(comment.get("issue_url", "")).path.rstrip("/")
    if comment.get("id") != expected_id:
        raise ValueError("read-back id does not match the created id")
    if (comment.get("user") or {}).get("login") != acting_login:
        raise ValueError("created comment is not authored by the acting identity")
    if comment.get("body") != expected_body:
        raise ValueError("created comment body does not match")
    if not issue_path.endswith(expected_suffix):
        raise ValueError("created comment does not belong to this PR")
except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as error:
    print(f"Error: Gitea comment persistence verification failed: {error}", file=sys.stderr)
    raise SystemExit(1)
PY

    echo "$created_id"
    return 0
}

# Resolve and cache the Gitea REST endpoint + token for the current remote,
# bound to a SPECIFIC login identity ($1). Populates GITEA_API_ROOT (…/api/v1),
# GITEA_API_BASE (…/api/v1/repos/<slug>), and GITEA_API_TOKEN.
#
# The token is resolved for the EFFECTIVE login (the --login override when
# given, otherwise the detected default), so the one credential used to submit
# the review/comment ALSO drives the /user identity read and every read-back —
# write token and read-back token are the same identity by construction. This
# is the credential-ordering fix: a --login override is no longer submitted
# under one credential and verified under a different default one. Falls back to
# the host-scoped credential only when the login has no token in tea's config.
# Returns non-zero (clear stderr) on any resolution failure.
gitea_resolve_api_for_login() {
    local effective_login="$1" host configured_url repo

    host=$(get_remote_host)
    GITEA_API_TOKEN=$(get_gitea_token_for_login "$effective_login") \
        || GITEA_API_TOKEN=$(get_gitea_token "$host") || {
        echo "Error: Gitea token not found for login '$effective_login' (review write/read-back)" >&2
        return 1
    }
    configured_url=$(get_gitea_url_for_host "$host") || {
        echo "Error: Configured Gitea URL not found for review read-back verification" >&2
        return 1
    }
    repo=$(get_gitea_repo_slug_for_url "$configured_url") || {
        echo "Error: Could not resolve Gitea owner/repository relative to configured URL" >&2
        return 1
    }
    GITEA_API_ROOT="${configured_url%/}/api/v1"
    GITEA_API_BASE="$GITEA_API_ROOT/repos/$repo"
    return 0
}

# Fetch every page of a Gitea list endpoint into $2 (merged into one JSON
# array). Gitea paginates list responses, so a single-page read would
# false-negative once a newly created review/comment lands beyond page 1.
# Walks page=1,2,… until a short or empty page is returned so the merged array
# is exhaustive. $1 is the endpoint URL with NO query string. Returns non-zero
# (clear stderr) on any transport / HTTP / parse failure.
gitea_fetch_all() {
    local base_url="$1" dest="$2" page=1 limit=50 status page_file count

    printf '[]' > "$dest"
    while :; do
        page_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-page.XXXXXX")
        if ! status=$(curl -sS -o "$page_file" -w '%{http_code}' \
            -H "Authorization: token $GITEA_API_TOKEN" \
            "${base_url}?limit=${limit}&page=${page}"); then
            rm -f "$page_file"
            echo "Error: Gitea list read transport failed" >&2
            return 1
        fi
        if [[ "$status" != "200" ]]; then
            rm -f "$page_file"
            echo "Error: Gitea list read failed with HTTP $status" >&2
            return 1
        fi
        count=$(DEST="$dest" python3 - "$page_file" <<'PY'
import json
import os
import sys

try:
    with open(os.environ["DEST"], encoding="utf-8") as merged_file:
        merged = json.load(merged_file)
    with open(sys.argv[1], encoding="utf-8") as page_file:
        page = json.load(page_file)
    if not isinstance(page, list):
        raise ValueError("page response is not a list")
    merged.extend(item for item in page if isinstance(item, dict))
    with open(os.environ["DEST"], "w", encoding="utf-8") as merged_file:
        json.dump(merged, merged_file)
except (OSError, json.JSONDecodeError, TypeError, ValueError) as error:
    print(f"Error: could not merge Gitea list page: {error}", file=sys.stderr)
    raise SystemExit(1)
print(len(page))
PY
) || { rm -f "$page_file"; return 1; }
        rm -f "$page_file"
        [[ "$count" -lt "$limit" ]] && break
        page=$((page + 1))
        if [[ "$page" -gt 1000 ]]; then
            echo "Error: Gitea list pagination exceeded 1000 pages" >&2
            return 1
        fi
    done
    return 0
}

# Resolve the login of the identity the API token authenticates as (GET
# /user). Used to attribute a read-back review to THIS action's reviewer so a
# concurrent review from a DIFFERENT identity cannot satisfy verification.
# Prints the login on success.
gitea_authenticated_login() {
    local response_file status

    response_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-whoami.XXXXXX")
    trap 'rm -f "$response_file"' RETURN

    if ! status=$(curl -sS -o "$response_file" -w '%{http_code}' \
        -H "Authorization: token $GITEA_API_TOKEN" \
        "$GITEA_API_ROOT/user"); then
        echo "Error: Gitea authenticated-identity read transport failed" >&2
        return 1
    fi
    if [[ "$status" != "200" ]]; then
        echo "Error: Gitea authenticated-identity read failed with HTTP $status" >&2
        return 1
    fi

    python3 - "$response_file" <<'PY'
import json
import sys

try:
    with open(sys.argv[1], encoding="utf-8") as response:
        user = json.load(response)
    login = user.get("login") if isinstance(user, dict) else None
    if not isinstance(login, str) or not login:
        raise ValueError("missing authenticated login")
except (OSError, json.JSONDecodeError, TypeError, ValueError) as error:
    print(f"Error: could not resolve authenticated Gitea identity: {error}", file=sys.stderr)
    raise SystemExit(1)
print(login)
PY
}

# Resolve the PR's current head commit SHA (GET /pulls/{n}). The review is
# submitted against — and later verified as pinned to — this exact commit, so a
# stale review left over from an earlier push cannot be mistaken for this one.
# Prints the head SHA on success.
gitea_pr_head_sha() {
    local pr_number="$1" pr_file status

    pr_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-head.XXXXXX")
    trap 'rm -f "$pr_file"' RETURN

    if ! status=$(curl -sS -o "$pr_file" -w '%{http_code}' \
        -H "Authorization: token $GITEA_API_TOKEN" \
        "$GITEA_API_BASE/pulls/$pr_number"); then
        echo "Error: Gitea PR head read transport failed" >&2
        return 1
    fi
    if [[ "$status" != "200" ]]; then
        echo "Error: Gitea PR head read failed with HTTP $status" >&2
        return 1
    fi
    python3 - "$pr_file" <<'PY'
import json
import sys

try:
    with open(sys.argv[1], encoding="utf-8") as response:
        pr = json.load(response)
    head_sha = pr.get("head", {}).get("sha") if isinstance(pr, dict) else None
    if not isinstance(head_sha, str) or not head_sha:
        raise ValueError("missing PR head sha")
except (OSError, json.JSONDecodeError, AttributeError, TypeError, ValueError) as error:
    print(f"Error: could not resolve PR head commit: {error}", file=sys.stderr)
    raise SystemExit(1)
print(head_sha)
PY
}

# Confirm that the review CREATED by this action ($2 = its provider id) is
# enumerable in the PR's full, paginated review listing, authored by the acting
# identity, in the expected state. Gitea paginates review lists, so a review
# created beyond page 1 must still be found; walking every page also proves the
# created id is durably indexed against THIS PR rather than merely retrievable
# by id. Returns non-zero (clear stderr) if the exact created id is absent or
# does not match author/state.
gitea_confirm_review_enumerable() {
    local pr_number="$1" created_id="$2" expected_state="$3" acting_login="$4" merged_file

    merged_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-list.XXXXXX")
    trap 'rm -f "$merged_file"' RETURN

    gitea_fetch_all "$GITEA_API_BASE/pulls/$pr_number/reviews" "$merged_file" || return 1

    CREATED_REVIEW_ID="$created_id" EXPECTED_STATE="$expected_state" ACTING_LOGIN="$acting_login" \
        python3 - "$merged_file" <<'PY'
import json
import os
import sys

try:
    with open(sys.argv[1], encoding="utf-8") as response:
        reviews = json.load(response)
    if not isinstance(reviews, list):
        raise ValueError("response is not a review list")
    created_id = int(os.environ["CREATED_REVIEW_ID"])
    expected_state = os.environ["EXPECTED_STATE"]
    acting_login = os.environ["ACTING_LOGIN"]
    match = next(
        (
            r for r in reviews
            if isinstance(r, dict)
            and r.get("id") == created_id
            and (r.get("user") or {}).get("login") == acting_login
            and r.get("state") == expected_state
        ),
        None,
    )
    if match is None:
        raise ValueError(
            f"created review id {created_id} is not enumerable in the PR's "
            "paginated review list under the acting identity/state"
        )
except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as error:
    print(f"Error: Gitea review enumeration check failed: {error}", file=sys.stderr)
    raise SystemExit(1)
PY
}

# Submit a review to a Gitea PR via the supported REST API and verify it against
# a PROVIDER-RETURNED created id. tea 0.11.1's `pr approve`/`reject` cannot emit
# the id of the review it created and can silently no-op while exiting 0 (#865
# defect class), so this does NOT shell out to tea: it POSTs to
# /pulls/{n}/reviews with the event (APPROVED / REQUEST_CHANGES), the PR head
# commit_id, and the review body, which returns the created review object
# including its id. It then GETs that exact review id and requires
# id == created id AND author == acting identity AND state == expected AND
# commit_id == PR head. Keying to the returned id means no concurrent review
# (even same identity/state/head) can masquerade as this one, and a no-op
# submit yields no id and fails closed. Prints the created review id on success.
#
# Args: $1 = PR number, $2 = event (APPROVED|REQUEST_CHANGES),
#       $3 = review body (may be empty for APPROVED), $4 = acting login,
#       $5 = PR head sha.
gitea_submit_review_verified() {
    local pr_number="$1" event="$2" review_body="$3" acting_login="$4" head_sha="$5"
    local payload write_file readback_file write_status readback_status created_id

    payload=$(REVIEW_EVENT="$event" REVIEW_BODY="$review_body" REVIEW_COMMIT="$head_sha" python3 -c '
import json
import os

print(json.dumps({
    "event": os.environ["REVIEW_EVENT"],
    "body": os.environ["REVIEW_BODY"],
    "commit_id": os.environ["REVIEW_COMMIT"],
}))
')
    write_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-submit.XXXXXX")
    readback_file=$(mktemp "${TMPDIR:-/tmp}/mosaic-pr-review-getid.XXXXXX")
    trap 'rm -f "$write_file" "$readback_file"' RETURN

    if ! write_status=$(curl -sS -o "$write_file" -w '%{http_code}' \
        -X POST \
        -H "Authorization: token $GITEA_API_TOKEN" \
        -H 'Content-Type: application/json' \
        -d "$payload" \
        "$GITEA_API_BASE/pulls/$pr_number/reviews"); then
        echo "Error: Gitea review submit transport failed" >&2
        return 1
    fi
    # Gitea returns 200 (occasionally 201) with the created review object.
    if [[ "$write_status" != "200" && "$write_status" != "201" ]]; then
        echo "Error: Gitea review submit failed with HTTP $write_status (#865: no durable review created)" >&2
        return 1
    fi

    created_id=$(python3 - "$write_file" <<'PY'
import json
import sys

try:
    with open(sys.argv[1], encoding="utf-8") as response:
        review = json.load(response)
    created_id = review.get("id") if isinstance(review, dict) else None
    if not isinstance(created_id, int) or created_id <= 0:
        raise ValueError("submit response carried no positive review id")
except (OSError, json.JSONDecodeError, ValueError) as error:
    print(f"Error: could not identify created Gitea review: {error}", file=sys.stderr)
    raise SystemExit(1)
print(created_id)
PY
) || return 1

    if ! readback_status=$(curl -sS -o "$readback_file" -w '%{http_code}' \
        -H "Authorization: token $GITEA_API_TOKEN" \
        "$GITEA_API_BASE/pulls/$pr_number/reviews/$created_id"); then
        echo "Error: Gitea review read-back transport failed" >&2
        return 1
    fi
    if [[ "$readback_status" != "200" ]]; then
        echo "Error: Gitea review read-back failed with HTTP $readback_status" >&2
        return 1
    fi

    EXPECTED_REVIEW_ID="$created_id" EXPECTED_STATE="$event" ACTING_LOGIN="$acting_login" \
        EXPECTED_HEAD_SHA="$head_sha" \
        python3 - "$readback_file" <<'PY' || return 1
import json
import os
import sys

try:
    with open(sys.argv[1], encoding="utf-8") as response:
        review = json.load(response)
    if not isinstance(review, dict):
        raise ValueError("response is not a review object")
    expected_id = int(os.environ["EXPECTED_REVIEW_ID"])
    expected_state = os.environ["EXPECTED_STATE"]
    acting_login = os.environ["ACTING_LOGIN"]
    expected_head = os.environ["EXPECTED_HEAD_SHA"]
    if review.get("id") != expected_id:
        raise ValueError("read-back id does not match the created id")
    if (review.get("user") or {}).get("login") != acting_login:
        raise ValueError("created review is not authored by the acting identity")
    if review.get("state") != expected_state:
        raise ValueError("created review is not in the expected state")
    if review.get("commit_id") != expected_head:
        raise ValueError("created review is not pinned to the PR head commit")
except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as error:
    print(f"Error: Gitea review persistence verification failed: {error}", file=sys.stderr)
    raise SystemExit(1)
PY

    gitea_confirm_review_enumerable "$pr_number" "$created_id" "$event" "$acting_login" || return 1

    echo "$created_id"
    return 0
}

if [[ "$PLATFORM" == "github" ]]; then
    case $ACTION in
        approve)
            gh pr review "$PR_NUMBER" --approve ${COMMENT:+--body "$COMMENT"}
            echo "Approved GitHub PR #$PR_NUMBER"
            ;;
        request-changes)
            if [[ -z "$COMMENT" ]]; then
                echo "Error: Comment required for request-changes"
                exit 1
            fi
            gh pr review "$PR_NUMBER" --request-changes --body "$COMMENT"
            echo "Requested changes on GitHub PR #$PR_NUMBER"
            ;;
        comment)
            if [[ -z "$COMMENT" ]]; then
                echo "Error: Comment required"
                exit 1
            fi
            gh pr review "$PR_NUMBER" --comment --body "$COMMENT"
            echo "Added review comment to GitHub PR #$PR_NUMBER"
            ;;
        *)
            echo "Error: Unknown action: $ACTION"
            exit 1
            ;;
    esac
elif [[ "$PLATFORM" == "gitea" ]]; then
    case $ACTION in
        approve)
            host=$(get_remote_host)
            # A --login override always wins. Otherwise name this host's login
            # only as a best effort: the login name merely selects a per-login
            # token, and gitea_resolve_api_for_login falls back to the host
            # credential (get_gitea_token) when no tea login is named — so a host
            # tea's login list need not enumerate exotic (e.g. ported) hosts for
            # the default credential to resolve. The single resolved token is
            # then used for the write, the /user identity, and the read-back.
            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
            # Bind the REST endpoint + token to the effective login, then derive
            # the acting identity from that SAME credential so the review submit
            # and its read-back verify against the identity that performed them.
            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" || exit 1
            ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
            head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
            # The review body (if any) travels with the review itself in the REST
            # submit — the created review record carries it — so there is no
            # separate detached comment to reconcile.
            review_id=$(gitea_submit_review_verified "$PR_NUMBER" "APPROVED" "$COMMENT" "$ACTING_LOGIN" "$head_sha") || {
                echo "Error: could not submit and verify an APPROVED review on Gitea PR #$PR_NUMBER via a provider-returned created id (#865)." >&2
                exit 1
            }
            echo "Approved and verified Gitea PR #$PR_NUMBER (review ID $review_id)"
            ;;
        request-changes)
            if [[ -z "$COMMENT" ]]; then
                echo "Error: Comment required for request-changes"
                exit 1
            fi
            host=$(get_remote_host)
            # A --login override always wins. Otherwise name this host's login
            # only as a best effort: the login name merely selects a per-login
            # token, and gitea_resolve_api_for_login falls back to the host
            # credential (get_gitea_token) when no tea login is named — so a host
            # tea's login list need not enumerate exotic (e.g. ported) hosts for
            # the default credential to resolve. The single resolved token is
            # then used for the write, the /user identity, and the read-back.
            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" || exit 1
            ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
            head_sha=$(gitea_pr_head_sha "$PR_NUMBER") || exit 1
            review_id=$(gitea_submit_review_verified "$PR_NUMBER" "REQUEST_CHANGES" "$COMMENT" "$ACTING_LOGIN" "$head_sha") || {
                echo "Error: could not submit and verify a REQUEST_CHANGES review on Gitea PR #$PR_NUMBER via a provider-returned created id (#865)." >&2
                exit 1
            }
            echo "Requested changes and verified on Gitea PR #$PR_NUMBER (review ID $review_id)"
            ;;
        comment)
            if [[ -z "$COMMENT" ]]; then
                echo "Error: Comment required"
                exit 1
            fi
            host=$(get_remote_host)
            # A --login override always wins. Otherwise name this host's login
            # only as a best effort: the login name merely selects a per-login
            # token, and gitea_resolve_api_for_login falls back to the host
            # credential (get_gitea_token) when no tea login is named — so a host
            # tea's login list need not enumerate exotic (e.g. ported) hosts for
            # the default credential to resolve. The single resolved token is
            # then used for the write, the /user identity, and the read-back.
            EFFECTIVE_LOGIN="$LOGIN_OVERRIDE"
            [[ -n "$EFFECTIVE_LOGIN" ]] || EFFECTIVE_LOGIN=$(get_gitea_login_for_host "$host" 2>/dev/null || true)
            gitea_resolve_api_for_login "$EFFECTIVE_LOGIN" || exit 1
            ACTING_LOGIN=$(gitea_authenticated_login) || exit 1
            comment_id=$(gitea_create_comment_verified "$PR_NUMBER" "$COMMENT" "$ACTING_LOGIN") || {
                echo "Error: could not create and verify a comment on Gitea PR #$PR_NUMBER via a provider-returned created id (#865)." >&2
                exit 1
            }
            echo "Added and verified comment on Gitea PR #$PR_NUMBER (comment ID $comment_id)"
            ;;
        *)
            echo "Error: Unknown action: $ACTION"
            exit 1
            ;;
    esac
else
    echo "Error: Unknown platform"
    exit 1
fi