vouchington-tooling 0.0.16 → 0.0.17

package/scripts/gha/ghcr-package-retention.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Keep the most recent KEEP_MIN non-protected GHCR package versions, plus any
+# version whose tags match the protected prefix/contains rules.
+set -euo pipefail
+
+KEEP_MIN="${KEEP_MIN:-10}"
+OWNER_TYPE="${GHCR_OWNER_TYPE:-user}"
+OWNER="${GHCR_OWNER:-}"
+PROTECTED_PREFIX="${PROTECTED_TAG_PREFIX:-latest}"
+PROTECTED_CONTAINS="${PROTECTED_TAG_CONTAINS:-buildcache}"
+
+case "$KEEP_MIN" in
+  *[!0-9]* | '')
+    echo "ghcr-package-retention: KEEP_MIN must be a non-negative integer" >&2
+    exit 2
+    ;;
+esac
+
+case "$OWNER_TYPE" in
+  user) package_root="user/packages/container" ;;
+  org)
+    [ -n "$OWNER" ] || {
+      echo "ghcr-package-retention: GHCR_OWNER is required when GHCR_OWNER_TYPE=org" >&2
+      exit 2
+    }
+    package_root="orgs/${OWNER}/packages/container"
+    ;;
+  *)
+    echo "ghcr-package-retention: GHCR_OWNER_TYPE must be user or org" >&2
+    exit 2
+    ;;
+esac
+
+if [ "$#" -eq 0 ]; then
+  echo "usage: ghcr-package-retention.sh <url-encoded-package>..." >&2
+  exit 2
+fi
+
+for pkg in "$@"; do
+  echo "=== Processing $pkg ==="
+  count=0
+  while IFS= read -r version_json; do
+    version_id=$(printf '%s' "$version_json" | jq -r '.id')
+    tags=$(printf '%s' "$version_json" | jq -r '[.metadata.container.tags[]?]')
+
+    protected=$(printf '%s' "$tags" |
+      jq --arg prefix "$PROTECTED_PREFIX" --arg contains "$PROTECTED_CONTAINS" \
+        'map(select(startswith($prefix) or contains($contains))) | length')
+    if [ "$protected" -gt 0 ]; then
+      printf '  keep (protected tag): version %s\n' "$version_id"
+      continue
+    fi
+
+    count=$((count + 1))
+    if [ "$count" -le "$KEEP_MIN" ]; then
+      printf '  keep (recent %d/%d): version %s\n' "$count" "$KEEP_MIN" "$version_id"
+      continue
+    fi
+
+    printf '  delete: version %s\n' "$version_id"
+    gh api -X DELETE "${package_root}/$pkg/versions/$version_id" || true
+  done < <(gh api \
+    "${package_root}/$pkg/versions?per_page=100" \
+    --jq '.[] | @json')
+done

package/scripts/gha/install-github-release.sh

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 usage() {
-  echo "usage: install-github-release.sh --repo owner/name --version VERSION --asset TEMPLATE --bin NAME [--tag-prefix PREFIX] [--strip-components N]" >&2
+  echo "usage: install-github-release.sh --repo owner/name --version VERSION --asset TEMPLATE --bin NAME [--tag-prefix PREFIX] [--strip-components N] [--bin-dir DIR] [--version-flag FLAG] [--checksums-asset NAME] [--no-checksum]" >&2
 }
 
 REPO="${REPO:-}"
@@ -11,6 +11,10 @@ ASSET_TEMPLATE="${ASSET_TEMPLATE:-}"
 BIN_NAME="${BIN_NAME:-}"
 TAG_PREFIX="${TAG_PREFIX:-}"
 STRIP_COMPONENTS="${STRIP_COMPONENTS:-1}"
+BIN_DIR="${INSTALL_BIN_DIR:-}"
+VERSION_FLAG="${VERSION_FLAG:---version}"
+CHECKSUMS_ASSET="${CHECKSUMS_ASSET:-}"
+NO_CHECKSUM="${NO_CHECKSUM:-0}"
 
 if [ -n "${RELEASE_OWNER:-}" ] && [ -n "${RELEASE_REPO:-}" ]; then
   REPO="${RELEASE_OWNER}/${RELEASE_REPO}"
