chore: 🤖 add build monitor

scripts/common/logging.sh

@@ -38,15 +38,46 @@ _LOG_FILE="${_LOGS_DIR}/${_TIMESTAMP}.log"
 
 mkdir -p "${_LOGS_DIR}"
 
+# Optionally drive the live progress dashboard in this terminal (the re-exec'd build
+# below has its stdout redirected to the log, so THIS process — which still owns the
+# TTY — is the one that can paint it). Opt-in: a build script sets KICAD_MONITOR=1
+# before sourcing this file. Skipped for non-interactive stdout or KICAD_NO_MONITOR=1.
+_MONITOR="${_PROJECT_ROOT}/scripts/build-monitor.sh"
+_USE_MONITOR=0
+if [[ "${KICAD_MONITOR:-0}" == "1" ]] && [[ -z "${KICAD_NO_MONITOR:-}" ]] \
+   && [[ -t 1 ]] && [[ -x "${_MONITOR}" ]]; then
+    _USE_MONITOR=1
+fi
+
 # Show log path before re-exec
 echo "Logging to: ${_LOG_FILE}"
+# Only suggest the manual command when we're NOT auto-launching the dashboard.
+[[ ${_USE_MONITOR} -eq 0 ]] && \
+    echo "Watch progress: ${_MONITOR} --dir ${_SCRIPT_NAME}"
 
 # Run the calling script with output redirected
 # This is equivalent to: ./script.sh > logfile 2>&1
 # and reliably captures ALL output including docker compose TTY messages
 export KICAD_LOG_NESTED=1
-"${_CALLER_SCRIPT}" "$@" > "${_LOG_FILE}" 2>&1
-_EXIT_CODE=$?
+export KICAD_LOG_FILE="${_LOG_FILE}"   # let the build body know its own log path
+
+if [[ ${_USE_MONITOR} -eq 1 ]]; then
+    : > "${_LOG_FILE}"                            # create now so the follower has a file
+    "${_MONITOR}" "${_LOG_FILE}" &                # live dashboard on this terminal
+    _MON_PID=$!
+    # Tear down the dashboard if the user interrupts the build.
+    trap 'kill ${_MON_PID} 2>/dev/null' INT TERM
+    "${_CALLER_SCRIPT}" "$@" >> "${_LOG_FILE}" 2>&1
+    _EXIT_CODE=$?
+    # The build body's EXIT trap writes the done/failed marker, so the monitor paints
+    # its final frame in place and self-exits — no separate redraw needed (which would
+    # otherwise print the frame a second time).
+    wait "${_MON_PID}" 2>/dev/null
+    trap - INT TERM
+else
+    "${_CALLER_SCRIPT}" "$@" > "${_LOG_FILE}" 2>&1
+    _EXIT_CODE=$?
+fi
 
 # Print completion message (this runs AFTER the script finishes)
 if [[ ${_EXIT_CODE} -eq 0 ]]; then

scripts/common/stages.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Emit machine-parseable build-progress markers into the log stream.
+#
+# All build output is captured by logging.sh into logs/<script>/<ts>.log, and
+# scripts/build-monitor.sh parses these @KW@ lines to render live progress.
+# These are plain printf so they work identically on the host (docker/build.sh)
+# and inside `docker compose exec` (build-kicad-target.sh, build-wxuniversal-wasm.sh):
+# the container's stdout flows back through build.sh's redirected stdout into the
+# same host log, so a single log is the source of truth for the whole build.
+#
+# Each marker carries an epoch timestamp so the monitor can reconstruct per-stage
+# elapsed time even when it attaches mid-build or runs --once on a finished log.
+#
+# Marker grammar (one per line):
+#   @KW@ <epoch> stage  <key>
+#   @KW@ <epoch> app    <name> <index> <total>
+#   @KW@ <epoch> done
+#   @KW@ <epoch> failed <exit_code>
+#
+# The monitor owns human-readable labels (key -> label), so keys stay terse here.
+
+kw_stage() { printf '@KW@ %s stage %s\n' "$(date +%s)" "$1"; }
+kw_app()   { printf '@KW@ %s app %s %s %s\n' "$(date +%s)" "$1" "$2" "$3"; }
+kw_done()  { printf '@KW@ %s done\n' "$(date +%s)"; }
+kw_fail()  { printf '@KW@ %s failed %s\n' "$(date +%s)" "${1:-1}"; }