scripts: fresh-clone-dev-env for clean ac-workspace checkout

Shallow-bootstrap friendly script clones ac-workspace on next with recursive
submodules and SHA verification for new developer machines.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -2,5 +2,11 @@
 
 CI helpers, OTA, native codec scripts, PDF driver wrappers.
 
+| Script | Purpose |
+|--------|---------|
+| **`fresh-clone-dev-env.sh`** | Clone `ac-workspace` + all submodules on a clean machine |
+| `install-git-hooks.sh` | Project git hooks |
+
 - **Remote:** `git://f0xx.org/ac/ac-scripts`
 - **Consumed by:** `ac-deploy` (submodule), local dev
+- **Guide:** `ac-docs/docs/FRESH_ENV_CLONE.md`

fresh-clone-dev-env.sh

@@ -0,0 +1,94 @@
+#!/bin/sh
+# Clone ac-workspace + all submodules on a clean machine (branch next).
+# Usage:
+#   sh fresh-clone-dev-env.sh
+#   sh fresh-clone-dev-env.sh -d ~/projects/androidcast-ac
+#   AC_GIT_BASE=git://f0xx.org/ac AC_BRANCH=next sh fresh-clone-dev-env.sh
+set -eu
+
+AC_GIT_BASE="${AC_GIT_BASE:-git://f0xx.org/ac}"
+AC_BRANCH="${AC_BRANCH:-next}"
+TARGET="${TARGET:-${HOME}/src/androidcast-ac}"
+DO_VERIFY=1
+
+usage() {
+  sed -n '2,12p' "$0"
+  exit 0
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -d|--dir) TARGET="${2:?}"; shift 2 ;;
+    -h|--help) usage ;;
+    --no-verify) DO_VERIFY=0; shift ;;
+    *) echo "unknown arg: $1" >&2; exit 1 ;;
+  esac
+done
+
+need() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "ERROR: missing command: $1" >&2
+    exit 1
+  }
+}
+
+need git
+
+WORKSPACE_URL="${AC_GIT_BASE}/ac-workspace"
+log() { printf '[fresh-clone] %s\n' "$*"; }
+die() { log "ERROR: $*"; exit 1; }
+
+log "git base=${AC_GIT_BASE} branch=${AC_BRANCH} target=${TARGET}"
+
+if [ -d "${TARGET}/.git" ]; then
+  log "existing clone at ${TARGET} — fetch + submodule sync"
+  git -C "$TARGET" fetch origin
+  git -C "$TARGET" checkout "$AC_BRANCH"
+  git -C "$TARGET" pull --ff-only origin "$AC_BRANCH" 2>/dev/null \
+    || git -C "$TARGET" reset --hard "origin/${AC_BRANCH}"
+else
+  mkdir -p "$(dirname "$TARGET")"
+  log "clone ${WORKSPACE_URL} → ${TARGET}"
+  git clone --branch "$AC_BRANCH" --single-branch "$WORKSPACE_URL" "$TARGET"
+fi
+
+cd "$TARGET"
+git submodule sync --recursive
+log "submodule update --init --recursive (may take a few minutes)"
+git submodule update --init --recursive
+
+EXPECTED="$(grep -c '^\[submodule ' .gitmodules 2>/dev/null || echo 0)"
+FOUND="$(find . -maxdepth 1 -type d -name 'ac-*' 2>/dev/null | wc -l | tr -d ' ')"
+log "submodule dirs: found=${FOUND} expected≈${EXPECTED}"
+
+if [ "$DO_VERIFY" -eq 0 ]; then
+  log "done (verify skipped)"
+  exit 0
+fi
+
+FAIL=0
+git submodule foreach --recursive '
+  if [ ! -e .git ] && [ ! -f .git ]; then
+    echo "[fresh-clone] FAIL missing git metadata: $sm_path" >&2
+    exit 1
+  fi
+' || FAIL=1
+
+log "revision summary:"
+git submodule foreach --quiet '
+  printf "  %-28s %s  %s\n" "$sm_path" "$(git rev-parse --short HEAD 2>/dev/null)" "$(git remote get-url origin 2>/dev/null)"
+'
+
+WS_SHA="$(git rev-parse --short HEAD)"
+log "ac-workspace @ ${WS_SHA}"
+
+if [ "$FAIL" -ne 0 ]; then
+  die "submodule verification failed — re-run: git submodule update --init --recursive"
+fi
+
+if [ "$FOUND" -lt "$((EXPECTED - 1))" ]; then
+  die "expected ~${EXPECTED} ac-* dirs, found ${FOUND}"
+fi
+
+log "OK fresh clone ready at ${TARGET}"
+log "next: read ac-docs/docs/FRESH_ENV_CLONE.md and ac-docs/docs/SECRETS_AND_RECOVERY.md"