@@ -48,6 +52,25 @@ while [ "${#}" -gt 0 ]; do
       STRIP_COMPONENTS="$2"
       shift 2
       ;;
+    --bin-dir)
+      [ "${#}" -ge 2 ] || { usage; exit 2; }
+      BIN_DIR="$2"
+      shift 2
+      ;;
+    --version-flag)
+      [ "${#}" -ge 2 ] || { usage; exit 2; }
+      VERSION_FLAG="$2"
+      shift 2
+      ;;
+    --checksums-asset)
+      [ "${#}" -ge 2 ] || { usage; exit 2; }
+      CHECKSUMS_ASSET="$2"
+      shift 2
+      ;;
+    --no-checksum)
+      NO_CHECKSUM=1
+      shift
+      ;;
     -h | --help)
       usage
       exit 2
@@ -74,7 +97,7 @@ if ! [[ "$STRIP_COMPONENTS" =~ ^[0-9]+$ ]]; then
   exit 2
 fi
 
-BIN_DIR="${RUNNER_TEMP:-${HOME}/.local}/bin"
+BIN_DIR="${BIN_DIR:-${RUNNER_TEMP:-${HOME}/.local}/bin}"
 mkdir -p "$BIN_DIR"
 if [ -n "${GITHUB_PATH:-}" ]; then
   echo "$BIN_DIR" >> "$GITHUB_PATH"
@@ -82,7 +105,8 @@ fi
 
 already_installed() {
   local output
-  output="$("$BIN_DIR/$BIN_NAME" --version 2>/dev/null || true)"
+  # shellcheck disable=SC2086
+  output="$("$BIN_DIR/$BIN_NAME" $VERSION_FLAG 2>/dev/null || true)"
   printf '%s\n' "$output" | awk -v v="$VERSION" '
     {
       n = split($0, parts, /[^0-9A-Za-z.-]+/)
@@ -115,22 +139,42 @@ fi
 asset_name="$ASSET_TEMPLATE"
 asset_name="${asset_name//\{version\}/${VERSION}}"
 asset_name="${asset_name//\{platform\}/${RELEASE_PLATFORM}}"
+checksums_name="$CHECKSUMS_ASSET"
+checksums_name="${checksums_name//\{version\}/${VERSION}}"
+checksums_name="${checksums_name//\{platform\}/${RELEASE_PLATFORM}}"
 base_url="https://github.com/${REPO}/releases/download/${TAG_PREFIX}${VERSION}"
-archive="${RUNNER_TEMP:-/tmp}/${BIN_NAME}-${VERSION}-${RELEASE_PLATFORM}.tar.gz"
-extract_dir="${RUNNER_TEMP:-/tmp}/${BIN_NAME}-${VERSION}-${RELEASE_PLATFORM}"
+work="${RUNNER_TEMP:-/tmp}/${BIN_NAME}-${VERSION}-${RELEASE_PLATFORM}"
+archive="${work}-archive"
+extract_dir="${work}-extract"
 
 rm -rf "$extract_dir"
 mkdir -p "$extract_dir"
 curl -fsSL -o "$archive" "${base_url}/${asset_name}"
-curl -fsSL -o "${archive}.sha256" "${base_url}/${asset_name}.sha256"
-expected=$(awk '{print $1}' "${archive}.sha256")
-if command -v sha256sum >/dev/null 2>&1; then
-  echo "${expected}  ${archive}" | sha256sum -c -
-else
-  echo "${expected}  ${archive}" | shasum -a 256 -c -
+if [ "$NO_CHECKSUM" != 1 ]; then
+  if [ -n "$checksums_name" ]; then
+    curl -fsSL -o "${archive}.checksums" "${base_url}/${checksums_name}"
+    expected=$(grep -F "$asset_name" "${archive}.checksums" | awk '{print $1}')
+    rm "${archive}.checksums"
+  else
+    curl -fsSL -o "${archive}.sha256" "${base_url}/${asset_name}.sha256"
+    expected=$(awk '{print $1}' "${archive}.sha256")
+    rm "${archive}.sha256"
+  fi
+  if [ -z "$expected" ]; then
+    echo "install-github-release.sh: checksum not found for ${asset_name}" >&2
+    rm -f "$archive"
+    exit 1
+  fi
+  if command -v sha256sum >/dev/null 2>&1; then
+    echo "${expected}  ${archive}" | sha256sum -c -
+  else
+    echo "${expected}  ${archive}" | shasum -a 256 -c -
+  fi
 fi
-rm "${archive}.sha256"
-tar -xzf "$archive" -C "$extract_dir" --strip-components="$STRIP_COMPONENTS"
+case "$asset_name" in
+  *.zip) unzip -q "$archive" -d "$extract_dir" ;;
+  *) tar -xzf "$archive" -C "$extract_dir" --strip-components="$STRIP_COMPONENTS" ;;
+esac
 mv "$extract_dir/$BIN_NAME" "$BIN_DIR/$BIN_NAME"
 chmod +x "$BIN_DIR/$BIN_NAME"
 rm -rf "$archive" "$extract_dir"

