bb

#!/usr/bin/env bash
#
# bb - Bitbucket CLI wrapper
#
# A local CLI for Bitbucket Cloud that wraps the REST API.
# Requires: curl, jq
#
# Configuration:
#   Set BB_USER, BB_TOKEN, and BB_WORKSPACE in ~/.config/bb/config
#   or as environment variables.
#
#   BB_WORKSPACE must be set (no default).
#
# Token setup:
#   1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
#   2. Create an API token
#   3. Set BB_USER to your Bitbucket email address
#   4. Set BB_TOKEN to the generated token
#

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
BB_API="https://api.bitbucket.org/2.0"

# --- Config loading ---

load_config() {
    # Snapshot env-provided values BEFORE sourcing the config files.
    # `source ~/.config/bb/config` runs `BB_USER=...` etc., which would
    # otherwise clobber values the user exported in their shell —
    # inverting the documented precedence (env vars are meant to be
    # highest priority) and diverging from the Python bb_api.load_config,
    # which resolves env first. We re-apply these snapshots after
    # sourcing so the env still wins.
    local _env_user="${BB_USER:-}" _env_token="${BB_TOKEN:-}"
    local _env_ws="${BB_WORKSPACE:-}" _env_api="${BB_API_BASE:-}"

    if [[ -f "$HOME/.config/bb/config" ]]; then
        # shellcheck source=/dev/null
        source "$HOME/.config/bb/config"
    fi
    if [[ -f "$SCRIPT_DIR/.env" ]]; then
        # shellcheck source=/dev/null
        source "$SCRIPT_DIR/.env"
    fi

    # Re-apply env snapshots (highest priority), matching the documented
    # order and the Python resolve() behaviour.
    [[ -n "$_env_user" ]] && BB_USER="$_env_user"
    [[ -n "$_env_token" ]] && BB_TOKEN="$_env_token"
    [[ -n "$_env_ws" ]] && BB_WORKSPACE="$_env_ws"
    [[ -n "$_env_api" ]] && BB_API_BASE="$_env_api"

    # Wire BB_API_BASE into the base URL every curl call uses. Without
    # this the variable was snapshotted + re-applied but never consulted,
    # so `BB_API_BASE=https://staging... bb prs` silently hit production
    # — and bb_api.py honours it, so the CLI was the odd one out. Strip a
    # trailing slash to match Python's api_base.rstrip("/") normalisation
    # (avoids "//path").
    if [[ -n "${BB_API_BASE:-}" ]]; then
        BB_API="${BB_API_BASE%/}"
    fi

    # BB_WORKSPACE is now OPTIONAL: when running inside a Bitbucket git
    # checkout, resolve_repo auto-detects the workspace from the origin
    # remote, and the -w/--workspace flag or a "workspace/slug" argument
    # can supply it per-command. Only BB_USER + BB_TOKEN are mandatory
    # (auth). A command that needs a workspace but can't resolve one
    # from any source fails at that point (resolve_repo / repo_path)
    # with a clear, actionable message.
    if [[ -z "${BB_USER:-}" || -z "${BB_TOKEN:-}" ]]; then
        echo "Error: BB_USER and BB_TOKEN must be set." >&2
        echo "" >&2
        echo "Quick setup:" >&2
        echo "  mkdir -p ~/.config/bb" >&2
        echo "  cat > ~/.config/bb/config <<EOF" >&2
        echo "BB_USER=your-email@example.com" >&2
        echo "BB_TOKEN=your-api-token" >&2
        echo "BB_WORKSPACE=your-workspace   # optional — auto-detected in a git checkout" >&2
        echo "EOF" >&2
        echo "" >&2
        echo "Create an API token at:" >&2
        echo "  https://id.atlassian.com/manage-profile/security/api-tokens" >&2
        echo "" >&2
        echo "BB_USER is your Bitbucket account email address." >&2
        exit 1
    fi
}

# --- API helpers ---

bb_get() {
    local path="$1"
    shift
    curl -sf -u "${BB_USER}:${BB_TOKEN}" "${BB_API}${path}" "$@"
}

bb_post() {
    local path="$1"
    local data="${2:-}"
    if [[ -n "$data" ]]; then
        curl -sf -u "${BB_USER}:${BB_TOKEN}" \
            -X POST -H "Content-Type: application/json" \
            -d "$data" "${BB_API}${path}"
    else
        curl -sf -u "${BB_USER}:${BB_TOKEN}" \
            -X POST "${BB_API}${path}"
    fi
}

bb_put() {
    local path="$1"
    local data="${2:-}"
    if [[ -n "$data" ]]; then
        curl -sf -u "${BB_USER}:${BB_TOKEN}" \
            -X PUT -H "Content-Type: application/json" \
            -d "$data" "${BB_API}${path}"
    else
        curl -sf -u "${BB_USER}:${BB_TOKEN}" \
            -X PUT "${BB_API}${path}"
    fi
}

bb_delete() {
    local path="$1"
    curl -sf -u "${BB_USER}:${BB_TOKEN}" -X DELETE "${BB_API}${path}"
}

