From dab36ea95d34d49081c9d8d1c801e2ffc876cace Mon Sep 17 00:00:00 2001
From: jwinterm <johnwmurphy@gmail.com>
Date: Tue, 7 Jul 2026 18:38:30 -0400
Subject: [PATCH] Add AMPB browser source build spike tools

---
 docs/browser-builds.md               | 57 ++++++++++++++++++++++++++++
 tools/browser-android-build-probe.sh | 27 +++++++++++++
 tools/browser-source-plan.sh         | 19 ++++++++++
 tools/browser-source-report.sh       | 21 ++++++++++
 tools/browser-source-sync.sh         | 40 +++++++++++++++++++
 5 files changed, 164 insertions(+)
 create mode 100644 tools/browser-android-build-probe.sh
 create mode 100644 tools/browser-source-plan.sh
 create mode 100644 tools/browser-source-report.sh
 create mode 100644 tools/browser-source-sync.sh

diff --git a/docs/browser-builds.md b/docs/browser-builds.md
index 6ad7e3f..ec379d1 100644
--- a/docs/browser-builds.md
+++ b/docs/browser-builds.md
@@ -35,6 +35,63 @@ The script creates:
 - `/tmp/ampb-browser-build/artifacts`
 - `/tmp/ampb-browser-build/logs`
 
+## Source Plan
+
+Print the canonical source targets and paths:
+
+```sh
+sh tools/browser-source-plan.sh
+```
+
+Clone or refresh the source trees under `/tmp`:
+
+```sh
+sh tools/browser-source-sync.sh
+```
+
+Report checked-out source revisions:
+
+```sh
+sh tools/browser-source-report.sh
+```
+
+Defaults:
+
+- Current Gecko / Firefox Android source: `https://github.com/mozilla/gecko-dev.git`
+- Tor Browser build recipes: `https://gitlab.torproject.org/tpo/applications/tor-browser-build.git`
+- Legacy archived Android layout reference: `https://github.com/mozilla-mobile/firefox-android.git`
+
+Override repositories for experiments without editing the repo:
+
+```sh
+AMPB_GECKO_REPO=https://github.com/mozilla/gecko-dev.git sh tools/browser-source-sync.sh
+```
+
+The legacy Firefox Android repository is archived and should not be treated as the current
+source of truth. Clone it only when comparing older `fenix`, `focus-android`, or
+`android-components` layout:
+
+```sh
+AMPB_INCLUDE_LEGACY_FIREFOX_ANDROID=1 sh tools/browser-source-sync.sh
+```
+
+## Android Build Probe
+
+Run the first Android build-discovery command from the `/tmp` checkout while keeping
+Gradle, pip, Python bytecode, and Mozilla build state in `/tmp`:
+
+```sh
+sh tools/browser-android-build-probe.sh
+```
+
+The probe writes its log to
+`/tmp/ampb-browser-build/logs/gecko-android-mach-probe.log`.
+
+This first probe intentionally asks `mach` for Android build help instead of compiling the
+world. It verifies that the current Gecko checkout, `mach`, Python virtualenv state, and
+Android build command entry point can initialize from `/tmp` before a longer bootstrap or
+compile run.
+
 ## Repo Rule
 
 Keep only repeatable scripts, clean docs, and small AMPB source changes in this repo.