package/scripts/gha/install-playwright-chromium-arm64.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/gha/download-with-diagnostics.sh
+source "${script_dir}/download-with-diagnostics.sh"
+
+browsers_json="${PLAYWRIGHT_BROWSERS_JSON:-}"
+if [ -z "$browsers_json" ] || [ ! -f "$browsers_json" ]; then
+  browsers_json="node_modules/playwright/node_modules/playwright-core/browsers.json"
+fi
+if [ ! -f "$browsers_json" ]; then
+  browsers_json=$(find node_modules -path '*/playwright-core/browsers.json' -print -quit 2>/dev/null || true)
+fi
+if [ -z "$browsers_json" ] || [ ! -f "$browsers_json" ]; then
+  echo "::error::playwright-core/browsers.json not found; set PLAYWRIGHT_BROWSERS_JSON or install Playwright first"
+  exit 1
+fi
+
+browsers_path="${PLAYWRIGHT_BROWSERS_PATH:-${HOME}/.cache/ms-playwright}"
+mirror="${PLAYWRIGHT_CHROMIUM_MIRROR:-https://cdn.playwright.dev/dbazure/download/playwright/builds/chromium}"
+mkdir -p "$browsers_path"
+
+browser_revision() {
+  node -e "const fs=require('node:fs'); const file=process.argv[1]; const name=process.argv[2]; const browser=JSON.parse(fs.readFileSync(file,'utf8')).browsers.find(b => b.name === name); if (!browser) { process.stderr.write('unknown browser '+name); process.exit(1) } process.stdout.write(String(browser.revision))" "$browsers_json" "$1"
+}
+
+install_browser() {
+  local name="$1" archive="$2"
+  local rev
+  rev=$(browser_revision "$name")
+  local dir="${browsers_path}/${name//-/_}-${rev}"
+  local marker="${dir}/INSTALLATION_COMPLETE"
+
+  if [ -f "$marker" ]; then
+    echo "Already installed: ${name}-${rev} (cache hit)"
+    return
+  fi
+
+  echo "Installing ${name} v${rev} via curl + system unzip"
+  local tmp="${RUNNER_TEMP:-/tmp}/${name}-${rev}-${archive}"
+  rm -f "$tmp"
+  rm -rf "$dir"
+  mkdir -p "$dir"
+  # integrity-check: skip reason=playwright-cdn-provides-no-published-checksums
+  ci_download_to "${mirror}/${rev}/${archive}" "$tmp" --retry 3 --retry-all-errors --max-time 300 --retry-max-time 300
+  unzip -q "$tmp" -d "$dir"
+  rm -f "$tmp"
+
+  local exe
+  case "$name" in
+    chromium) exe="$dir/chrome-linux/chrome" ;;
+    chromium-headless-shell) exe="$dir/chrome-linux/headless_shell" ;;
+    *)
+      echo "::error::install_browser: unknown browser name '$name'"
+      exit 1
+      ;;
+  esac
+  if [ ! -x "$exe" ]; then
+    echo "::error::Expected ${name} binary missing or not executable after extract: $exe"
+    exit 1
+  fi
+
+  touch "$marker"
+  echo "Installed ${name} at ${dir}"
+}
+
+if [ "$#" -eq 0 ]; then
+  install_browser chromium chromium-linux-arm64.zip
+  install_browser chromium-headless-shell chromium-headless-shell-linux-arm64.zip
+  exit 0
+fi
+
+while [ "$#" -gt 0 ]; do
+  spec="$1"
+  shift
+  name="${spec%%:*}"
+  archive="${spec#*:}"
+  if [ -z "$name" ] || [ "$archive" = "$spec" ]; then
+    echo "::error::browser spec must be name:archive, got '$spec'"
+    exit 2
+  fi
+  install_browser "$name" "$archive"
+done