# Resolve the (workspace, repo-slug) pair for a command from its
# optional repo argument, and publish the result by SETTING two
# variables in the CALLER's scope:
#   repo          — the repo slug
#   BB_WORKSPACE  — the workspace to operate in
#
# This is called WITHOUT command substitution (i.e. `resolve_repo "$1"`,
# not `repo=$(resolve_repo "$1")`) precisely so it runs in the caller's
# shell and its assignments to `repo` (a caller `local`, reached via
# bash dynamic scope) and `BB_WORKSPACE` (global) actually propagate.
# A subshell — which is what the old `detect_repo` ran in — cannot set
# the parent's workspace, which is why workspace auto-detect needs this
# shape.
#
# Resolution precedence (highest first) — mirrors the Python
# _resolve_repo contract in mcp_server.py:
#   1. -w/--workspace flag        (BB_WORKSPACE_OVERRIDE, set pre-dispatch)
#   2. explicit "workspace/slug"  (overrides workspace for this call)
#   3. git origin auto-detect     (workspace + slug from the remote URL)
#   4. BB_WORKSPACE default       (bare "slug" arg, or env/config default)
#   5. error                      (nothing resolved a workspace)
resolve_repo() {
    local arg="${1:-}"
    # A -w/--workspace flag locks the workspace: it beats both the git
    # origin and any "ws/slug" arg. Detected by BB_WORKSPACE_OVERRIDE
    # being set (the dispatcher records it before load_config).
    local ws_locked=""
    [[ -n "${BB_WORKSPACE_OVERRIDE:-}" ]] && ws_locked=1

    if [[ -z "$arg" ]]; then
        # (3) Auto-detect from the git origin remote.
        local remote_url
        remote_url=$(git remote get-url origin 2>/dev/null || true)
        if [[ -z "$remote_url" ]]; then
            echo "Error: no repo specified and not in a git repository." >&2
            echo "  Pass a repo (bb <cmd> myrepo) or workspace/repo" >&2
            echo "  (bb <cmd> acme/myrepo), or run inside a git checkout." >&2
            exit 1
        fi
        # Strip one trailing slash so `.../repo/` parses, then match the
        # tail. Greedy [^/]+ is fine here because we strip `.git`
        # afterward (bash ERE has no non-greedy quantifier, unlike the
        # Python _REMOTE_TAIL regex — same end result via the %.git
        # parameter expansion below).
        remote_url="${remote_url%/}"
        if [[ "$remote_url" =~ [:/]([^/:]+)/([^/]+)$ ]]; then
            local detected_ws="${BASH_REMATCH[1]}"
            local detected_repo="${BASH_REMATCH[2]%.git}"
            repo="$detected_repo"
            # Flag wins over git-detected workspace; else use git's.
            [[ -z "$ws_locked" ]] && BB_WORKSPACE="$detected_ws"
        else
            echo "Error: could not parse workspace/repo from origin URL." >&2
            exit 1
        fi
    elif [[ "$arg" == */* ]]; then
        # (2) Explicit "workspace/slug" override.
        local arg_ws="${arg%%/*}"
        local arg_repo="${arg#*/}"
        if [[ "$arg_repo" == */* ]]; then
            echo "Error: repo must be 'slug' or 'workspace/slug' (one '/'), got '$arg'." >&2
            exit 1
        fi
        repo="$arg_repo"
        # The -w flag still wins over an inline ws/slug (flag is the
        # most explicit, per-invocation signal).
        [[ -z "$ws_locked" ]] && BB_WORKSPACE="$arg_ws"
    else
        # (4) Bare slug → use whatever BB_WORKSPACE already resolved to
        # (flag override, else env/config default). repo_path enforces
        # that BB_WORKSPACE is actually set and well-formed.
        repo="$arg"
    fi
}

# Resolve JUST the workspace for workspace-level commands that take no
# repo argument (e.g. `bb repos`). Sets BB_WORKSPACE in the caller's
# scope. Same precedence as resolve_repo, minus the slug:
#   1. -w/--workspace flag      (BB_WORKSPACE_OVERRIDE locks it)
#   2. git origin auto-detect   (workspace from the remote URL)
#   3. BB_WORKSPACE default     (env / config)
#   4. error
resolve_workspace() {
    # -w flag locks the workspace (most explicit signal).
    [[ -n "${BB_WORKSPACE_OVERRIDE:-}" ]] && return

    # git origin wins over the config default — "operate on where I am".
    local remote_url
    remote_url=$(git remote get-url origin 2>/dev/null || true)
    if [[ -n "$remote_url" ]]; then
        remote_url="${remote_url%/}"
        if [[ "$remote_url" =~ [:/]([^/:]+)/([^/]+)$ ]]; then
            BB_WORKSPACE="${BASH_REMATCH[1]}"
            return
        fi
    fi

    # Fall back to env/config BB_WORKSPACE; error if nothing resolved one.
    if [[ -z "${BB_WORKSPACE:-}" ]]; then
        echo "Error: no workspace resolved." >&2
        echo "  Set BB_WORKSPACE (env or ~/.config/bb/config), pass" >&2
        echo "  -w <workspace>, or run inside a Bitbucket git checkout." >&2
        exit 1
    fi
}

repo_path() {
    local repo="$1"
    # Validate inputs at the boundary so a malformed slug doesn't
    # silently construct a wrong URL (/repositories//foo or
    # /repositories/../foo). Mirrors the bb_api.repo_path Python
    # validation — both surfaces enforce the same contract.
    #
    # Whitespace check: reject if the value EQUALS its whitespace-
    # stripped form's emptiness. Catches all-whitespace AND mixed-
    # whitespace (e.g. ` acme ` which the previous `^[[:space:]]+$`
    # regex let through). `tr -d '[:space:]'` is true parity with
    # Python's `.strip()`.
    local _ws_stripped _repo_stripped
    _ws_stripped="$(printf '%s' "$BB_WORKSPACE" | tr -d '[:space:]')"
    _repo_stripped="$(printf '%s' "$repo" | tr -d '[:space:]')"
    if [[ -z "$_ws_stripped" || "$_ws_stripped" != "$BB_WORKSPACE" ]]; then
        echo "Error: BB_WORKSPACE must be a non-empty, non-whitespace string." >&2
        kill -TERM $$
    fi
    if [[ -z "$_repo_stripped" || "$_repo_stripped" != "$repo" ]]; then
        echo "Error: repo must be a non-empty, non-whitespace string." >&2
        kill -TERM $$
    fi
    if [[ "$BB_WORKSPACE" == *"/"* || "$repo" == *"/"* ]]; then
        echo "Error: workspace and repo must not contain '/'." >&2
        kill -TERM $$
    fi
    if [[ "$BB_WORKSPACE" == "." || "$BB_WORKSPACE" == ".." ]]; then
        echo "Error: workspace must not be '.' or '..'." >&2
        kill -TERM $$
    fi
    if [[ "$repo" == "." || "$repo" == ".." ]]; then
        echo "Error: repo must not be '.' or '..'." >&2
        kill -TERM $$
    fi
    # `exit 1` inside a `$(repo_path ...)` command substitution only
    # terminates the subshell — the caller would proceed with an
    # empty path. `kill -TERM $$` terminates the parent script so
    # the validation actually halts execution.
    echo "/repositories/${BB_WORKSPACE}/${repo}"
}

# Validate a build_number argument is a positive integer before
# splicing into a jq filter or URL. jq treats unquoted non-numeric
# identifiers as undefined-function references (e.g. `select(.x == abc)`
# becomes `abc/0 is not defined`), aborting under `set -e` with no
# curated error. A crafted value like `1) | $ENV.BB_TOKEN, .uuid` can
# also exfil environment via the jq filter's $ENV — validate the shape
# at the boundary so neither failure mode can fire.
_require_build_number() {
    if ! [[ "$1" =~ ^[0-9]+$ ]]; then
        echo "Error: build_number must be a positive integer (got ${1!r:-empty})." >&2
        exit 1
    fi
}

# Allowlist the PR state before it's interpolated into the request URL.
# Mirrors the Python _KNOWN_PR_STATES boundary check (bb_ops.py) — both
# surfaces reject anything outside the four valid states. Also closes a
# query-param injection surface: without this, `bb prs my-repo
# 'OPEN&pagelen=1000'` would smuggle extra query params into the URL.
_require_pr_state() {
    case "$1" in
        OPEN|MERGED|DECLINED|SUPERSEDED) ;;
        *)
            echo "Error: state must be one of OPEN, MERGED, DECLINED, SUPERSEDED (got '$1')." >&2
            exit 1
            ;;
    esac
}

# --- Formatting helpers ---

format_state() {
    local state="$1"
    case "$state" in
        COMPLETED)  echo "DONE" ;;
        SUCCESSFUL) echo "PASS" ;;
        RUNNING)    echo "RUN " ;;
        PENDING)    echo "WAIT" ;;
        FAILED)     echo "FAIL" ;;
        ERROR)      echo "ERR " ;;
        STOPPED)    echo "STOP" ;;
        PAUSED)     echo "HOLD" ;;
        HALTED)     echo "HALT" ;;
        OPEN)       echo "OPEN" ;;
        MERGED)     echo "MRGD" ;;
        DECLINED)   echo "DECL" ;;
        SUPERSEDED) echo "SUPD" ;;
        *)          echo "$state" ;;
    esac
}

format_duration() {
    local seconds="$1"
    if [[ "$seconds" -lt 60 ]]; then
        echo "${seconds}s"
    elif [[ "$seconds" -lt 3600 ]]; then
        echo "$((seconds / 60))m $((seconds % 60))s"
    else
        echo "$((seconds / 3600))h $((seconds % 3600 / 60))m"
    fi
}

# =========================================================================
#  PIPELINE COMMANDS
# =========================================================================

cmd_pipelines() {
    local repo
    resolve_repo "${1:-}"
    local count="${2:-10}"

    echo "Pipelines for ${BB_WORKSPACE}/${repo}:"
    echo ""

    local response
    response=$(bb_get "$(repo_path "$repo")/pipelines/?sort=-created_on&pagelen=${count}")

    printf "  %-7s %-6s %-22s %-18s %-12s %s\n" "BUILD" "STATE" "BRANCH" "TRIGGER" "DATE" "DURATION"
    printf "  %-7s %-6s %-22s %-18s %-12s %s\n" "-----" "-----" "------" "-------" "----" "--------"

    echo "$response" | jq -r '
        .values[] |
        [
            (.build_number | tostring),
            .state.name,
            (.state.result.name // .state.stage.name // "-"),
            (.target.ref_name // "n/a"),
            (.target.selector.pattern // .trigger.name // "-"),
            (.created_on | split("T") | .[0]),
            (.duration_in_seconds // 0 | tostring)
        ] | join("\t")
    ' | while IFS=$'\t' read -r num state result ref trigger date duration; do
        local display_state
        if [[ -n "$result" ]]; then
            display_state=$(format_state "$result")
        else
            display_state=$(format_state "$state")
        fi

        local dur_str="-"
        if [[ "$duration" != "0" && "$duration" != "null" ]]; then
            dur_str=$(format_duration "$duration")
        fi

        printf "  #%-6s %-6s %-22s %-18s %-12s %s\n" \
            "$num" "$display_state" "$ref" "$trigger" "$date" "$dur_str"
    done
}

cmd_pipeline() {
    local repo
    resolve_repo "${1:-}"
    local build_number="${2:-}"

    if [[ -z "$build_number" ]]; then
        echo "Usage: bb pipeline [repo] <build-number>" >&2
        exit 1
    fi
    _require_build_number "$build_number"

    # Parity fix: bumped pagelen 50→100 (Bitbucket's max). Older
    # pipelines still unfindable beyond 100; full pagination is
    # the Python-side improvement.
    local response
    response=$(bb_get "$(repo_path "$repo")/pipelines/?sort=-created_on&pagelen=100")

    local pipeline_uuid
    pipeline_uuid=$(echo "$response" | jq -r ".values[] | select(.build_number == ${build_number}) | .uuid" | tr -d '{}')

    if [[ -z "$pipeline_uuid" ]]; then
        echo "Pipeline #${build_number} not found." >&2
        exit 1
    fi

    local pipeline
    pipeline=$(bb_get "$(repo_path "$repo")/pipelines/%7B${pipeline_uuid}%7D")

    echo "Pipeline #${build_number} - ${BB_WORKSPACE}/${repo}"
    echo ""
    echo "$pipeline" | jq -r '
        "  Branch:   " + (.target.ref_name // "n/a"),
        "  Trigger:  " + (.target.selector.pattern // .trigger_name // "n/a"),
        "  State:    " + .state.name + (if .state.result then " / " + .state.result.name else "" end),
        "  Created:  " + .created_on,
        "  Duration: " + (if .duration_in_seconds then (.duration_in_seconds | tostring) + "s" else "in progress" end)
    '

    echo ""
    echo "  Steps:"

    local steps
    steps=$(bb_get "$(repo_path "$repo")/pipelines/%7B${pipeline_uuid}%7D/steps/?pagelen=50")

    echo "$steps" | jq -r '
        .values[] |
        "    " +
        (if .state.result then .state.result.name else .state.name end) +
        "  " + .name +
        (if .duration_in_seconds then " (" + (.duration_in_seconds | tostring) + "s)" else "" end)
    '
}

cmd_watch() {
    local repo
    resolve_repo "${1:-}"
    local build_number="${2:-}"
    local poll_interval="${3:-15}"

    if [[ -z "$build_number" ]]; then
        local latest
        latest=$(bb_get "$(repo_path "$repo")/pipelines/?sort=-created_on&pagelen=1")
        build_number=$(echo "$latest" | jq -r '.values[0].build_number')
        echo "Watching most recent pipeline: #${build_number}"
    fi
    _require_build_number "$build_number"

    echo "Watching pipeline #${build_number} on ${BB_WORKSPACE}/${repo} (every ${poll_interval}s)..."
    echo ""

    while true; do
        # Parity fix: bumped pagelen 50 → 100, symmetric with
        # cmd_pipeline / cmd_pipeline_stop / cmd_logs. Without this
        # bump, a pipeline at positions 51-100 in the recent list
        # would never match here and the watch loop would spin
        # forever printing blanks.
        local response
        response=$(bb_get "$(repo_path "$repo")/pipelines/?sort=-created_on&pagelen=100")

        local state result duration ref
        IFS=$'\t' read -r state result duration ref < <(echo "$response" | jq -r "
            .values[] | select(.build_number == ${build_number}) |
            [.state.name, (.state.result.name // \"-\"), (.duration_in_seconds // 0 | tostring), (.target.ref_name // \"n/a\")] | join(\"\t\")
        ")

        local display_state
        if [[ -n "$result" && "$result" != "-" ]]; then
            display_state=$(format_state "$result")
        else
            display_state=$(format_state "$state")
        fi

        local dur_str=""
        if [[ "$duration" =~ ^[0-9]+$ && "$duration" != "0" ]]; then
            dur_str=" ($(format_duration "$duration"))"
        fi

        printf "\r  #%-6s %-6s %-22s%s    " "$build_number" "$display_state" "$ref" "$dur_str"

        if [[ "$state" == "COMPLETED" ]]; then
            echo ""
            echo ""
            echo "Pipeline finished: ${result}"
            cmd_pipeline "$repo" "$build_number" 2>/dev/null | grep -A 100 "Steps:" || true
            return 0
        fi

        sleep "$poll_interval"
    done
}

cmd_logs() {
    local repo
    resolve_repo "${1:-}"
    local build_number="${2:-}"
    local step_index="${3:-}"

    if [[ -z "$build_number" ]]; then
        echo "Usage: bb logs [repo] <build-number> [step-index]" >&2
        exit 1
    fi
    _require_build_number "$build_number"

    # Parity fix: bumped pagelen 50→100 (Bitbucket's max). Symmetric
    # with cmd_pipeline_stop / cmd_pipeline.
    local response
    response=$(bb_get "$(repo_path "$repo")/pipelines/?sort=-created_on&pagelen=100")

    local pipeline_uuid
    pipeline_uuid=$(echo "$response" | jq -r ".values[] | select(.build_number == ${build_number}) | .uuid" | tr -d '{}')

    if [[ -z "$pipeline_uuid" ]]; then
        echo "Pipeline #${build_number} not found." >&2
        exit 1
    fi

    local steps
    steps=$(bb_get "$(repo_path "$repo")/pipelines/%7B${pipeline_uuid}%7D/steps/?pagelen=50")

    if [[ -z "$step_index" ]]; then
        echo "Steps for pipeline #${build_number}:"
        echo ""
        echo "$steps" | jq -r '
            .values | to_entries[] |
            "  [" + (.key | tostring) + "] " + .value.name +
            " (" + (if .value.state.result then .value.state.result.name else .value.state.name end) + ")"
        '
        echo ""
        echo "Usage: bb logs ${repo} ${build_number} <step-index>"
        return
    fi

    local step_uuid
    step_uuid=$(echo "$steps" | jq -r ".values[${step_index}].uuid" | tr -d '{}')

    if [[ "$step_uuid" == "null" || -z "$step_uuid" ]]; then
        echo "Step index ${step_index} not found." >&2
        exit 1
    fi

    local step_name
    step_name=$(echo "$steps" | jq -r ".values[${step_index}].name")
    echo "Logs for step [${step_index}] ${step_name}:"
    echo ""

    curl -sfL -u "${BB_USER}:${BB_TOKEN}" \
        "${BB_API}$(repo_path "$repo")/pipelines/%7B${pipeline_uuid}%7D/steps/%7B${step_uuid}%7D/log" \
        2>/dev/null || echo "(no log output available)"
}

cmd_pipeline_trigger() {
    local repo
    resolve_repo "${1:-}"
    local branch="${2:-}"
    local pattern="${3:-}"

    # `shift 3 || true` previously masked the under-3-args case:
    # bash leaves $@ unchanged when the shift count exceeds $#, so
    # `bb trigger myrepo` (1 arg) left "myrepo" in $@ and the
    # var-loop below parsed it as a VAR=VALUE pair, sending
    # {"key":"myrepo","value":"myrepo"} as a pipeline variable.
    # Guard explicitly.
    if [[ $# -ge 3 ]]; then
        shift 3
    else
        # Consume what's there; remaining $@ is empty.
        shift $#
    fi

    # Remaining args are VAR=VALUE pairs. Build the array via `jq`
    # so values containing `"`, `\`, newlines, or tabs are correctly
    # JSON-escaped. NUL delimiter (not newline) so values containing
    # newlines aren't fragmented into ghost vars — the previous
    # newline-split approach would turn VAR=$'line1\nline2' into a
    # real {VAR:line1} entry plus a ghost {line2:""} entry. jq's
    # split("") on a NUL-delimited stream sidesteps that.
    local variables="[]"
    if [[ $# -gt 0 ]]; then
        # Per-pair shape: split on the FIRST `=` only so values
        # containing `=` survive intact.
        variables=$(printf '%s\0' "$@" | jq -Rs '
            split("")
            | map(select(length > 0))
            | map(
                split("=") | {
                    key: .[0],
                    value: (.[1:] | join("="))
                }
            )
        ')
    fi

    if [[ -z "$branch" ]]; then
        branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
        # git rev-parse exits 0 with literal "HEAD" on detached HEAD —
        # Bitbucket would 400 on ref_name=HEAD. Surface a clean error.
        if [[ "$branch" == "HEAD" ]]; then
            echo "Error: detached HEAD detected. Pass an explicit branch." >&2
            exit 1
        fi
    fi

    # Parity fix: previously the no-pattern branch built `{target: {...}}`
    # WITHOUT the variables field, silently dropping any VAR=value args
    # the user passed. Build the payload incrementally so variables always
    # land in the request when provided, regardless of pattern.
    local payload
    if [[ "$variables" != "[]" ]]; then
        if [[ -n "$pattern" ]]; then
            payload=$(jq -n \
                --arg ref "$branch" \
                --arg pat "$pattern" \
                --argjson vars "$variables" \
                '{target: {ref_name: $ref, ref_type: "branch", selector: {type: "custom", pattern: $pat}}, variables: $vars}')
        else
            payload=$(jq -n \
                --arg ref "$branch" \
                --argjson vars "$variables" \
                '{target: {ref_name: $ref, ref_type: "branch"}, variables: $vars}')
        fi
    else
        # No variables → omit the key entirely (matches Python's
        # omit-when-empty contract).
        if [[ -n "$pattern" ]]; then
            payload=$(jq -n \
                --arg ref "$branch" \
                --arg pat "$pattern" \
                '{target: {ref_name: $ref, ref_type: "branch", selector: {type: "custom", pattern: $pat}}}')
        else
            payload=$(jq -n --arg ref "$branch" '{target: {ref_name: $ref, ref_type: "branch"}}')
        fi
    fi

    echo "Triggering pipeline on ${BB_WORKSPACE}/${repo} branch ${branch}..."
    if [[ -n "$pattern" ]]; then
        echo "  Custom pipeline: ${pattern}"
    fi
    if [[ "$variables" != "[]" ]]; then
        # Echo variable KEYS only — values may be secrets (API tokens,
        # deploy creds) that the user passed as VAR=value. The previous
        # `Variables: $*` form leaked the full value into stdout /
        # terminal scrollback / CI logs / shell history.
        local masked
        masked=$(printf '%s\n' "$@" | sed -E 's/=.*$/=***/' | tr '\n' ' ')
        echo "  Variables: ${masked%% }"
    fi

    # rc-capture pattern: capture the exit code so a 4xx (protected
    # branch, custom pipeline name not found, invalid variable shape)
    # surfaces as a labelled error instead of `set -e` silently
    # aborting after the "Triggering pipeline..." banner.
    # Capture rc via `|| rc=$?`, not `if ! cmd; then rc=$?` — the
    # latter sets $? to the negation (always 0), so the real exit code
    # was being lost and `exit $rc` exited 0 on failure. Verified on
    # bash 3.2 and 5.x.
    local response rc=0
    response=$(bb_post "$(repo_path "$repo")/pipelines/" "$payload") || rc=$?
    if [[ "$rc" -ne 0 ]]; then
        echo "Trigger request failed for ${BB_WORKSPACE}/${repo} branch ${branch} (exit $rc)." >&2
        echo "  Common causes: protected branch, custom pipeline name not" >&2
        echo "  found, or invalid variable shape." >&2
        exit "$rc"
    fi

    local build_num
    build_num=$(echo "$response" | jq -r '.build_number')
    echo "Started pipeline #${build_num}"
    echo ""
    echo "Watch with: bb watch ${repo} ${build_num}"
}

cmd_pipeline_stop() {
    local repo
    resolve_repo "${1:-}"
    local build_number="${2:-}"

    if [[ -z "$build_number" ]]; then
        echo "Usage: bb pipeline-stop [repo] <build-number>" >&2
        exit 1
    fi
    _require_build_number "$build_number"

    # Parity fix: previously scanned only 50 most-recent pipelines, so
    # older builds were unfindable. Bumped to 100 (Bitbucket's max
    # pagelen) which covers ~2x more in a single page without
    # implementing full pagination in bash. The Python side paginates
    # up to 2000 — this is a partial parity step.
    local response
    response=$(bb_get "$(repo_path "$repo")/pipelines/?sort=-created_on&pagelen=100")

    local pipeline_uuid
    pipeline_uuid=$(echo "$response" | jq -r ".values[] | select(.build_number == ${build_number}) | .uuid" | tr -d '{}')

    if [[ -z "$pipeline_uuid" ]]; then
        echo "Pipeline #${build_number} not found in the 100 most-recent pipelines." >&2
        exit 1
    fi

    # Parity fix: previously discarded the API response with > /dev/null.
    # Now capture exit code so a stop failure (already-stopped pipeline,
    # 4xx, etc.) surfaces to the user instead of being masked.
    if bb_post "$(repo_path "$repo")/pipelines/%7B${pipeline_uuid}%7D/stopPipeline" > /dev/null; then
        echo "Stopped pipeline #${build_number}"
    else
        local rc=$?
        echo "Stop request failed for pipeline #${build_number} (exit $rc)." >&2
        exit $rc
    fi
}

cmd_pipeline_approve() {
    local repo
    resolve_repo "${1:-}"
    local build_number="${2:-}"

    if [[ -z "$build_number" ]]; then
        echo "Usage: bb approve [repo] <build-number>" >&2
        exit 1
    fi

    echo "Manual step approval is not supported by the Bitbucket public API."
    echo "Opening pipeline in browser..."
    echo ""

    local url="https://bitbucket.org/${BB_WORKSPACE}/${repo}/addon/pipelines/home#!/results/${build_number}"
    echo "  ${url}"
    open "$url" 2>/dev/null || xdg-open "$url" 2>/dev/null || true
}

# =========================================================================
#  PULL REQUEST COMMANDS
# =========================================================================

cmd_pr_list() {
    local repo state
    # State-recognition: `bb prs MERGED` from inside a checkout means
    # "MERGED PRs in this repo", not "a repo named MERGED". If the first
    # arg is a bare state name (matched case-INSENSITIVELY, so `merged`
    # works too), treat it as the state and auto-detect the repo.
    # Otherwise the first arg is the repo ([repo] [state] positional
    # form, unchanged).
    #
    # Tradeoff: because the match is case-insensitive, a repo literally
    # named "open"/"merged"/"declined"/"superseded" (any case) would be
    # read as a state and shadowed — you'd reach it via the explicit
    # `bb prs <workspace>/open` form. Accepted: such a repo name is
    # vanishingly unlikely, and the explicit form is always available
    # as an escape hatch.
    local _arg1_upper
    _arg1_upper="$(printf '%s' "${1:-}" | tr '[:lower:]' '[:upper:]')"
    case "$_arg1_upper" in
        OPEN|MERGED|DECLINED|SUPERSEDED)
            resolve_repo ""
            state="$_arg1_upper"
            ;;
        *)
            resolve_repo "${1:-}"
            state="$(printf '%s' "${2:-OPEN}" | tr '[:lower:]' '[:upper:]')"
            ;;
    esac
    _require_pr_state "$state"

    echo "Pull requests for ${BB_WORKSPACE}/${repo} [${state}]:"
    echo ""

    local response
    response=$(bb_get "$(repo_path "$repo")/pullrequests?state=${state}&pagelen=25")

    local count
    count=$(echo "$response" | jq '.size')

    if [[ "$count" == "0" ]]; then
        # Use `tr` instead of `${state,,}` for bash 3.x compatibility.
        # macOS ships bash 3.2 at /bin/bash and `#!/usr/bin/env bash`
        # finds it before Homebrew bash on the default PATH, so the
        # lowercase-substitution syntax would fail this branch only
        # (when count==0) — and only on macOS where it bites hardest.
        # Use printf '%s' rather than echo to neutralize leading-dash
        # values (echo would interpret `-n` / `-e` / `-E` as flags); not
        # a real risk for Bitbucket states (OPEN/MERGED/DECLINED/...)
        # but bulletproof and only marginally longer.
        echo "  No $(printf '%s' "$state" | tr '[:upper:]' '[:lower:]') pull requests."
        return
    fi

    printf "  %-6s %-6s %-30s %-20s %s\n" "PR" "STATE" "TITLE" "BRANCH" "AUTHOR"
    printf "  %-6s %-6s %-30s %-20s %s\n" "--" "-----" "-----" "------" "------"

    echo "$response" | jq -r '
        .values[] |
        [
            .id,
            .state,
            (.title | if length > 28 then .[:28] + ".." else . end),
            (.source.branch.name | if length > 18 then .[:18] + ".." else . end),
            .author.display_name
        ] | @tsv
    ' | while IFS=$'\t' read -r id state title branch author; do
        local display_state
        display_state=$(format_state "$state")
        printf "  #%-5s %-6s %-30s %-20s %s\n" "$id" "$display_state" "$title" "$branch" "$author"
    done
}

cmd_pr_view() {
    local repo
    resolve_repo "${1:-}"
    local pr_id="${2:-}"

    if [[ -z "$pr_id" ]]; then
        echo "Usage: bb pr-view [repo] <pr-id>" >&2
        exit 1
    fi

    local response
    response=$(bb_get "$(repo_path "$repo")/pullrequests/${pr_id}")

    echo "$response" | jq -r '
        "PR #" + (.id | tostring) + " - " + .title,
        "",
        "  State:       " + .state,
        "  Author:      " + .author.display_name,
        "  Source:      " + .source.branch.name,
        "  Destination: " + .destination.branch.name,
        "  Created:     " + .created_on,
        "  Updated:     " + .updated_on,
        "  Link:        " + .links.html.href,
        "",
        "  Description:",
        "  " + (.description // "(none)")
    '

    echo ""
    echo "  Reviewers:"
    echo "$response" | jq -r '
        if (.reviewers | length) == 0 then "    (none)"
        else .reviewers[] | "    - " + .display_name
        end
    '

    # Show approval status
    local activity
    activity=$(bb_get "$(repo_path "$repo")/pullrequests/${pr_id}/activity?pagelen=50" 2>/dev/null || echo '{"values":[]}')

    echo ""
    echo "  Approvals:"
    local approvals
    approvals=$(echo "$activity" | jq -r '
        [.values[] | select(.approval) | .approval.user.display_name] | unique | .[]
    ' 2>/dev/null || true)

    if [[ -z "$approvals" ]]; then
        echo "    (none)"
    else
        echo "$approvals" | while read -r name; do
            echo "    + ${name}"
        done
    fi
}

cmd_pr_create() {
    local repo
    resolve_repo "${1:-}"
    local title="${2:-}"
    local dest="${3:-main}"

    local source_branch
    source_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)

    if [[ -z "$source_branch" || "$source_branch" == "HEAD" ]]; then
        echo "Error: Not on a branch. Check out a branch first." >&2
        exit 1
    fi

    if [[ -z "$title" ]]; then
        echo "Usage: bb pr-create [repo] <title> [dest-branch]" >&2
        echo "" >&2
        echo "  Creates a PR from current branch (${source_branch}) to dest (default: main)" >&2
        exit 1
    fi

    # Read description from stdin if piped, otherwise empty.
    local description=""
    if [[ ! -t 0 ]]; then
        description=$(cat)
    fi

    # Parity fix: omit `description` from the payload when empty so it
    # matches the Python omit-when-empty contract (bb_ops.pr_create).
    # close_source_branch hardcoded to true matches bb_ops's default
    # too; both surfaces could expose this as a flag in a future PR.
    local payload
    if [[ -n "$description" ]]; then
        payload=$(jq -n \
            --arg title "$title" \
            --arg desc "$description" \
            --arg src "$source_branch" \
            --arg dst "$dest" \
            '{
                title: $title,
                description: $desc,
                source: {branch: {name: $src}},
                destination: {branch: {name: $dst}},
                close_source_branch: true
            }')
    else
        payload=$(jq -n \
            --arg title "$title" \
            --arg src "$source_branch" \
            --arg dst "$dest" \
            '{
                title: $title,
                source: {branch: {name: $src}},
                destination: {branch: {name: $dst}},
                close_source_branch: true
            }')
    fi

    echo "Creating PR: ${source_branch} -> ${dest}"

    # rc-capture pattern: a 400 (typo in dest branch, duplicate PR
    # already open, source branch not pushed, etc.) makes bb_post
    # exit non-zero and `set -e` would silently abort after the
    # "Creating PR:" banner. Without a labelled error, a user
    # retrying assuming a network blip might create a duplicate.
    # Capture rc via `|| rc=$?`, not `if ! cmd; then rc=$?` — the
    # latter sets $? to the negation (always 0), so the real exit code
    # was being lost and `exit $rc` exited 0 on failure. Verified on
    # bash 3.2 and 5.x.
    local response rc=0
    response=$(bb_post "$(repo_path "$repo")/pullrequests" "$payload") || rc=$?
    if [[ "$rc" -ne 0 ]]; then
        echo "PR-create request failed (exit $rc)." >&2
        echo "  Common causes: dest branch typo, a PR with this source" >&2
        echo "  branch is already open, source branch not pushed." >&2
        exit "$rc"
    fi

    local pr_id pr_url
    pr_id=$(echo "$response" | jq -r '.id')
    pr_url=$(echo "$response" | jq -r '.links.html.href')

    echo "Created PR #${pr_id}: ${title}"
    echo "  ${pr_url}"
}

cmd_pr_approve() {
    local repo
    resolve_repo "${1:-}"
    local pr_id="${2:-}"

    if [[ -z "$pr_id" ]]; then
        echo "Usage: bb pr-approve [repo] <pr-id>" >&2
        exit 1
    fi

    # Parity fix: capture exit code so an approve failure (already
    # approved, 4xx, etc.) surfaces to the user instead of being
    # masked by the unconditional success print.
    if bb_post "$(repo_path "$repo")/pullrequests/${pr_id}/approve" > /dev/null; then
        echo "Approved PR #${pr_id}"
    else
        local rc=$?
        echo "Approve request failed for PR #${pr_id} (exit $rc)." >&2
        exit $rc
    fi
}

cmd_pr_unapprove() {
    local repo
    resolve_repo "${1:-}"
    local pr_id="${2:-}"

    if [[ -z "$pr_id" ]]; then
        echo "Usage: bb pr-unapprove [repo] <pr-id>" >&2
        exit 1
    fi

    # Bitbucket's contract: DELETE the same /approve subpath that
    # POST uses for approval. Parity with bb_ops.pr_unapprove.
    if bb_delete "$(repo_path "$repo")/pullrequests/${pr_id}/approve" > /dev/null; then
        echo "Removed approval on PR #${pr_id}"
    else
        local rc=$?
        echo "Unapprove request failed for PR #${pr_id} (exit $rc)." >&2
        exit $rc
    fi
}

cmd_pr_merge() {
    local repo
    resolve_repo "${1:-}"
    local pr_id="${2:-}"
    local strategy="${3:-merge_commit}"

    if [[ -z "$pr_id" ]]; then
        echo "Usage: bb pr-merge [repo] <pr-id> [strategy]" >&2
        echo "  Strategies: merge_commit (default), squash, fast_forward" >&2
        exit 1
    fi

    # Validate strategy against Bitbucket's accepted set so a typo
    # (e.g. "squash_commit") fails locally with a clear message
    # instead of getting an opaque 400 from the API.
    case "$strategy" in
        merge_commit|squash|fast_forward) ;;
        *)
            echo "Error: invalid strategy '${strategy}'." >&2
            echo "  Valid: merge_commit, squash, fast_forward." >&2
            exit 1
            ;;
    esac

    local payload
    payload=$(jq -n --arg strategy "$strategy" \
        '{type: "pullrequest", merge_strategy: $strategy, close_source_branch: true}')

    # Parity fix: capture exit code so a merge conflict / failing
    # required check / wrong-strategy-for-repo error surfaces as a
    # labelled error instead of silently aborting under set -e.
    if bb_put "$(repo_path "$repo")/pullrequests/${pr_id}/merge" "$payload" > /dev/null; then
        echo "Merged PR #${pr_id} (${strategy})"
    else
        local rc=$?
        echo "Merge request failed for PR #${pr_id} (exit $rc)." >&2
        echo "  Common causes: unresolved comments, failing required" >&2
        echo "  builds, or wrong merge strategy for this repo." >&2
        exit $rc
    fi
}

