refactor(lib): fold ownership_guard primitives into common.sh + wire env passthrough from Elixir TUI

Two polish items addressing the gaps surfaced 2026-04-26:

(A) Fold ownership_guard into common.sh
- Move owner_allowed / repo_owner_from_remote / repo_allowed /
  assert_owner_allowed into common.sh under `gs::`-prefixed names.
- Adds GS_OWNERS_CONFIG env-var override (alongside the existing
  GIT_SCRIPTS_ALLOWED_OWNERS) for ergonomics.
- Use the lib's colour palette + die helper for the rejection banner
  rather than open-coding it.
- Convert the legacy scripts/lib/ownership_guard.sh into a thin
  backwards-compat shim that sources common.sh and re-exports the
  unprefixed names so any existing `source ownership_guard.sh` callers
  continue to work unchanged.
- The Elixir mirror at lib/script_manager/ownership_guard.ex stays as-is
  (it's a parallel implementation called from pr_processor.ex; not part
  of the shell library merge).

(B) Wire env passthrough from Elixir TUI
- `ScriptManager.ScriptRunner.run_script/3` now accepts an `env` map and
  passes it through to `System.cmd`. Existing 2-arity callers continue
  to work (delegate to /3 with empty map).
- Module docstring documents the common.sh env-var contract
  (GS_DRY_RUN, GS_YES, GS_LOG_LEVEL, GS_PARALLEL, GS_REPO_LIST,
  NO_COLOR) so TUI menu code can wire them through cleanly.
- When env is non-empty the runner echoes a one-line "ℹ️ env: …"
  summary so the user can see what they triggered.

This unblocks the TUI menus exposing dry-run / verbose / quiet toggles
on every script invocation. Per-menu wiring is a separate cosmetic
change; the runner-side plumbing it needs is now in place.

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

Author: hyperpolymath

lib/script_manager/script_runner.ex

@@ -1,24 +1,60 @@
 defmodule ScriptManager.ScriptRunner do
   @moduledoc """
   Runs shell scripts from `scripts/` and reports real duration + exit status.
+
+  Scripts that source `scripts/lib/common.sh` honour these env vars (set
+  any of them via the third arg of `run_script/3`):
+
+      GS_DRY_RUN=1     no destructive writes
+      GS_YES=1         skip confirmation prompts (CI mode)
+      GS_LOG_LEVEL=debug|info|warn|error
+      GS_PARALLEL=N    bounded parallelism for repo iteration
+      GS_REPO_LIST=…   one-repo-per-line filter file
+      NO_COLOR=1       disable ANSI in output
+
+  See `scripts/README.adoc` for the full common.sh contract.
   """
 
   @scripts_dir "scripts"
 
+  @doc """
+  Run a script. Backwards-compatible 2-arity form.
+  """
   @spec run_script(String.t(), list(String.t())) :: non_neg_integer()
-  def run_script(script_name, args \\ []) do
+  def run_script(script_name, args \\ []), do: run_script(script_name, args, %{})
+
+  @doc """
+  Run a script with an explicit env map. Use this to surface common.sh
+  flags (dry-run, log level, parallelism) from TUI menu choices.
+
+  Example: `run_script("audit_contractiles.sh", ["--report"], %{"GS_DRY_RUN" => "1"})`
+  """
+  @spec run_script(String.t(), list(String.t()), map()) :: non_neg_integer()
+  def run_script(script_name, args, env) when is_map(env) do
     script_path = Path.join(@scripts_dir, script_name)
 
     if !File.exists?(script_path) do
       IO.puts("❌ Script not found: #{script_path}")
       127
     else
+      env_list = Enum.map(env, fn {k, v} -> {to_string(k), to_string(v)} end)
+
+      if env_list != [] do
+        env_summary =
+          env_list
+          |> Enum.map(fn {k, v} -> "#{k}=#{v}" end)
+          |> Enum.join(" ")
+
+        IO.puts("ℹ️  env: #{env_summary}")
+      end
+
       started_at = System.monotonic_time(:millisecond)
 
       {_out, status} =
         System.cmd("bash", [script_path | args],
           into: IO.stream(:stdio, :line),
-          stderr_to_stdout: true
+          stderr_to_stdout: true,
+          env: env_list
         )
 
       elapsed_ms = System.monotonic_time(:millisecond) - started_at