diff --git a/tools/browser-android-build-probe.sh b/tools/browser-android-build-probe.sh
new file mode 100644
index 0000000..66ee4b5
--- /dev/null
+++ b/tools/browser-android-build-probe.sh
@@ -0,0 +1,27 @@
+#!/bin/sh
+set -eu
+
+root="${AMPB_BROWSER_BUILD_ROOT:-/tmp/ampb-browser-build}"
+gecko_dir="$root/src/gecko-dev"
+log="$root/logs/gecko-android-mach-probe.log"
+
+if [ ! -d "$gecko_dir" ]; then
+  printf 'missing gecko checkout: %s\n' "$gecko_dir" >&2
+  exit 1
+fi
+
+mkdir -p "$root/cache/gradle"
+mkdir -p "$root/cache/mozbuild"
+mkdir -p "$root/cache/pip"
+mkdir -p "$root/cache/pycache"
+mkdir -p "$root/logs"
+
+cd "$gecko_dir"
+
+MOZBUILD_STATE_PATH="$root/cache/mozbuild" \
+GRADLE_USER_HOME="$root/cache/gradle" \
+PIP_CACHE_DIR="$root/cache/pip" \
+PYTHONPYCACHEPREFIX="$root/cache/pycache" \
+  ./mach build mobile/android --help >"$log" 2>&1
+
+printf 'AMPB_ANDROID_BUILD_PROBE status=ok log=%s\n' "$log"
diff --git a/tools/browser-source-plan.sh b/tools/browser-source-plan.sh
new file mode 100644
index 0000000..69c9716
--- /dev/null
+++ b/tools/browser-source-plan.sh
@@ -0,0 +1,19 @@
+#!/bin/sh
+set -eu
+
+root="${AMPB_BROWSER_BUILD_ROOT:-/tmp/ampb-browser-build}"
+
+gecko_repo="${AMPB_GECKO_REPO:-https://github.com/mozilla/gecko-dev.git}"
+legacy_android_repo="${AMPB_LEGACY_FIREFOX_ANDROID_REPO:-https://github.com/mozilla-mobile/firefox-android.git}"
+tor_build_repo="${AMPB_TOR_BROWSER_BUILD_REPO:-https://gitlab.torproject.org/tpo/applications/tor-browser-build.git}"
+
+printf 'AMPB_BROWSER_BUILD_ROOT=%s\n' "$root"
+printf 'AMPB_GECKO_REPO=%s\n' "$gecko_repo"
+printf 'AMPB_GECKO_DIR=%s\n' "$root/src/gecko-dev"
+printf 'AMPB_LEGACY_FIREFOX_ANDROID_REPO=%s\n' "$legacy_android_repo"
+printf 'AMPB_LEGACY_FIREFOX_ANDROID_DIR=%s\n' "$root/src/firefox-android"
+printf 'AMPB_TOR_BROWSER_BUILD_REPO=%s\n' "$tor_build_repo"
+printf 'AMPB_TOR_BROWSER_BUILD_DIR=%s\n' "$root/src/tor-browser-build"
+printf 'AMPB_GRADLE_USER_HOME=%s\n' "$root/cache/gradle"
+printf 'AMPB_MOZBUILD_STATE_PATH=%s\n' "$root/cache/mozbuild"
+printf 'AMPB_BUILD_LOG=%s\n' "$root/logs/gecko-android-mach-probe.log"
diff --git a/tools/browser-source-report.sh b/tools/browser-source-report.sh
new file mode 100644
index 0000000..2fdede1
--- /dev/null
+++ b/tools/browser-source-report.sh
@@ -0,0 +1,21 @@
+#!/bin/sh
+set -eu
+
+root="${AMPB_BROWSER_BUILD_ROOT:-/tmp/ampb-browser-build}"
+
+report_repo() {
+  label="$1"
+  path="$2"
+  if [ -d "$path/.git" ]; then
+    printf '%s_DIR=%s\n' "$label" "$path"
+    printf '%s_REMOTE=%s\n' "$label" "$(git -C "$path" remote get-url origin)"
+    printf '%s_REV=%s\n' "$label" "$(git -C "$path" rev-parse --short HEAD)"
+  else
+    printf '%s_DIR=%s\n' "$label" "$path"
+    printf '%s_STATUS=missing\n' "$label"
+  fi
+}
+
+report_repo AMPB_GECKO "$root/src/gecko-dev"
+report_repo AMPB_TOR_BROWSER_BUILD "$root/src/tor-browser-build"
+report_repo AMPB_LEGACY_FIREFOX_ANDROID "$root/src/firefox-android"
diff --git a/tools/browser-source-sync.sh b/tools/browser-source-sync.sh
new file mode 100644
index 0000000..3bf0ee6
--- /dev/null
+++ b/tools/browser-source-sync.sh
@@ -0,0 +1,40 @@
+#!/bin/sh
+set -eu
+
+root="${AMPB_BROWSER_BUILD_ROOT:-/tmp/ampb-browser-build}"
+src="$root/src"
+
+gecko_repo="${AMPB_GECKO_REPO:-https://github.com/mozilla/gecko-dev.git}"
+legacy_android_repo="${AMPB_LEGACY_FIREFOX_ANDROID_REPO:-https://github.com/mozilla-mobile/firefox-android.git}"
+tor_build_repo="${AMPB_TOR_BROWSER_BUILD_REPO:-https://gitlab.torproject.org/tpo/applications/tor-browser-build.git}"
+
+mkdir -p "$src"
+
+sync_repo() {
+  repo_url="$1"
+  dest="$2"
+  mode="$3"
+  if [ -d "$dest/.git" ]; then
+    if [ "$mode" = "blobless" ]; then
+      git -C "$dest" fetch --depth 1 --filter=blob:none origin
+    else
+      git -C "$dest" fetch --depth 1 origin
+    fi
+    git -C "$dest" reset --hard FETCH_HEAD
+  else
+    if [ "$mode" = "blobless" ]; then
+      git clone --depth 1 --filter=blob:none "$repo_url" "$dest"
+    else
+      git clone --depth 1 "$repo_url" "$dest"
+    fi
+  fi
+}
+
+sync_repo "$gecko_repo" "$src/gecko-dev" "blobless"
+sync_repo "$tor_build_repo" "$src/tor-browser-build" "normal"
+
+if [ "${AMPB_INCLUDE_LEGACY_FIREFOX_ANDROID:-0}" = "1" ]; then
+  sync_repo "$legacy_android_repo" "$src/firefox-android" "normal"
+fi
+
+printf 'AMPB_SOURCE_SYNC status=ok root=%s\n' "$root"