cmd_pr_decline() {
    local repo
    resolve_repo "${1:-}"
    local pr_id="${2:-}"

    if [[ -z "$pr_id" ]]; then
        echo "Usage: bb pr-decline [repo] <pr-id>" >&2
        exit 1
    fi

    # Parity fix: capture exit code (was previously discarded).
    if bb_post "$(repo_path "$repo")/pullrequests/${pr_id}/decline" > /dev/null; then
        echo "Declined PR #${pr_id}"
    else
        local rc=$?
        echo "Decline request failed for PR #${pr_id} (exit $rc)." >&2
        exit $rc
    fi
}

cmd_pr_diff() {
    local repo
    resolve_repo "${1:-}"
    local pr_id="${2:-}"

    if [[ -z "$pr_id" ]]; then
        echo "Usage: bb pr-diff [repo] <pr-id>" >&2
        exit 1
    fi

    # Parity fix: -L so we follow any redirect Bitbucket introduces on
    # this endpoint (today it serves inline, but future-proofing).
    # `curl -L -u` does NOT resend credentials to a different host by
    # default, so the cross-host credential-leak concern is already
    # mitigated by curl semantics.
    curl -sfL -u "${BB_USER}:${BB_TOKEN}" \
        "${BB_API}$(repo_path "$repo")/pullrequests/${pr_id}/diff"
}

