fix: [nomad-prep] P8 — spot-check lib/mirrors.sh against empty Forgejo target (#796)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

lib/mirrors.sh

@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
-# mirrors.sh — Push primary branch + tags to configured mirror remotes.
+# mirrors.sh — Mirror helpers: push to remotes + register pull mirrors via API.
 #
 # Usage: source lib/mirrors.sh; mirror_push
+#        source lib/mirrors.sh; mirror_pull_register <clone_url> <owner> <repo_name> [interval]
 # Requires: PROJECT_REPO_ROOT, PRIMARY_BRANCH, MIRROR_* vars from load-project.sh
+#           FORGE_API, FORGE_TOKEN for pull-mirror registration
 
 # shellcheck disable=SC2154  # globals set by load-project.sh / calling script
 
@@ -37,3 +39,71 @@ mirror_push() {
     log "mirror: pushed to ${name} (pid $!)"
   done
 }
+
+# ---------------------------------------------------------------------------
+# mirror_pull_register — register a Forgejo pull mirror via the /repos/migrate API.
+#
+# Creates a new repo as a pull mirror of an external source.  Works against
+# empty target repos (the repo is created by the API call itself).
+#
+# Usage:
+#   mirror_pull_register <clone_url> <owner> <repo_name> [interval]
+#
+# Args:
+#   clone_url  — HTTPS URL of the source repo (e.g. https://codeberg.org/johba/disinto.git)
+#   owner      — Forgejo org or user that will own the mirror repo
+#   repo_name  — name of the new mirror repo on Forgejo
+#   interval   — sync interval (default: "8h0m0s"; Forgejo duration format)
+#
+# Requires:
+#   FORGE_API, FORGE_TOKEN (from env.sh)
+#
+# Returns 0 on success, 1 on failure.  Prints the new repo JSON to stdout.
+# ---------------------------------------------------------------------------
+mirror_pull_register() {
+  local clone_url="$1"
+  local owner="$2"
+  local repo_name="$3"
+  local interval="${4:-8h0m0s}"
+
+  if [ -z "${FORGE_API:-}" ] || [ -z "${FORGE_TOKEN:-}" ]; then
+    echo "ERROR: FORGE_API and FORGE_TOKEN must be set" >&2
+    return 1
+  fi
+
+  if [ -z "$clone_url" ] || [ -z "$owner" ] || [ -z "$repo_name" ]; then
+    echo "Usage: mirror_pull_register <clone_url> <owner> <repo_name> [interval]" >&2
+    return 1
+  fi
+
+  local payload
+  payload=$(cat <<ENDJSON
+{
+  "clone_addr": "${clone_url}",
+  "repo_name": "${repo_name}",
+  "repo_owner": "${owner}",
+  "mirror": true,
+  "mirror_interval": "${interval}",
+  "service": "git"
+}
+ENDJSON
+  )
+
+  local http_code body
+  body=$(curl -s -w "\n%{http_code}" -X POST \
+    -H "Authorization: token ${FORGE_TOKEN}" \
+    -H "Content-Type: application/json" \
+    "${FORGE_API}/repos/migrate" \
+    -d "$payload")
+
+  http_code=$(printf '%s' "$body" | tail -n1)
+  body=$(printf '%s' "$body" | sed '$d')
+
+  if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+    printf '%s\n' "$body"
+    return 0
+  else
+    echo "ERROR: mirror_pull_register failed (HTTP ${http_code}): ${body}" >&2
+    return 1
+  fi
+}