package/scripts/gha/lint-links.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Two-pass Markdown link check. Pass 1: internal relative links and #anchors
+# fail the job. Pass 2: external http/https links warn only.
+set -euo pipefail
+
+explicit_offline=false
+options=()
+files=()
+globs=()
+config="lychee.toml"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --offline=true | --offline)
+      explicit_offline=true
+      shift
+      ;;
+    --offline=false)
+      shift
+      ;;
+    --config)
+      [ "$#" -ge 2 ] || {
+        echo "lint-links: --config requires a path" >&2
+        exit 2
+      }
+      config="$2"
+      shift 2
+      ;;
+    --glob)
+      [ "$#" -ge 2 ] || {
+        echo "lint-links: --glob requires a pattern" >&2
+        exit 2
+      }
+      globs+=("$2")
+      shift 2
+      ;;
+    --)
+      shift
+      files+=("$@")
+      break
+      ;;
+    -*)
+      options+=("$1")
+      shift
+      ;;
+    *)
+      if [[ "$1" == *.md && -f "$1" ]]; then
+        files+=("$1")
+      else
+        options+=("$1")
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [ "${#files[@]}" -eq 0 ]; then
+  if [ "${#globs[@]}" -eq 0 ]; then
+    globs=('*.md')
+  fi
+  while IFS= read -r -d '' file; do
+    if [ -f "$file" ]; then
+      files+=("$file")
+    fi
+  done < <(git ls-files -z -- "${globs[@]}")
+fi
+
+if [ "${#files[@]}" -eq 0 ]; then
+  echo "No tracked Markdown files found"
+  exit 0
+fi
+
+base=(lychee --config "$config")
+if [ "${#options[@]}" -gt 0 ]; then
+  base+=("${options[@]+"${options[@]}"}")
+fi
+
+echo "::group::Internal link check (relative paths + anchors)"
+"${base[@]}" --offline --include-fragments -- "${files[@]}"
+echo "::endgroup::"
+
+if [ "$explicit_offline" = "true" ]; then
+  exit 0
+fi
+
+echo "::group::External link check (warn-only)"
+if ! "${base[@]}" --scheme http --scheme https -- "${files[@]}"; then
+  echo "::endgroup::"
+  echo "::warning title=External link check::External link(s) failed (non-blocking) — see the 'External link check' group above."
+  exit 0
+fi
+echo "::endgroup::"

