@moondeck/station 0.0.0-stage → 1.0.0

package/scripts/agent/_common.sh

@@ -0,0 +1,633 @@
+#!/usr/bin/env bash
+# uai agent — shared helpers.
+#
+# Every agent script source's this file at the top. It establishes the
+# strict-mode posture, structured JSON output contract, sqlite access
+# helpers, and a uniform error trap.
+#
+# Output contract (docs/agent.md):
+#
+#   success  → stdout:  {"ok":true,"data":{...}}
+#   failure  → stderr:  {"ok":false,"error":{"code":"...","message":"...","step":"..."}}
+#               exit non-zero.
+#
+# Environment:
+#   UAI_DB_PATH        absolute path to uai.sqlite          (required)
+#   UAI_OWNER_HOME     host $HOME (for ~/.claude, ~/.codex) (default: $HOME)
+#   UAI_TTYD_BIND      ttyd listen address                  (default: 127.0.0.1)
+#   UAI_LOG_DIR        directory for ttyd / docker logs     (default: $UAI_DATA_DIR/logs)
+#   UAI_DATA_DIR       base data dir                        (default: dirname of UAI_DB_PATH)
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Strict env.
+# ---------------------------------------------------------------------------
+
+: "${UAI_DB_PATH:?UAI_DB_PATH must be set (path to uai.sqlite)}"
+
+UAI_DATA_DIR="${UAI_DATA_DIR:-$(dirname "$UAI_DB_PATH")}"
+UAI_OWNER_HOME="${UAI_OWNER_HOME:-$HOME}"
+# The station's storage tree (lib/env.ts: ~/.moondeck unless configured).
+# task-up / task-down derive the per-project mirrors, per-task dirs,
+# browsers and shared files from here. The station passes it explicitly
+# (lib/agent.ts); there is no default, because a wrong one builds a task
+# somewhere the station then refuses (rehearsal #2, 2026-11-02).
+: "${UAI_WORKSPACE_ROOT:?UAI_WORKSPACE_ROOT must be set (the station passes its workspace root)}"
+UAI_TTYD_BIND="${UAI_TTYD_BIND:-127.0.0.1}"
+UAI_LOG_DIR="${UAI_LOG_DIR:-$UAI_DATA_DIR/logs}"
+mkdir -p "$UAI_LOG_DIR"
+
+# Optional dependencies — fail fast with a structured error if missing.
+# docker is only a dependency of the docker runtime mode: the Apple runtime
+# path must work on a Docker-free Mac (ADR-106), and its own CLI is validated
+# by validate_task_runtime_selection instead.
+agent_required_bins="sqlite3 jq git"
+if [ "${UAI_TASK_RUNTIME:-docker}" != "apple-container" ]; then
+  agent_required_bins="$agent_required_bins docker"
+fi
+# Collect EVERY missing tool before failing: reporting them one at a time
+# cost one full fix-and-Resume round trip per binary on a fresh Amazon
+# Linux box (sqlite3, then jq — live 2026-08-21). Bash 3.2: plain string
+# accumulation, no arrays.
+missing_bins=""
+for bin in $agent_required_bins; do
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    missing_bins="$missing_bins $bin"
+  fi
+done
+if [ -n "$missing_bins" ]; then
+  missing_bins="${missing_bins# }"
+  printf '{"ok":false,"error":{"code":"MISSING_DEPENDENCY","message":"missing on PATH: %s — install with your package manager (dnf/apt/brew), then Resume"}}\n' "$missing_bins" >&2
+  exit 127
+fi
+
+
+# The docker BINARY existing does not make `docker compose` work: the v2
+# compose plugin ships separately, and a bare-engine install (Amazon Linux
+# 2023's docker package) answers `docker compose` with the top-level help
+# text — the operator saw exactly that as their task error (live
+# 2026-08-21). Called LAZILY by the task scripts right before their first
+# compose use, never at source time: argument validation must precede any
+# docker invocation (the task-down/task-up tests enforce that ordering).
+uai_require_compose_plugin() {
+  [ "${UAI_TASK_RUNTIME:-docker}" = "apple-container" ] && return 0
+  if ! docker compose version >/dev/null 2>&1; then
+    printf '{"ok":false,"error":{"code":"MISSING_DEPENDENCY","message":"missing on PATH: docker-compose-plugin — install the Docker Compose v2 plugin, then Resume"}}\n' >&2
+    exit 127
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# Logger. All log lines go to stderr so stdout stays reserved for JSON.
+# ---------------------------------------------------------------------------
+
+_uai_ts() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+
+log() { printf '[uai-agent %s] %s\n' "$(_uai_ts)" "$*" >&2; }
+
+# ---------------------------------------------------------------------------
+# JSON output helpers.
+# ---------------------------------------------------------------------------
+
+# emit_ok '{"foo":"bar"}'
+#
+# NOTE: do not use `${1:-{}}` here — bash parses `{` inside the default
+# as a literal and the matching `}` closes the substitution prematurely,
+# so a real payload gets a trailing `}` appended. Use an explicit check.
+emit_ok() {
+  local data="$1"
+  if [ -z "$data" ]; then data='{}'; fi
+  printf '{"ok":true,"data":%s}\n' "$data"
+}
+
+# emit_err <code> <message> [step]
+#
+# Persists status='error' on the current task (if UAI_TASK_ID is set),
+# logs an `error` event, prints structured JSON to stderr, and exits 1.
+emit_err() {
+  local code="$1" msg="$2" step="${3:-${UAI_CURRENT_STEP:-}}"
+  _uai_record_failure "$code" "$step"
+  local json
+  if [ -n "$step" ]; then
+    json=$(jq -nc --arg c "$code" --arg m "$msg" --arg s "$step" \
+      '{ok:false,error:{code:$c,message:$m,step:$s}}')
+  else
+    json=$(jq -nc --arg c "$code" --arg m "$msg" \
+      '{ok:false,error:{code:$c,message:$m}}')
+  fi
+  printf '%s\n' "$json" >&2
+  exit 1
+}
+
+# Docker can disappear after the TypeScript admission check but before a
+# minutes-long compose/init command finishes. These codes describe steps whose
+# failure may be a daemon outage. Keep the command snapshot retryable here; the
+# host process re-probes `docker info` and records a terminal error only when
+# the daemon is positively reachable and the operation itself really failed.
+_uai_is_runtime_sensitive_error() {
+  case "$1" in
+    STANDARD_IMAGE_MISSING|COMPOSE_UP_FAILED|COMPOSE_DOWN_FAILED|CONTAINER_INIT_FAILED|DOCKER_PS_FAILED)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+_uai_mark_retryable() {
+  if [ -n "${UAI_TASK_ID:-}" ] && [ -n "${UAI_DB_PATH:-}" ]; then
+    local restore=""
+    if [ -n "${UAI_RETRY_STATUS:-}" ]; then
+      restore=", status='$(sql_escape "$UAI_RETRY_STATUS")'"
+    fi
+    sqlite_exec "UPDATE uai_tasks SET locked_at=NULL${restore}, updated_at=(unixepoch()*1000) WHERE id='$(sql_escape "$UAI_TASK_ID")'" 2>/dev/null || true
+  fi
+  UAI_LOCK_HELD=""
+}
+
+_uai_record_failure() {
+  local code="$1" step="$2"
+  if _uai_is_runtime_sensitive_error "$code"; then
+    _uai_mark_retryable
+  else
+    _uai_mark_error "$code" "$step"
+  fi
+}
+
+# _uai_mark_error <code> <step>  — best-effort persist of status=error.
+# Shared between emit_err (explicit) and the ERR trap (set -e).
+_uai_mark_error() {
+  local code="$1" step="$2"
+  if [ -n "${UAI_TASK_ID:-}" ] && [ -n "${UAI_DB_PATH:-}" ]; then
+    sqlite_exec "UPDATE uai_tasks SET status='error', locked_at=NULL, updated_at=(unixepoch()*1000) WHERE id='$(sql_escape "$UAI_TASK_ID")'" 2>/dev/null || true
+    local payload
+    payload=$(jq -nc --arg c "$code" --arg s "$step" '{code:$c,step:$s}')
+    sqlite_exec "INSERT INTO uai_task_events (id, task_id, kind, payload) VALUES ('$(sql_escape "$(_uai_event_id)")', '$(sql_escape "$UAI_TASK_ID")', 'error', '$(sql_escape "$payload")')" 2>/dev/null || true
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# SQLite helpers. The DB is local SQLite; concurrency is single-writer per
+# task (enforced via lock_task below + Next.js).
+# ---------------------------------------------------------------------------
+
+# sqlite_exec "<sql>"
+sqlite_exec() {
+  sqlite3 "$UAI_DB_PATH" "$1"
+}
+
+# sqlite_json "<sql>"  →  JSON array
+sqlite_json() {
+  sqlite3 -json "$UAI_DB_PATH" "$1"
+}
+
+# sql_escape <value>  →  single-quote-safe string for inline SQL.
+#
+# We pipe through sed instead of using bash parameter expansion because
+# bash 3.2 (macOS default) keeps backslashes in `${var//\'/\'\'}` —
+# producing `you\'\'re` from `you're` and breaking SQL string parsing.
+# sed handles it identically on bash 3.2 and 5+.
+sql_escape() {
+  printf '%s' "$1" | sed "s/'/''/g"
+}
+
+# db_get_task <id>  →  JSON array (one row) or "[]"
+db_get_task() {
+  local out
+  out=$(sqlite_json "SELECT * FROM uai_tasks WHERE id='$(sql_escape "$1")'")
+  printf '%s' "${out:-[]}"
+}
+
+# db_get_projects_for_task <taskId>  →  JSON array of the task's selected
+# projects, in position order. Each element carries every uai_projects
+# column plus the `position` from uai_task_projects. Empty array when the
+# task has no selected projects (scratchpad).
+db_get_projects_for_task() {
+  local out
+  out=$(sqlite_json "SELECT p.*, tp.position AS position FROM uai_projects p JOIN uai_task_projects tp ON tp.project_id = p.id WHERE tp.task_id = '$(sql_escape "$1")' ORDER BY tp.position ASC")
+  printf '%s' "${out:-[]}"
+}
+
+# db_update_task <id> "col=value" "col=value" ...
+#
+# Values must be pre-quoted by the caller (e.g. status='running', port=42).
+db_update_task() {
+  local id="$1"; shift
+  local set_clause
+  set_clause=$(IFS=','; echo "$*")
+  sqlite_exec "UPDATE uai_tasks SET ${set_clause}, updated_at=(unixepoch()*1000) WHERE id='$(sql_escape "$id")'"
+}
+
+# emit_event <task_id> <kind> <payload-json>
+emit_event() {
+  local tid="$1" kind="$2" payload="$3"
+  if [ -z "$payload" ]; then payload='{}'; fi
+  local eid
+  eid=$(_uai_event_id)
+  sqlite_exec "INSERT INTO uai_task_events (id, task_id, kind, payload) VALUES ('$(sql_escape "$eid")', '$(sql_escape "$tid")', '$(sql_escape "$kind")', '$(sql_escape "$payload")')"
+}
+
+# _uai_event_id — ULID-shaped fallback id generator (Crockford base32 prefix).
+# Real ULIDs come from the Next.js layer; agent-side events use ev_<unix><rand>.
+_uai_event_id() {
+  printf 'ev_%s%s' "$(date +%s%N | cut -c1-13)" "$(_uai_rand 10)"
+}
+
+_uai_rand() {
+  # Lowercase alphanumeric, length $1. Avoids depending on `uuidgen` etc.
+  local n="$1"
+  LC_ALL=C tr -dc 'a-z0-9' </dev/urandom | head -c "$n"
+}
+
+# ---------------------------------------------------------------------------
+# Locking. The Task row carries `locked_at`. Next.js also checks this
+# before invoking the agent; the shell-side lock is a safety net for
+# concurrent invocations of the same script.
+# ---------------------------------------------------------------------------
+
+lock_task() {
+  local id="$1"
+  # Atomic CAS via UPDATE WHERE locked_at IS NULL; success = changes()==1.
+  local changes
+  changes=$(sqlite_exec "UPDATE uai_tasks SET locked_at=(unixepoch()*1000), updated_at=(unixepoch()*1000) WHERE id='$(sql_escape "$id")' AND locked_at IS NULL; SELECT changes();")
+  [ "$changes" = "1" ] || emit_err "TASK_LOCKED" "task $id is already locked" "lock"
+  UAI_LOCK_HELD="$id"
+}
+
+unlock_task() {
+  local id="$1"
+  sqlite_exec "UPDATE uai_tasks SET locked_at=NULL, updated_at=(unixepoch()*1000) WHERE id='$(sql_escape "$id")'"
+  UAI_LOCK_HELD=""
+}
+
+# ---------------------------------------------------------------------------
+# Step tracking + ERR trap.
+#
+# `step <code> <label>` declares the next risky operation. If the script
+# exits non-zero, the trap emits a structured error tagged with the
+# current step's code + label, marks the task `status=error`, and
+# releases the lock.
+# ---------------------------------------------------------------------------
+
+UAI_CURRENT_STEP=""
+UAI_ERROR_CODE="UNKNOWN"
+UAI_TASK_ID=""
+UAI_LOCK_HELD=""
+UAI_RETRY_STATUS=""
+UAI_PROJECT_LOCK_PATH=""
+UAI_PROJECT_LOCK_TOKEN=""
+
+# Shared project mirrors are mutated by task-up and task-down across different
+# task processes. A task-row lock cannot serialize those operations, so use a
+# portable atomic directory lock (macOS does not ship `flock`). Never reclaim
+# a stale lock automatically: checking a PID and unlinking a fixed path creates
+# a TOCTOU window where a new owner's lock can be deleted. A stale directory is
+# deliberately surfaced for an operator to inspect and remove.
+acquire_project_lock() {
+  local projects_root="$1" project_id="$2"
+  local project_parent="$projects_root/$project_id"
+  local lock_path="$project_parent/.uai-repo.lock"
+  local owner_pid attempts=0
+  mkdir -p "$project_parent"
+  while ! mkdir "$lock_path" 2>/dev/null; do
+    if [ ! -d "$lock_path" ]; then
+      emit_err "FETCH_FAILED" \
+        "project $project_id has an obsolete or invalid repository lock at $lock_path. Confirm no task-up/task-down process is active, remove that lock manually, then retry." \
+        "acquire project cache lock"
+    fi
+    owner_pid=$(cat "$lock_path/pid" 2>/dev/null || true)
+    case "$owner_pid" in
+      ''|*[!0-9]*) ;;
+      *)
+        if ! kill -0 "$owner_pid" 2>/dev/null; then
+          emit_err "FETCH_FAILED" \
+            "project $project_id has a stale repository lock at $lock_path (owner pid $owner_pid). Confirm no task-up/task-down process is active, remove that lock directory manually, then retry." \
+            "acquire project cache lock"
+        fi
+        ;;
+    esac
+    attempts=$((attempts + 1))
+    if [ "$attempts" -ge 300 ]; then
+      emit_err "FETCH_FAILED" \
+        "project $project_id is busy in another host operation, or has an incomplete lock at $lock_path. Confirm no task-up/task-down process is active; if none is, remove that lock directory manually, then retry." \
+        "acquire project cache lock"
+    fi
+    sleep 0.1
+  done
+  UAI_PROJECT_LOCK_TOKEN="$$:${RANDOM:-0}"
+  printf '%s\n' "$$" > "$lock_path/pid"
+  printf '%s\n' "$UAI_PROJECT_LOCK_TOKEN" > "$lock_path/owner"
+  UAI_PROJECT_LOCK_PATH="$lock_path"
+}
+
+release_project_lock() {
+  [ -n "$UAI_PROJECT_LOCK_PATH" ] || return 0
+  local owner
+  owner=$(cat "$UAI_PROJECT_LOCK_PATH/owner" 2>/dev/null || true)
+  if [ -n "$UAI_PROJECT_LOCK_TOKEN" ] \
+     && [ "$owner" = "$UAI_PROJECT_LOCK_TOKEN" ]; then
+    rm -f "$UAI_PROJECT_LOCK_PATH/pid" "$UAI_PROJECT_LOCK_PATH/owner" \
+      2>/dev/null || true
+    rmdir "$UAI_PROJECT_LOCK_PATH" 2>/dev/null || true
+  fi
+  UAI_PROJECT_LOCK_PATH=""
+  UAI_PROJECT_LOCK_TOKEN=""
+}
+
+_uai_on_exit() {
+  release_project_lock || true
+}
+
+step() {
+  UAI_ERROR_CODE="$1"
+  UAI_CURRENT_STEP="$2"
+  log "step: $UAI_CURRENT_STEP"
+}
+
+_uai_on_err() {
+  local rc=$?
+  # Disable further ERR trap recursion.
+  trap - ERR
+
+  local code="$UAI_ERROR_CODE"
+  local stepname="$UAI_CURRENT_STEP"
+
+  _uai_record_failure "$code" "$stepname"
+
+  local out
+  out=$(jq -nc --arg c "$code" --arg m "agent step failed" --arg s "$stepname" --argjson rc "$rc" \
+    '{ok:false,error:{code:$c,message:$m,step:$s,exit_code:$rc}}')
+  printf '%s\n' "$out" >&2
+  exit "$rc"
+}
+
+setup_err_trap() {
+  trap _uai_on_err ERR
+  trap _uai_on_exit EXIT
+}
+
+# ---------------------------------------------------------------------------
+# Compose project name + container name conventions.
+# ---------------------------------------------------------------------------
+
+# Belt-and-braces: docker compose only accepts lowercase project names.
+# We also lowercase ulids at generation (lib/ulid.ts) but defensive
+# lowercasing here protects against any caller passing mixed case.
+_uai_lower() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
+compose_project_for_task()    { printf 'task-%s' "$(_uai_lower "$1")"; }
+# Compose v2 names containers as `<project>-<service>-<replica>`. We
+# never scale beyond one replica, so the suffix is always `-1`. If we
+# ever do scale, swap to discovering the container name via the
+# `com.docker.compose.project` + `com.docker.compose.service` labels.
+app_container_for_task()      { printf 'task-%s-app-1' "$(_uai_lower "$1")"; }
+# ADR-106: the Apple runtime has no Compose, so its app container drops the
+# replica suffix. Must match appleTaskContainerName in
+# lib/task-environment/apple-container.ts.
+apple_app_container_for_task() { printf 'moondeck-task-%s-app' "$(_uai_lower "$1")"; }
+# ADR-118: per-task block volume carrying the pnpm store. Must match
+# appleTaskStoreVolumeName in lib/task-environment/apple-container.ts.
+apple_store_volume_for_task() { printf 'moondeck-store-%s' "$(_uai_lower "$1")"; }
+
+# -----------------------------------------------------------------------------
+# ADR-106 container runtime selection. The host publishes the selected backend
+# in UAI_TASK_RUNTIME (+ UAI_CONTAINER_CLI for the bundled Apple toolchain);
+# `docker` keeps every historical path byte-for-byte.
+# -----------------------------------------------------------------------------
+TASK_RUNTIME_MODE="${UAI_TASK_RUNTIME:-docker}"
+CONTAINER_CLI="${UAI_CONTAINER_CLI:-}"
+
+validate_task_runtime_selection() {
+  case "$TASK_RUNTIME_MODE" in
+    docker|apple-container) ;;
+    *)
+      emit_err "BAD_ARGS" \
+        "unsupported UAI_TASK_RUNTIME '$TASK_RUNTIME_MODE'" \
+        "select container runtime"
+      ;;
+  esac
+  if [ "$TASK_RUNTIME_MODE" = "apple-container" ]; then
+    case "$CONTAINER_CLI" in
+      /*) ;;
+      *)
+        emit_err "BAD_ARGS" \
+          "UAI_CONTAINER_CLI must be an absolute path to the bundled container CLI" \
+          "select container runtime"
+        ;;
+    esac
+    if [ -L "$CONTAINER_CLI" ] || [ ! -f "$CONTAINER_CLI" ] \
+       || [ ! -x "$CONTAINER_CLI" ]; then
+      emit_err "BAD_ARGS" \
+        "the bundled container CLI at $CONTAINER_CLI is missing or not executable" \
+        "select container runtime"
+    fi
+  fi
+}
+
+# Single dispatcher for the verbs whose flags are identical across Docker and
+# the Apple CLI (exec/cp/stop/inspect/image inspect/volume create). Verbs that
+# differ (compose, run, build, port) branch explicitly at their call sites.
+crt() {
+  if [ "$TASK_RUNTIME_MODE" = "apple-container" ]; then
+    "$CONTAINER_CLI" "$@"
+  else
+    docker "$@"
+  fi
+}
+
+# Absence proof for the Apple runtime. The CLI exits nonzero for BOTH a
+# missing container and a broken apiserver; only the not-found error that
+# names this exact container proves absence. Everything else proves nothing
+# and must never authorize destructive work.
+apple_container_proven_absent() {
+  apple_absent_name="$1"
+  # One CLI response supplies the whole proof: nonzero exit, empty stdout,
+  # and the complete not-found error line naming this exact container (never
+  # a substring — a not-found answer for "$name-shadow" must not prove the
+  # absence of "$name"). Two separate invocations could each satisfy half
+  # while no single response satisfies both.
+  apple_absent_dir=$(mktemp -d "${TMPDIR:-/tmp}/uai-absent.XXXXXX") \
+    || return 1
+  apple_absent_rc=0
+  "$CONTAINER_CLI" inspect "$apple_absent_name" \
+    >"$apple_absent_dir/out" 2>"$apple_absent_dir/err" \
+    || apple_absent_rc=$?
+  apple_absent_proven=1
+  [ "$apple_absent_rc" -ne 0 ] || apple_absent_proven=0
+  [ ! -s "$apple_absent_dir/out" ] || apple_absent_proven=0
+  grep -Fqx "Error: container not found: $apple_absent_name" \
+    "$apple_absent_dir/err" 2>/dev/null || apple_absent_proven=0
+  rm -rf "$apple_absent_dir"
+  [ "$apple_absent_proven" -eq 1 ]
+}
+
+# ADR-118: same single-response absence discipline for a named volume. Only
+# the exact whole-line not-found grammar naming this volume proves absence;
+# any other failure (broken apiserver, timeout) proves nothing.
+apple_volume_proven_absent() {
+  apple_vabsent_name="$1"
+  apple_vabsent_dir=$(mktemp -d "${TMPDIR:-/tmp}/uai-vabsent.XXXXXX") \
+    || return 1
+  apple_vabsent_rc=0
+  "$CONTAINER_CLI" volume inspect "$apple_vabsent_name" \
+    >"$apple_vabsent_dir/out" 2>"$apple_vabsent_dir/err" \
+    || apple_vabsent_rc=$?
+  apple_vabsent_proven=1
+  [ "$apple_vabsent_rc" -ne 0 ] || apple_vabsent_proven=0
+  [ ! -s "$apple_vabsent_dir/out" ] || apple_vabsent_proven=0
+  grep -Fqx "Error: volume not found: $apple_vabsent_name" \
+    "$apple_vabsent_dir/err" 2>/dev/null || apple_vabsent_proven=0
+  rm -rf "$apple_vabsent_dir"
+  [ "$apple_vabsent_proven" -eq 1 ]
+}
+
+# Canonicalise every GitHub URL shape to credential-free HTTPS. task-up selects
+# the credential per task: the creator's connected GitHub token is primary;
+# SSH is a fallback only when that user has no GitHub connection on this host.
+# Keeping the stored/shared origin transport-neutral avoids binding a project
+# to whichever user's credential happened to touch its mirror first.
+#
+# Mirrors normalizeRepoUrl() in lib/github/repo-url.ts — keep the two in step.
+# Non-GitHub remotes are returned untouched: we only know how to speak for
+# GitHub, and Uai supports any git remote.
+#
+# Bash 3.2 (macOS /bin/bash): no ${var,,}, no associative arrays.
+normalize_github_repo_url() {
+  local input="$1" url after_scheme authority host_port host host_lc
+  local path owner rest repo repo_lc left
+  url=$(printf '%s' "$input" | sed \
+    -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+  if [ "${url#*://}" != "$url" ]; then
+    after_scheme=${url#*://}
+    authority=${after_scheme%%/*}
+    [ "$after_scheme" != "$authority" ] || {
+      printf '%s' "$url"
+      return
+    }
+    host_port=${authority##*@}
+    host=${host_port%%:*}
+    host_lc=$(printf '%s' "$host" | tr '[:upper:]' '[:lower:]')
+    case "$host_lc" in
+      github.com|www.github.com) path=${after_scheme#*/} ;;
+      *)
+        printf '%s' "$url"
+        return
+        ;;
+    esac
+  elif [ "${url#*:}" != "$url" ]; then
+    left=${url%%:*}
+    host=${left##*@}
+    host_lc=$(printf '%s' "$host" | tr '[:upper:]' '[:lower:]')
+    case "$host_lc" in
+      github.com|www.github.com) path=${url#*:} ;;
+      *)
+        printf '%s' "$url"
+        return
+        ;;
+    esac
+  else
+    case "$url" in
+      */*/*|/*)
+        printf '%s' "$url"
+        return
+        ;;
+      */*) path=$url ;;
+      *)
+        printf '%s' "$url"
+        return
+        ;;
+    esac
+  fi
+
+  # Keep only owner/repo. Browser URLs can include /tree/branch/path, and a
+  # pasted clone URL can carry both `.git` and a trailing slash.
+  path=${path%%\?*}
+  path=${path%%\#*}
+  path=$(printf '%s' "$path" | sed -e 's#/*$##')
+  owner=${path%%/*}
+  rest=${path#*/}
+  if [ -z "$owner" ] || [ "$rest" = "$path" ]; then
+    printf '%s' "$url"
+    return
+  fi
+  repo=${rest%%/*}
+  repo=${repo%%\?*}
+  repo=${repo%%\#*}
+  repo_lc=$(printf '%s' "$repo" | tr '[:upper:]' '[:lower:]')
+  case "$repo_lc" in
+    *.git) repo=${repo%????} ;;
+  esac
+  if [ -z "$repo" ]; then
+    printf '%s' "$url"
+    return
+  fi
+  printf 'https://github.com/%s/%s.git' "$owner" "$repo"
+}
+
+# True for a reference whose explicit authority is github.com, even if its
+# path is malformed. Callers use this to fail closed rather than handing a
+# GitHub-looking URL to a generic Git command with ambient credentials.
+is_github_hosted_url() {
+  local input="$1" url after_scheme authority host_port host host_lc left
+  url=$(printf '%s' "$input" | sed \
+    -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+  if [ "${url#*://}" != "$url" ]; then
+    after_scheme=${url#*://}
+    authority=${after_scheme%%/*}
+    host_port=${authority##*@}
+    host=${host_port%%:*}
+  elif [ "${url#*:}" != "$url" ]; then
+    left=${url%%:*}
+    host=${left##*@}
+  else
+    case "$url" in
+      */*/*|/*|*://*) return 1 ;;
+      */*) return 0 ;;
+      *) return 1 ;;
+    esac
+  fi
+  host_lc=$(printf '%s' "$host" | tr '[:upper:]' '[:lower:]')
+  case "$host_lc" in
+    github.com|www.github.com) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# HTTPS spelling of a github.com repository. Empty for non-GitHub remotes.
+github_https_repo_url() {
+  local https_url rest owner repo
+  https_url=$(normalize_github_repo_url "$1")
+  case "$https_url" in
+    https://github.com/*)
+      rest=${https_url#https://github.com/}
+      owner=${rest%%/*}
+      repo=${rest#*/}
+      if [ "$repo" = "$rest" ]; then
+        printf ''
+      else
+        case "$owner/$repo" in
+          /*|*/|*/*/*) printf '' ;;
+          *) printf '%s' "$https_url" ;;
+        esac
+      fi
+      ;;
+    *)
+      printf ''
+      ;;
+  esac
+}
+
+# SSH spelling used only when the task owner has not connected GitHub.
+github_ssh_repo_url() {
+  local https_url
+  https_url=$(github_https_repo_url "$1")
+  case "$https_url" in
+    https://github.com/*)
+      printf 'git@github.com:%s' "${https_url#https://github.com/}"
+      ;;
+    *)
+      printf ''
+      ;;
+  esac
+}