scripts/lib/common.sh

@@ -393,6 +393,115 @@ gs::have() {
     command -v "$1" >/dev/null 2>&1
 }
 
+# -----------------------------------------------------------------------------
+# Ownership guard. Refuse to operate on repos owned by anyone outside the
+# allowlist. Folded in from the legacy scripts/lib/ownership_guard.sh
+# (which now sources this lib for backwards compat).
+#
+# Configuration (first match wins):
+#   $GIT_SCRIPTS_ALLOWED_OWNERS   space-separated list, env-var override
+#   ${GS_OWNERS_CONFIG} or scripts/../config/owners.config (sources ALLOWED_OWNERS=())
+#   /var/mnt/eclipse/repos/git-scripts/config/owners.config (legacy fallback)
+#   hard-coded ["hyperpolymath"]                            (final fallback)
+# -----------------------------------------------------------------------------
+
+if [[ -z "${GS_OWNERSHIP_GUARD_LOADED:-}" ]]; then
+    GS_OWNERSHIP_GUARD_LOADED=1
+
+    # Load allowlist.
+    if [[ -n "${GIT_SCRIPTS_ALLOWED_OWNERS:-}" ]]; then
+        # shellcheck disable=SC2206
+        ALLOWED_OWNERS=(${GIT_SCRIPTS_ALLOWED_OWNERS})
+        GS_OWNERS_SOURCE="env:GIT_SCRIPTS_ALLOWED_OWNERS"
+    else
+        __gs_owners_candidates=(
+            "${GS_OWNERS_CONFIG:-}"
+            "$(dirname -- "$(readlink -f "${BASH_SOURCE[0]}")")/../../config/owners.config"
+            "/var/mnt/eclipse/repos/git-scripts/config/owners.config"
+        )
+        GS_OWNERS_SOURCE=""
+        for __gs_c in "${__gs_owners_candidates[@]}"; do
+            [[ -z "${__gs_c}" || ! -f "${__gs_c}" ]] && continue
+            # shellcheck disable=SC1090
+            source "${__gs_c}"
+            GS_OWNERS_SOURCE="${__gs_c}"
+            break
+        done
+        [[ -z "${GS_OWNERS_SOURCE}" ]] && ALLOWED_OWNERS=("hyperpolymath")
+    fi
+fi
+
+__gs_lc() { printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]'; }
+
+# Return 0 if $1 is in ALLOWED_OWNERS (case-insensitive).
+gs::owner_allowed() {
+    local needle; needle="$(__gs_lc "${1:-}")"
+    [[ -z "${needle}" ]] && return 1
+    local allowed
+    for allowed in "${ALLOWED_OWNERS[@]}"; do
+        [[ "${needle}" = "$(__gs_lc "${allowed}")" ]] && return 0
+    done
+    return 1
+}
+
+# Print the owner segment of a local repo's `origin` URL.
+# Host-agnostic: GitHub, GitLab, Bitbucket, Gitea, codeberg, SSH, HTTPS.
+gs::repo_owner_from_remote() {
+    local repo_path="${1:-.}"
+    local url
+    url="$(git -C "${repo_path}" config --get remote.origin.url 2>/dev/null)" || return 1
+    [[ -z "${url}" ]] && return 1
+    url="${url%.git}"
+
+    local path_part=""
+    if [[ "${url}" =~ ^[^[:space:]/@]+@[^:]+:(.+)$ ]]; then
+        path_part="${BASH_REMATCH[1]}"
+    elif [[ "${url}" =~ ^[a-zA-Z]+://[^/]+(/.+)$ ]]; then
+        path_part="${BASH_REMATCH[1]}"
+    else
+        return 1
+    fi
+    path_part="${path_part#/}"; path_part="${path_part%/}"
+    [[ -z "${path_part}" ]] && return 1
+
+    local owner_dir owner
+    owner_dir="$(dirname "${path_part}")"
+    [[ "${owner_dir}" = "." || "${owner_dir}" = "/" ]] && return 1
+    owner="$(basename "${owner_dir}")"
+    [[ -z "${owner}" ]] && return 1
+    printf '%s\n' "${owner}"
+}
+
+# Soft check: 0 if local repo's owner is allowed.
+gs::repo_allowed() {
+    local owner
+    owner="$(gs::repo_owner_from_remote "${1:-.}")" || return 1
+    gs::owner_allowed "${owner}"
+}
+
+# Hard guard: print explanation and exit 78 (EX_CONFIG) if owner not allowed.
+gs::assert_owner_allowed() {
+    local owner="${1:-}"
+    if gs::owner_allowed "${owner}"; then
+        return 0
+    fi
+    {
+        printf '\n%s%s%s REFUSING to operate on owner %s%s%s\n' \
+            "${GS_C_RED}" "❌" "${GS_C_RST}" \
+            "${GS_C_BOLD}" "'${owner}'" "${GS_C_RST}"
+        printf '   This owner is not in the allowlist for git-scripts.\n'
+        printf '   Allowed owners: %s\n' "${ALLOWED_OWNERS[*]}"
+        printf '   Configure via:\n'
+        if [[ -n "${GS_OWNERS_SOURCE}" ]]; then
+            printf '     %s\n' "${GS_OWNERS_SOURCE}"
+        else
+            printf '     scripts/../config/owners.config\n'
+        fi
+        printf '   …or set GIT_SCRIPTS_ALLOWED_OWNERS="owner1 owner2" in env.\n\n'
+    } >&2
+    exit 78
+}
+
 # -----------------------------------------------------------------------------
 # Tiny flag parser. Consumes the standard flags and leaves the rest in
 # $GS_ARGS (an array). Recognised:

scripts/lib/ownership_guard.sh

@@ -1,135 +1,29 @@
 #!/usr/bin/env bash
 # SPDX-License-Identifier: PMPL-1.0-or-later
+# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 #
-# ownership_guard.sh — refuse to operate on repositories owned by anyone
-# outside the configured allowlist. Source this from any script that
-# touches GitHub or pushes to remotes.
+# ownership_guard.sh — backwards-compat shim.
 #
-# Public functions:
+# The canonical implementation lives in `lib/common.sh` under `gs::`-prefixed
+# names (gs::owner_allowed, gs::repo_owner_from_remote, gs::repo_allowed,
+# gs::assert_owner_allowed). This file re-exports them under their legacy
+# unprefixed names so existing `source` callers keep working.
+#
+# Public functions (legacy names — prefer the gs:: forms in new code):
 #   owner_allowed <owner>            — return 0 if allowed, 1 otherwise
-#   assert_owner_allowed <owner>     — exit 78 if owner is not allowed
 #   repo_owner_from_remote <path>    — print the GitHub owner of a local repo
 #   repo_allowed <path>              — return 0 if a local repo's owner is allowed
-#
-# Configuration is loaded from the first existing file:
-#   $(dirname this)/../../config/owners.config
-#   /var/mnt/eclipse/repos/git-scripts/config/owners.config
-# falling back to a hard-coded ["hyperpolymath"].
+#   assert_owner_allowed <owner>     — exit 78 if owner is not allowed
 
-# Idempotent: only load once per shell.
-if [[ "${_OWNERSHIP_GUARD_LOADED:-0}" == "1" ]]; then
-    return 0 2>/dev/null || true
-fi
+# Idempotent guard kept for source-twice safety.
+[[ -n "${_OWNERSHIP_GUARD_LOADED:-}" ]] && return 0
 _OWNERSHIP_GUARD_LOADED=1
 
-_GUARD_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-_OWNERS_CONFIG_CANDIDATES=(
-    "${_GUARD_DIR}/../../config/owners.config"
-    "/var/mnt/eclipse/repos/git-scripts/config/owners.config"
-)
-
-_loaded_owners_config=""
-for _candidate in "${_OWNERS_CONFIG_CANDIDATES[@]}"; do
-    if [[ -f "${_candidate}" ]]; then
-        # shellcheck disable=SC1090
-        source "${_candidate}"
-        _loaded_owners_config="${_candidate}"
-        break
-    fi
-done
-
-if [[ -z "${_loaded_owners_config}" ]]; then
-    ALLOWED_OWNERS=("hyperpolymath")
-fi
-
-# Lowercase a string (portable; no `${var,,}` to keep bash 3 compat).
-_lc() {
-    printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]'
-}
-
-# Return 0 if $1 is in ALLOWED_OWNERS (case-insensitive).
-owner_allowed() {
-    local needle
-    needle="$(_lc "${1:-}")"
-    [[ -z "${needle}" ]] && return 1
-    local allowed
-    for allowed in "${ALLOWED_OWNERS[@]}"; do
-        if [[ "${needle}" == "$(_lc "${allowed}")" ]]; then
-            return 0
-        fi
-    done
-    return 1
-}
-
-# Print the owner of a local git repo, derived from `origin` URL.
-# Host-agnostic: works for GitHub, GitLab, Bitbucket, Gitea, codeberg,
-# self-hosted servers, and SSH-style URLs. The owner is taken as the
-# second-to-last path segment (after stripping a trailing .git).
-# Returns 1 (and prints nothing) if no owner can be parsed.
-repo_owner_from_remote() {
-    local repo_path="${1:-.}"
-    local url
-    url=$(git -C "${repo_path}" config --get remote.origin.url 2>/dev/null) || return 1
-    [[ -z "${url}" ]] && return 1
-
-    # Strip a trailing .git for clean splitting.
-    url="${url%.git}"
-
-    local path_part=""
-
-    if [[ "${url}" =~ ^[^[:space:]/@]+@[^:]+:(.+)$ ]]; then
-        # SSH-style: [user@]host:path
-        path_part="${BASH_REMATCH[1]}"
-    elif [[ "${url}" =~ ^[a-zA-Z]+://[^/]+(/.+)$ ]]; then
-        # URL-style: proto://[creds@]host[:port]/path
-        path_part="${BASH_REMATCH[1]}"
-    else
-        return 1
-    fi
-
-    # Trim leading/trailing slashes, then take the segment before the last.
-    path_part="${path_part#/}"
-    path_part="${path_part%/}"
-    [[ -z "${path_part}" ]] && return 1
-
-    local owner_dir owner
-    owner_dir="$(dirname "${path_part}")"
-    [[ "${owner_dir}" == "." || "${owner_dir}" == "/" ]] && return 1
-
-    owner="$(basename "${owner_dir}")"
-    [[ -z "${owner}" ]] && return 1
-
-    printf '%s\n' "${owner}"
-}
-
-# Soft check: returns 0 if the local repo's owner is allowed.
-repo_allowed() {
-    local owner
-    owner="$(repo_owner_from_remote "${1:-.}")" || return 1
-    owner_allowed "${owner}"
-}
+__OG_DIR="$(cd -- "$(dirname -- "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+# shellcheck disable=SC1091
+. "${__OG_DIR}/common.sh"
 
-# Hard guard: print an explanation and exit if the owner is not allowed.
-# Use at the top of any script that targets a single org/user.
-assert_owner_allowed() {
-    local owner="${1:-}"
-    if owner_allowed "${owner}"; then
-        return 0
-    fi
-    {
-        echo ""
-        echo "❌ REFUSING to operate on owner '${owner}'."
-        echo "   This owner is not in the allowlist for git-scripts."
-        echo "   Allowed owners: ${ALLOWED_OWNERS[*]}"
-        echo ""
-        echo "   To allow it, edit:"
-        if [[ -n "${_loaded_owners_config}" ]]; then
-            echo "     ${_loaded_owners_config}"
-        else
-            echo "     config/owners.config"
-        fi
-        echo "   …or set GIT_SCRIPTS_ALLOWED_OWNERS=\"owner1 owner2\" in the environment."
-        echo ""
-    } >&2
-    exit 78  # EX_CONFIG
-}
+owner_allowed()           { gs::owner_allowed "$@"; }
+repo_owner_from_remote()  { gs::repo_owner_from_remote "$@"; }
+repo_allowed()            { gs::repo_allowed "$@"; }
+assert_owner_allowed()    { gs::assert_owner_allowed "$@"; }