package/scripts/gha/materialize-pr-context.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# Materialize PR title, body, files, diff, comments, and linked issue/PR
+# threads so a review agent does not need gh or bash.
+set -euo pipefail
+
+PR_NUMBER="${PR_NUMBER:?PR_NUMBER is required}"
+GITHUB_REPOSITORY="${GITHUB_REPOSITORY:?GITHUB_REPOSITORY is required}"
+GITHUB_WORKSPACE="${GITHUB_WORKSPACE:?GITHUB_WORKSPACE is required}"
+MAX_MATERIALIZED="${MAX_MATERIALIZED:-20}"
+MAX_SEEN="${MAX_SEEN:-40}"
+
+case "$MAX_MATERIALIZED" in
+  *[!0-9]* | '')
+    echo "materialize-pr-context: MAX_MATERIALIZED must be a non-negative integer" >&2
+    exit 2
+    ;;
+esac
+case "$MAX_SEEN" in
+  *[!0-9]* | '')
+    echo "materialize-pr-context: MAX_SEEN must be a non-negative integer" >&2
+    exit 2
+    ;;
+esac
+
+review_context="${REVIEW_CONTEXT_DIR:-${GITHUB_WORKSPACE}/.review-context}"
+rm -rf "$review_context"
+mkdir -p "$review_context/issues"
+
+extract_issue_numbers() {
+  grep -oE "(https://github.com/${GITHUB_REPOSITORY}/(issues|pull)/[0-9]+|#[0-9]+)" |
+    grep -oE '[0-9]+' ||
+    true
+}
+
+enqueue_from_text() {
+  local seen_file="$1"
+  local queue_file="$2"
+  local materialized_file="$3"
+  local number
+  while IFS= read -r number; do
+    [ -n "$number" ] || continue
+    [ "$number" = "$PR_NUMBER" ] && continue
+    grep -qxF "$number" "$seen_file" && continue
+    if [ "$(wc -l <"$materialized_file" | tr -d ' ')" -ge "$MAX_MATERIALIZED" ]; then
+      return 0
+    fi
+    if [ "$(wc -l <"$seen_file" | tr -d ' ')" -ge "$MAX_SEEN" ]; then
+      return 0
+    fi
+    printf '%s\n' "$number" >>"$seen_file"
+    printf '%s\n' "$number" >>"$queue_file"
+  done
+}
+
+gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" \
+  --json title,body,url,author,baseRefName,headRefName,headRefOid \
+  >"$review_context/pr.json"
+gh api --paginate --slurp "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?per_page=100" |
+  jq 'add // []' >"$review_context/files.json"
+if ! gh pr diff "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" >"$review_context/pr.diff"; then
+  printf 'PR diff unavailable (GitHub limits patch responses to 300 files). Use files.json.\n' \
+    >"$review_context/pr.diff"
+fi
+gh api --paginate --slurp "repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments?per_page=100" |
+  jq 'add // []' >"$review_context/pr-comments.json"
+gh api --paginate --slurp "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/comments?per_page=100" |
+  jq 'add // []' >"$review_context/pr-review-comments.json"
+gh api --paginate --slurp "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/reviews?per_page=100" |
+  jq 'add // []' >"$review_context/pr-reviews.json"
+
+seen_file="${review_context}/.seen"
+queue_file="${review_context}/.queue"
+materialized_file="${review_context}/.materialized"
+: >"$seen_file"
+: >"$queue_file"
+: >"$materialized_file"
+
+{
+  jq -r '.body // ""' "$review_context/pr.json"
+  jq -r '.[].body // ""' "$review_context/pr-comments.json"
+  jq -r '.[].body // ""' "$review_context/pr-review-comments.json"
+  jq -r '.[].body // ""' "$review_context/pr-reviews.json"
+} | extract_issue_numbers | enqueue_from_text "$seen_file" "$queue_file" "$materialized_file"
+
+index=1
+while true; do
+  if [ "$(wc -l <"$materialized_file" | tr -d ' ')" -ge "$MAX_MATERIALIZED" ]; then
+    break
+  fi
+  issue_number="$(sed -n "${index}p" "$queue_file")"
+  [ -n "$issue_number" ] || break
+  index=$((index + 1))
+  if ! gh api "repos/${GITHUB_REPOSITORY}/issues/${issue_number}" \
+    --jq '{number,title,body,url,pull_request}' \
+    >"$review_context/issues/${issue_number}.json"; then
+    rm -f "$review_context/issues/${issue_number}.json"
+    continue
+  fi
+  printf '%s\n' "$issue_number" >>"$materialized_file"
+  gh api --paginate --slurp \
+    "repos/${GITHUB_REPOSITORY}/issues/${issue_number}/comments?per_page=100" |
+    jq 'add // []' >"$review_context/issues/${issue_number}-comments.json" ||
+    printf '[]\n' >"$review_context/issues/${issue_number}-comments.json"
+  {
+    jq -r '.body // ""' "$review_context/issues/${issue_number}.json"
+    jq -r '.[].body // ""' "$review_context/issues/${issue_number}-comments.json"
+    if jq -e '.pull_request != null' "$review_context/issues/${issue_number}.json" >/dev/null; then
+      gh api --paginate --slurp \
+        "repos/${GITHUB_REPOSITORY}/pulls/${issue_number}/comments?per_page=100" |
+        jq 'add // []' >"$review_context/issues/${issue_number}-review-comments.json" ||
+        printf '[]\n' >"$review_context/issues/${issue_number}-review-comments.json"
+      gh api --paginate --slurp \
+        "repos/${GITHUB_REPOSITORY}/pulls/${issue_number}/reviews?per_page=100" |
+        jq 'add // []' >"$review_context/issues/${issue_number}-reviews.json" ||
+        printf '[]\n' >"$review_context/issues/${issue_number}-reviews.json"
+      jq -r '.[].body // ""' "$review_context/issues/${issue_number}-review-comments.json"
+      jq -r '.[].body // ""' "$review_context/issues/${issue_number}-reviews.json"
+    fi
+  } | extract_issue_numbers | enqueue_from_text "$seen_file" "$queue_file" "$materialized_file"
+done
+
+rm -f "$seen_file" "$queue_file" "$materialized_file"
+printf 'Materialized PR #%s context in %s\n' "$PR_NUMBER" "$review_context"