cmd_pr_comments() {
    local repo
    resolve_repo "${1:-}"
    local pr_id="${2:-}"

    if [[ -z "$pr_id" ]]; then
        echo "Usage: bb pr-comments [repo] <pr-id>" >&2
        exit 1
    fi

    local response
    response=$(bb_get "$(repo_path "$repo")/pullrequests/${pr_id}/comments?pagelen=100")

    echo "Comments on PR #${pr_id}:"
    echo ""

    echo "$response" | jq -r '
        .values[] |
        "  " + .user.display_name + " (" + (.created_on | split("T") | .[0]) + "):",
        "  " + (.content.raw // "(empty)"),
        ""
    '
}

cmd_pr_comment_add() {
    local repo
    resolve_repo "${1:-}"
    local pr_id="${2:-}"
    local body="${3:-}"

    if [[ -z "$pr_id" || -z "$body" ]]; then
        echo "Usage: bb pr-comment [repo] <pr-id> <body>" >&2
        echo "" >&2
        echo "  Add a top-level comment to PR #<pr-id>." >&2
        echo "  Use single quotes around <body> if it contains spaces or shell metacharacters." >&2
        exit 1
    fi

    # Bitbucket's contract: POST {"content": {"raw": "<text>"}}.
    # Parity with bb_ops.pr_comment_add.
    local payload
    payload=$(jq -n --arg body "$body" '{content: {raw: $body}}')

    local response
    response=$(bb_post "$(repo_path "$repo")/pullrequests/${pr_id}/comments" "$payload")

    local comment_id
    comment_id=$(echo "$response" | jq -r '.id // empty')
    if [[ -n "$comment_id" ]]; then
        echo "Posted comment #${comment_id} on PR #${pr_id}"
    else
        echo "Comment posted (response did not include an id)." >&2
        echo "$response" >&2
        exit 1
    fi
}

# =========================================================================
#  BRANCH COMMANDS
# =========================================================================

# URL-encode a single path segment (for branch names containing `/`).
# jq's @uri filter does this correctly; using jq avoids a Python /
# Perl dependency.
_url_encode_segment() {
    printf '%s' "$1" | jq -sRr @uri
}

cmd_branches() {
    local repo
    resolve_repo "${1:-}"

    echo "Branches for ${BB_WORKSPACE}/${repo}:"
    echo ""

    local response
    response=$(bb_get "$(repo_path "$repo")/refs/branches?pagelen=50&sort=-target.date")

    printf "  %-30s %-12s %s\n" "BRANCH" "DATE" "COMMIT"
    printf "  %-30s %-12s %s\n" "------" "----" "------"

    echo "$response" | jq -r '
        .values[] |
        [
            (.name | if length > 28 then .[:28] + ".." else . end),
            (.target.date | split("T") | .[0]),
            .target.hash[:8],
            .target.message[:50]
        ] | @tsv
    ' | while IFS=$'\t' read -r name date hash msg; do
        printf "  %-30s %-12s %s  %s\n" "$name" "$date" "$hash" "$msg"
    done
}

cmd_branch_show() {
    local repo
    resolve_repo "${1:-}"
    local name="${2:-}"

    if [[ -z "$name" ]]; then
        echo "Usage: bb branch [repo] <name>" >&2
        echo "" >&2
        echo "  Show details for a single branch. Branch names with '/'" >&2
        echo "  (e.g. feat/widget) are URL-encoded automatically." >&2
        exit 1
    fi

    # URL-encode the name so feat/widget isn't interpreted as a
    # sub-resource path by Bitbucket. Mirrors bb_ops.branch_show.
    local encoded
    encoded=$(_url_encode_segment "$name")

    local response
    response=$(bb_get "$(repo_path "$repo")/refs/branches/${encoded}")

    echo "Branch ${name} on ${BB_WORKSPACE}/${repo}:"
    echo ""
    echo "$response" | jq -r '
        "  Name:    " + .name,
        "  Hash:    " + .target.hash[:12],
        "  Date:    " + .target.date,
        "  Author:  " + (.target.author.user.display_name // .target.author.raw // "unknown"),
        "  Message: " + (.target.message // "(empty)" | split("\n") | .[0])
    '
}

cmd_commits() {
    local repo
    resolve_repo "${1:-}"
    local branch="${2:-}"
    local count="${3:-10}"

    local path response
    if [[ -n "$branch" ]]; then
        local encoded
        encoded=$(_url_encode_segment "$branch")
        path="$(repo_path "$repo")/commits/${encoded}?pagelen=${count}"
        echo "Recent commits on ${BB_WORKSPACE}/${repo} branch ${branch}:"
    else
        path="$(repo_path "$repo")/commits?pagelen=${count}"
        echo "Recent commits on ${BB_WORKSPACE}/${repo} (all branches):"
    fi
    echo ""

    response=$(bb_get "$path")

    printf "  %-10s %-12s %-22s %s\n" "HASH" "DATE" "AUTHOR" "MESSAGE"
    printf "  %-10s %-12s %-22s %s\n" "----" "----" "------" "-------"

    echo "$response" | jq -r '
        .values[] |
        [
            .hash[:8],
            (.date | split("T") | .[0]),
            (.author.user.display_name // .author.raw // "unknown" | .[:20]),
            (.message // "(empty)" | split("\n") | .[0] | .[:60])
        ] | @tsv
    ' | while IFS=$'\t' read -r hash date author msg; do
        printf "  %-10s %-12s %-22s %s\n" "$hash" "$date" "$author" "$msg"
    done
}

# =========================================================================
#  REPOSITORY COMMANDS
# =========================================================================

cmd_workspaces() {
    # GET /2.0/user/workspaces — the CHANGE-3022 replacement for the
    # cross-workspace listing endpoints removed under CHANGE-2770
    # (effective 2026-04-14). Workspace-scoped (no BB_WORKSPACE
    # involvement), so no -w override applies here.
    #
    # Requires `read:workspace:bitbucket` scope on the API token.
    # A token granted only repository/pullrequest/pipeline scopes
    # returns 403 — bb_get (`curl -sf`) exits non-zero WITHOUT printing
    # the body, so we can't echo Bitbucket's exact message; instead we
    # name the scope unconditionally on the error path so the user
    # knows the fix regardless.
    if [[ $# -gt 0 ]]; then
        echo "Usage: bb workspaces   (takes no arguments)" >&2
        exit 1
    fi

    echo "Workspaces accessible to ${BB_USER}:"
    echo ""

    # Capture rc via `|| rc=$?` rather than `if ! cmd; then rc=$?`.
    # The `!`-negation form sets $? to the LOGICAL NEGATION of the
    # command's status (always 0 for a failing command), so the real
    # curl exit code is unrecoverable inside an `if !` block — verified
    # on bash 3.2 and 5.x. curl -f exits 22 on an HTTP >=400 response;
    # other codes are transport-level (DNS, connection, TLS).
    local response rc=0
    response=$(bb_get "/user/workspaces?pagelen=100") || rc=$?
    if [[ "$rc" -ne 0 ]]; then
        echo "Workspace listing failed (exit $rc)." >&2
        if [[ "$rc" -eq 22 ]]; then
            echo "If this is a 403, the token lacks the read:workspace:bitbucket" >&2
            echo "scope. Rotate it at" >&2
            echo "https://id.atlassian.com/manage-profile/security/api-tokens" >&2
            echo "with that scope checked (existing scopes stay as they are)." >&2
        else
            echo "This looks like a connectivity error (not an HTTP response)." >&2
            echo "Check your network and that api.bitbucket.org is reachable." >&2
        fi
        exit "$rc"
    fi

    printf "  %-30s %s\n" "SLUG" "ROLE"
    printf "  %-30s %s\n" "----" "----"

    echo "$response" | jq -r '
        .values[] |
        [
            .workspace.slug,
            (if .administrator then "admin" else "member" end)
        ] | @tsv
    ' | while IFS=$'\t' read -r slug role; do
        printf "  %-30s %s\n" "$slug" "$role"
    done

    # Parity guard with bb_ops.workspaces_list, which paginates: bash
    # fetches a single 100-item page (matching cmd_repos convention).
    # >100 workspace memberships is vanishingly rare, but if the API
    # signals more pages, say so rather than silently truncating —
    # direct the user to the paginating MCP tool.
    if [[ "$(echo "$response" | jq -r '.next // empty')" != "" ]]; then
        # All three lines to stderr so the separator stays attached to
        # the hint even when stdout is piped elsewhere.
        echo "" >&2
        echo "  (showing first 100 — you belong to more; use the MCP" >&2
        echo "   workspaces_list tool, which paginates, for the full set)" >&2
    fi
}

cmd_repos() {
    resolve_workspace
    echo "Repositories in ${BB_WORKSPACE}:"
    echo ""

    local response
    response=$(bb_get "/repositories/${BB_WORKSPACE}?pagelen=100&sort=-updated_on")

    printf "  %-35s %-12s %s\n" "REPO" "UPDATED" "LANGUAGE"
    printf "  %-35s %-12s %s\n" "----" "-------" "--------"

    echo "$response" | jq -r '
        .values[] |
        [
            .slug,
            (.updated_on | split("T") | .[0]),
            (.language // "-")
        ] | @tsv
    ' | while IFS=$'\t' read -r slug updated lang; do
        printf "  %-35s %-12s %s\n" "$slug" "$updated" "$lang"
    done
}

cmd_repo() {
    local repo
    resolve_repo "${1:-}"

    local response
    response=$(bb_get "$(repo_path "$repo")")

    echo "$response" | jq -r '
        .full_name + " - " + (.description // "(no description)"),
        "",
        "  Language:    " + (.language // "n/a"),
        "  Created:     " + .created_on,
        "  Updated:     " + .updated_on,
        "  Size:        " + ((.size // 0) / 1024 / 1024 | floor | tostring) + " MB",
        "  Main branch: " + (.mainbranch.name // "n/a"),
        "  Private:     " + (.is_private | tostring),
        "  Clone SSH:   " + ([.links.clone[] | select(.name == "ssh") | .href] | first // "n/a"),
        "  URL:         " + .links.html.href
    '
}

# =========================================================================
#  DOWNLOADS (deployment artifacts)
# =========================================================================

cmd_downloads() {
    local repo
    resolve_repo "${1:-}"

    echo "Downloads for ${BB_WORKSPACE}/${repo}:"
    echo ""

    local response
    response=$(bb_get "$(repo_path "$repo")/downloads?pagelen=25")

    local count
    count=$(echo "$response" | jq '.size // 0')

    if [[ "$count" == "0" ]]; then
        echo "  No downloads."
        return
    fi

    printf "  %-40s %-10s %s\n" "FILE" "SIZE" "DATE"
    printf "  %-40s %-10s %s\n" "----" "----" "----"

    echo "$response" | jq -r '
        .values[] |
        [
            .name,
            ((.size // 0) / 1024 | floor | tostring + " KB"),
            (.created_on | split("T") | .[0])
        ] | @tsv
    ' | while IFS=$'\t' read -r name size date; do
        printf "  %-40s %-10s %s\n" "$name" "$size" "$date"
    done
}

# =========================================================================
#  ENVIRONMENT / DEPLOY VARIABLES
# =========================================================================

cmd_vars() {
    local repo
    resolve_repo "${1:-}"

    echo "Repository variables for ${BB_WORKSPACE}/${repo}:"
    echo ""

    local response
    response=$(bb_get "$(repo_path "$repo")/pipelines_config/variables/?pagelen=100")

    printf "  %-30s %-8s %s\n" "KEY" "SECURED" "VALUE"
    printf "  %-30s %-8s %s\n" "---" "-------" "-----"

    echo "$response" | jq -r '
        .values[] |
        [
            .key,
            (.secured | tostring),
            (if .secured then "********" else .value end)
        ] | @tsv
    ' | while IFS=$'\t' read -r key secured value; do
        printf "  %-30s %-8s %s\n" "$key" "$secured" "$value"
    done
}

# =========================================================================
#  OPEN IN BROWSER
# =========================================================================

cmd_whoami() {
    # Report the resolved config + git context. Useful as a connectivity
    # smoke test before invasive operations. NEVER echoes BB_TOKEN and
    # NEVER echoes credentials embedded in the origin URL (a common
    # pattern for token-based git auth — `whoami` output gets pasted
    # into bug reports / screenshots, can't have secrets in it).
    echo "bb configuration:"
    echo "  User:      ${BB_USER}"
    if [[ -n "${BB_WORKSPACE:-}" ]]; then
        echo "  Workspace: ${BB_WORKSPACE} (default)"
    else
        echo "  Workspace: (not set — auto-detected per-repo from git origin)"
    fi
    echo "  API:       ${BB_API}"
    echo "  Token:     [set, redacted]"

    echo ""
    echo "Git context:"
    local cwd_branch cwd_remote
    cwd_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "(not a git repo)")
    # Strip `user:token@` from origin URL before echoing. Matches the
    # `_redact_url` helper in mcp_server.py / git_ops.py: anything of
    # the form `://user:token@host/path` becomes `://[redacted]@host/path`.
    #
    # Use an `if` block (not `git ... | sed ... || echo`) because in a
    # pipeline the `||` attaches to sed, which always exits 0 on
    # empty input — so the fallback would never fire when git itself
    # failed (no origin remote / not in a git repo). The if-form
    # branches on git's exit status, not sed's.
    local _git_remote_raw
    if _git_remote_raw=$(git remote get-url origin 2>/dev/null); then
        cwd_remote=$(printf '%s' "$_git_remote_raw" | sed -E 's#://[^/@]+@#://[redacted]@#')
    else
        cwd_remote="(no origin remote)"
    fi
    echo "  Cwd:       $(pwd)"
    echo "  Branch:    ${cwd_branch}"
    echo "  Origin:    ${cwd_remote}"

    # Light reachability check. Probe the configured workspace
    # endpoint (not /user — workspace-scoped tokens, which Atlassian
    # now recommends, reject /user with 401/403 while serving
    # /repositories/{workspace} correctly). False-negative on /user
    # would tell a user with a valid token to rotate it.
    #
    # Converse caveat: /repositories/{workspace} requires
    # `repository:read` scope. A workspace-scoped token granting only
    # `pipelines:read` or `pullrequest:read` will fail this probe even
    # though `bb pipelines` / `bb prs` still work. Treat this as a
    # scope hint, not a global credential verdict.
    echo ""
    echo "Auth check:"
    # BB_WORKSPACE is optional now, so pick a workspace to probe: the
    # configured/flag default if set, else the git origin's workspace.
    # If neither resolves, skip the probe rather than build a bad URL.
    local probe_ws="${BB_WORKSPACE:-}"
    if [[ -z "$probe_ws" && -n "${_git_remote_raw:-}" ]]; then
        local _pr="${_git_remote_raw%/}"
        if [[ "$_pr" =~ [:/]([^/:]+)/([^/]+)$ ]]; then
            probe_ws="${BASH_REMATCH[1]}"
        fi
    fi
    if [[ -z "$probe_ws" ]]; then
        echo "  Skipped — no workspace to probe (set BB_WORKSPACE or run"
        echo "  inside a Bitbucket git checkout). Config + token look set."
    elif bb_get "/repositories/${probe_ws}?pagelen=1" > /dev/null 2>&1; then
        echo "  Workspace '${probe_ws}' reachable — auth OK."
    else
        echo "  Workspace '${probe_ws}' NOT reachable — token may be invalid,"
        echo "  expired, scoped to a different workspace, or missing"
        echo "  repository:read (pipeline/PR-only scoped tokens still work"
        echo "  for those commands)."
        echo "  Rotate at https://id.atlassian.com/manage-profile/security/api-tokens"
    fi
}

cmd_open() {
    local repo
    resolve_repo "${1:-}"
    local section="${2:-}"

    local url="https://bitbucket.org/${BB_WORKSPACE}/${repo}"

    case "$section" in
        pr|prs)       url="${url}/pull-requests" ;;
        pipelines|pl) url="${url}/addon/pipelines/home" ;;
        branches|br)  url="${url}/branches" ;;
        settings)     url="${url}/admin" ;;
        commits)      url="${url}/commits" ;;
        *)            ;; # default: repo home
    esac

    echo "Opening: ${url}"
    open "$url" 2>/dev/null || xdg-open "$url" 2>/dev/null || echo "  $url"
}

# =========================================================================
#  HELP
# =========================================================================

cmd_help() {
    cat <<'HELP'
bb - Bitbucket CLI

PIPELINES
  bb pipelines [repo] [count]           List recent pipelines (default: 10)
  bb pipeline [repo] <number>           Show pipeline details and steps
  bb watch [repo] [number] [interval]   Poll pipeline until done (default: 15s)
  bb logs [repo] <number> [step]        Show step logs
  bb trigger [repo] [branch] [pattern]  Trigger a pipeline run
  bb stop [repo] <number>               Stop a running pipeline
  bb approve [repo] <number>            Open pipeline in browser (manual steps require UI)

PULL REQUESTS
  bb prs [repo] [state]                 List PRs (default: OPEN)
  bb pr [repo] <id>                     View PR details
  bb pr-create [repo] <title> [dest]    Create PR from current branch
  bb pr-approve [repo] <id>             Approve a PR
  bb pr-unapprove [repo] <id>           Remove your approval on a PR
  bb pr-merge [repo] <id> [strategy]    Merge a PR (merge_commit|squash|fast_forward)
  bb pr-decline [repo] <id>             Decline a PR
  bb pr-diff [repo] <id>                Show PR diff
  bb pr-comments [repo] <id>            Show PR comments
  bb pr-comment [repo] <id> <body>      Add a comment to a PR

BRANCHES
  bb branches [repo]                    List branches
  bb branch [repo] <name>               Show a single branch
  bb commits [repo] [branch] [count]    List recent commits (default count: 10)

REPOSITORY
  bb workspaces                         List workspaces you belong to (needs read:workspace:bitbucket scope)
  bb repos                              List workspace repos
  bb repo [repo]                        Show repo details
  bb downloads [repo]                   List repo downloads
  bb vars [repo]                        List pipeline variables

UTILITIES
  bb whoami                             Show resolved config + git context
  bb open [repo] [section]              Open in browser (pr|pipelines|branches|settings|commits)
  bb help                               Show this help

GLOBAL FLAGS
  -w, --workspace <name>                Override BB_WORKSPACE for this invocation

  Example: bb -w acme repos

NOTES
  [repo] is auto-detected from the current git remote if omitted.
  Config: ~/.config/bb/config or env vars BB_USER, BB_TOKEN, BB_WORKSPACE.

  Auth uses Atlassian API tokens with HTTP Basic auth.
  BB_USER is your Bitbucket account email address.
  Create a token at: https://id.atlassian.com/manage-profile/security/api-tokens

  For agent-driven workflows, register the MCP server (mcp_server.py)
  with Claude Code. See README.md for the install path.
HELP
}

# --- Main ---

# Parse global flags before the command
while [[ "${1:-}" == -* ]]; do
    case "$1" in
        -w|--workspace)
            BB_WORKSPACE_OVERRIDE="$2"
            shift 2
            ;;
        --workspace=*)
            BB_WORKSPACE_OVERRIDE="${1#*=}"
            shift
            ;;
        --help|-h)
            cmd_help
            exit 0
            ;;
        *)
            echo "Unknown flag: $1" >&2
            echo "Run 'bb help' for usage." >&2
            exit 1
            ;;
    esac
done

command="${1:-help}"
shift || true

# Allow help without credentials
if [[ "$command" == "help" || "$command" == "--help" || "$command" == "-h" ]]; then
    cmd_help
    exit 0
fi

load_config

# Apply workspace override after config load
if [[ -n "${BB_WORKSPACE_OVERRIDE:-}" ]]; then
    BB_WORKSPACE="$BB_WORKSPACE_OVERRIDE"
fi

case "$command" in
    # Pipelines
    pipelines|pls)        cmd_pipelines "$@" ;;
    pipeline|pl)          cmd_pipeline "$@" ;;
    watch|w)              cmd_watch "$@" ;;
    logs|l)               cmd_logs "$@" ;;
    trigger|run)          cmd_pipeline_trigger "$@" ;;
    stop)                 cmd_pipeline_stop "$@" ;;
    approve|ap)           cmd_pipeline_approve "$@" ;;
    # Pull Requests
    prs|pr-list)          cmd_pr_list "$@" ;;
    pr|pr-view)           cmd_pr_view "$@" ;;
    pr-create|prc)        cmd_pr_create "$@" ;;
    pr-approve|pra)       cmd_pr_approve "$@" ;;
    pr-unapprove|prua)    cmd_pr_unapprove "$@" ;;
    pr-merge|prm)         cmd_pr_merge "$@" ;;
    pr-decline|prd)       cmd_pr_decline "$@" ;;
    pr-diff)              cmd_pr_diff "$@" ;;
    pr-comments|pr-comm)  cmd_pr_comments "$@" ;;
    pr-comment)           cmd_pr_comment_add "$@" ;;
    # Branches
    branches|br)          cmd_branches "$@" ;;
    branch)               cmd_branch_show "$@" ;;
    commits)              cmd_commits "$@" ;;
    # Repos
    workspaces|ws)        cmd_workspaces "$@" ;;
    repos)                cmd_repos "$@" ;;
    repo)                 cmd_repo "$@" ;;
    downloads|dl)         cmd_downloads "$@" ;;
    vars)                 cmd_vars "$@" ;;
    # Utilities
    whoami)               cmd_whoami ;;
    open|o)               cmd_open "$@" ;;
    help|--help|-h)       cmd_help ;;
    *)
        echo "Unknown command: $command" >&2
        echo "Run 'bb help' for usage." >&2
        exit 1
        ;;
esac