package/scripts/gha/run-with-timeout.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$#" -lt 3 ]; then
+  echo "::error::run-with-timeout: timeout runner requires timeout seconds, kill-after seconds, and a command"
+  exit 2
+fi
+
+timeout_seconds="$1"
+kill_after_seconds="$2"
+shift 2
+
+case "$timeout_seconds" in
+  *[!0-9]* | '0' | '')
+    echo "::error::run-with-timeout: timeout seconds must be a positive integer"
+    exit 2
+    ;;
+esac
+case "$kill_after_seconds" in
+  *[!0-9]* | '0' | '')
+    echo "::error::run-with-timeout: kill-after seconds must be a positive integer"
+    exit 2
+    ;;
+esac
+
+if command -v timeout >/dev/null 2>&1 &&
+  timeout --version 2>/dev/null | grep -q 'GNU coreutils'; then
+  timeout_pid=""
+  pending_signal_number=""
+
+  cleanup_timeout_group() {
+    [ -n "$timeout_pid" ] || return
+    kill -KILL -- "-$timeout_pid" 2>/dev/null || true
+  }
+
+  # Invoked through signal traps.
+  # shellcheck disable=SC2329
+  handle_timeout_signal() {
+    signal_number="$1"
+    if [ -z "$timeout_pid" ]; then
+      pending_signal_number="$signal_number"
+      return
+    fi
+    kill -TERM "$timeout_pid" 2>/dev/null || true
+    wait "$timeout_pid" 2>/dev/null || true
+    cleanup_timeout_group
+    exit $((128 + signal_number))
+  }
+
+  trap 'handle_timeout_signal 2' INT
+  trap 'handle_timeout_signal 15' TERM
+  trap 'handle_timeout_signal 1' HUP
+
+  timeout --kill-after="${kill_after_seconds}s" "${timeout_seconds}s" "$@" &
+  timeout_pid=$!
+  if [ -n "$pending_signal_number" ]; then
+    handle_timeout_signal "$pending_signal_number"
+  fi
+  if wait "$timeout_pid"; then
+    status=0
+  else
+    status=$?
+  fi
+  cleanup_timeout_group
+  exit "$status"
+fi
+
+if command -v perl >/dev/null 2>&1; then
+  exec perl -e '
+    my $timeout = shift @ARGV;
+    my $kill_after = shift @ARGV;
+    sub terminate_group {
+      my ($pid) = @_;
+      kill(15, -$pid);
+      for (1 .. ($kill_after * 10)) {
+        waitpid($pid, 1);
+        return if kill(0, -$pid) == 0;
+        select undef, undef, undef, 0.1;
+      }
+      kill(9, -$pid);
+      waitpid($pid, 0);
+    }
+    my $pid = fork();
+    if (!defined $pid) {
+      exit 125;
+    }
+    if ($pid == 0) {
+      setpgrp(0, 0);
+      exec @ARGV;
+      exit 127;
+    }
+    my $timed_out = 0;
+    local $SIG{INT} = sub {
+      terminate_group($pid);
+      exit 130;
+    };
+    local $SIG{TERM} = sub {
+      terminate_group($pid);
+      exit 143;
+    };
+    local $SIG{HUP} = sub {
+      terminate_group($pid);
+      exit 129;
+    };
+    local $SIG{ALRM} = sub {
+      $timed_out = 1;
+      terminate_group($pid);
+    };
+    alarm $timeout;
+    waitpid($pid, 0);
+    my $status = $?;
+    alarm 0;
+    exit 124 if $timed_out;
+    exit($status & 127 ? 128 + ($status & 127) : $status >> 8);
+  ' "$timeout_seconds" "$kill_after_seconds" "$@"
+fi
+
+echo "::error::run-with-timeout: neither GNU timeout nor Perl is available to enforce the deadline"
+exit 125

package/scripts/gha/wait-for-apt-locks.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$(uname -s)" != "Linux" ]; then
+  exit 0
+fi
+
+timeout_seconds="${APT_LOCK_TIMEOUT_SECONDS:-120}"
+case "$timeout_seconds" in
+  *[!0-9]* | '')
+    echo "::error::wait-for-apt-locks: APT_LOCK_TIMEOUT_SECONDS must be a non-negative integer"
+    exit 2
+    ;;
+esac
+
+lock_probe_cmd=()
+lock_probe_detail_cmd=()
+if command -v fuser >/dev/null 2>&1; then
+  lock_probe_cmd=(fuser)
+  lock_probe_detail_cmd=(fuser -v)
+elif command -v lsof >/dev/null 2>&1; then
+  lock_probe_cmd=(lsof)
+  lock_probe_detail_cmd=(lsof -w)
+else
+  echo "::warning::fuser and lsof are unavailable; skipping apt/dpkg lock probe"
+  exit 0
+fi
+if command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then
+  lock_probe_cmd=(sudo -n "${lock_probe_cmd[@]}")
+  lock_probe_detail_cmd=(sudo -n "${lock_probe_detail_cmd[@]}")
+fi
+
+deadline=$((SECONDS + timeout_seconds))
+lock_paths=(
+  /var/lib/apt/lists/lock
+  /var/lib/dpkg/lock
+  /var/lib/dpkg/lock-frontend
+  /var/cache/apt/archives/lock
+)
+busy_paths=()
+
+while true; do
+  busy_paths=()
+  for lock_path in "${lock_paths[@]}"; do
+    if [ -e "$lock_path" ] && "${lock_probe_cmd[@]}" "$lock_path" >/dev/null 2>&1; then
+      busy_paths+=("$lock_path")
+    fi
+  done
+
+  if [ "${#busy_paths[@]}" -eq 0 ]; then
+    exit 0
+  fi
+  if [ "$SECONDS" -ge "$deadline" ]; then
+    echo "::error::Timed out waiting for apt/dpkg locks after ${timeout_seconds}s: ${busy_paths[*]}"
+    "${lock_probe_detail_cmd[@]}" "${busy_paths[@]}" || true
+    exit 1
+  fi
+  echo "::warning::Waiting for apt/dpkg locks: ${busy_paths[*]}"
+  sleep 5
+done